🧬 MODIFI: DNA Modification Detection and ECE-host linkage inference from PacBio Metagenomic Data

MODIFI is a software package for detecting DNA base modifications and inferring host–mobile genetic element (MGE) linkages from PacBio metagenomic sequencing data. It enables precise modification calling, motif discovery, and host–MGE association in complex microbial communities, supporting both subreads and HiFi read types.

• How it works
• Installation
• Quick Start
• Detailed Usage
• Complete Metagenomics Workflow
• Linkage-only mode
• Command-line options
• Output Files
• Control Database
• Important Notes
• Citation
• Getting Help

MODIFI expects a PacBio BAM with IPD kinetics and a reference FASTA (metagenome assembly or isolate). If you pass an unaligned BAM, reads are aligned with pbmm2 while preserving kinetic tags. The pipeline splits work by contig, optionally accumulates control k-mer IPD statistics (from the same run or external databases), and normalizes sample IPDs against those controls. It then calls modifications, discovers motifs, and builds per-contig methylation profiles. With an MGE table (e.g. from geNomad) and optionally a binning file, it merges motif evidence and scores host–MGE linkages. Typical outputs are motif calls, strand-specific profiles, base-level GFF annotations, and host_summary.csv when linkage is enabled.

conda create -n modifi -c bioconda modifi
conda activate modifi

If SMRT tools are installed in your system PATH, MODIFI will detect and use them automatically; otherwise, it defaults to its built-in alternatives.

git clone https://github.com/sachdevalab/MODIFI.git
cd MODIFI/
conda env create -n modifi -f env.yml
conda activate modifi
pip install .

You can set your SMRT Link tools path here. You can also skip this step.

Configuration priority (in order):

1. Config file first – MODIFI will use the path specified in smrt.config.yaml
2. System PATH – If smrt.config.yaml is not found or incomplete, MODIFI checks system PATH
3. Built-in alternative – Use built-in MultiMotifMaker and pbmm2 as fallback

To configure via smrt.config.yaml (only if needed):

Edit smrt.config.yaml in the MODIFI directory:

smrtlink_bin: /path/to/smrtlink/private/bin/

Test that the command-line entry point is available:

modifi --help

Run the built-in HiFi test dataset with a single command (works after either a Bioconda or a from-source install, with nothing to edit):

modifi-test

modifi-test creates a modifi_test/ folder in your current directory and writes the results to modifi_test/output/. It also copies a reference profile next to them at modifi_test/expected_motif_profile.csv.

Working inside a cloned repo? You can also run the script directly: cd test/hifi/ && bash test_hifi.sh (results then land in test/hifi/output/).

When modifi-test finishes, modifi_test/output/ holds the standard MODIFI results, including:

• summary.csv, all.motifs.merged.csv, motif_profile.csv, mean_depth.csv
• motif_heatmap.pdf
• per-genome folders gffs/, motifs/, profiles/

See the Output Files section below for what each of these means.

To confirm your run looks right, compare your modifi_test/output/motif_profile.csv against the bundled reference modifi_test/expected_motif_profile.csv. The two list the same motifs with matching per-contig modification fractions.

Subreads support requires pbcore, which only installs in a separate environment (Python 3.9, numpy 1.22.4). It is therefore available with the from-source install below, not with the Bioconda package (which is HiFi-only). Set it up from a cloned repo:

conda env create -n MODIFI_subreads -f subreads.env.yml
conda activate MODIFI_subreads
pip install git+https://github.com/PacificBiosciences/pbcore.git
pip install .

To verify subreads support, run the bundled subreads test from inside the repo:

cd test/subreads/
bash test_subreads.sh

Results are written to test/subreads/output/. To confirm the run looks right, compare your test/subreads/output/motif_profile.csv against the committed reference test/subreads/expected_motif_profile.csv (the two list the same motifs with matching per-contig modification fractions). See the Output Files section below for what each output file means.

MODIFI supports both HiFi reads and subreads. Your PacBio BAM file must contain kinetics (IPD) tags:

⚠️ Important:

• FASTQ files do not contain kinetics information and cannot be used
• The BAM file stores kinetic information; it does not need to be pre-aligned
• See PacBio BAM format specifications for details
• Reference should be indexed using samtools faidx before running.

Run MODIFI with unaligned BAM containing kinetics:

samtools faidx assembly.fasta 
modifi \
    -o /path/to/output \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi

MODIFI will automatically align reads using pbmm2:

modifi \
    -o /path/to/output \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi

If already aligned with pbmm2 (with kinetics preserved):

modifi \
    -o /path/to/output \
    --aligned_bam aligned.sorted.bam \
    -r assembly.fasta \
    --read_type hifi

For subread data (requires MODIFI_subreads environment):

modifi \
    -o /path/to/output \
    -b raw.subreads.bam \
    -r assembly.fasta \
    --read_type subreads

Provide an MGE table to automatically infer MGE-host linkages:

modifi \
    -o /path/to/output \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi \
    --mge_file MGE_list.tab

MGE table format: Tab-separated file with at least a seq_name column. Can be output from geNomad or manually created:

seq_name	length	topology	n_genes	genetic_code	plasmid_score	fdr
ERR6535514_2_L	6291	DTR	8	11	0.9997	0.0003
...

💡 Tip: Once motif detection has finished, you can re-run linkage only using the modifi-linkage helper instead of the full pipeline (see Linkage-only mode).

Assign MGEs to host bins using binning results:

modifi \
    -o /path/to/output \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi \
    --mge_file MGE_list.tab \
    --bin_file binning.tab

Bin file format: Tab-separated, two columns (no header): contig name and bin name

scaffold_53	maxbin.017
scaffold_66	maxbin.017
scaffold_73	maxbin.017
...

For isolate genomes or low-complexity metagenomes, use a control database for better normalization.

modifi \
    -o /path/to/output \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi \
    --kmer_mean_db control/control_db.up7.down3.mean.dat \
    --kmer_num_db control/control_db.up7.down3.num.dat

Use control database from your own high-complexity metagenome runs (automatically generated in <output>/control/):

control/control_db.up7.down3.mean.dat
control/control_db.up7.down3.num.dat

End-to-end example from MGE prediction to host linkage inference.

Prerequisites:

• Raw PacBio BAM with kinetics
• Metagenomic assembly (FASTA)

genomad end-to-end \
    --relaxed \
    --cleanup \
    --enable-score-calibration \
    --threads 32 \
    --sensitivity 7.0 \
    --force-auto \
    assembly.fasta \
    output/genomad/ \
    /path/to/genomad_db

cat output/genomad/assembly_summary/assembly_virus_summary.tsv \
    output/genomad/assembly_summary/assembly_plasmid_summary.tsv \
    > all_MGEs.tsv

modifi \
    -o output/MODIFI \
    -b raw.hifi_reads.bam \
    -r assembly.fasta \
    --read_type hifi \
    --mge_file all_MGEs.tsv \
    --threads 32

Note: Proviruses are automatically excluded from analysis.

If you have already run MODIFI and generated motif profiles in a given -o, you can re-run just the MGE-host linkage step (for example, with a different MGE table or binning file) without re-running modification detection:

modifi-linkage \
    -o /path/to/output \
    -r assembly.fasta \
    --mge_file all_MGEs.tsv \
    --bin_file binning.tab \
    --threads 32

For the full, up-to-date list of arguments and defaults:

modifi --help
modifi-linkage --help

All modifi options, matching modifi --help:

File: motifs/*.motifs.csv

File: host_summary.csv

Filtering recommendations:

• General: final_score > 0.5 AND specificity < 0.01
• Very high confidence: final_score > 0.8 AND specificity < 0.001

Files: gffs/*.reprocess.gff

Standard GFF3 format with 9 columns:

Files: figs/*.png (generated with --visu_ipd)

2×2 subplot grid showing IPD normalization:

For isolate genomes or low-complexity metagenomes, using a control database improves IPD normalization and modification calling accuracy.

MODIFI includes a pre-built control database:

control/control_db.up7.down3.mean.dat
control/control_db.up7.down3.num.dat

Use with --kmer_mean_db and --kmer_num_db flags (see Using Control Databases).

For better results, generate a control database from your own high-complexity metagenomes:

1. Run MODIFI on high-complexity metagenomic samples
2. Control files are automatically generated in <output>/control/
3. Reuse these files for isolate/low-complexity samples

• The k-mer window size (e.g., up7.down3) must match between sample and control
• Control database accumulates more accurate statistics with larger/more diverse datasets
• Recommended for: isolates, enriched cultures, low-diversity communities

In 59 metagenomics from nine habitats, the mean wall-clock time was 4.5 hours (range: 0.2–19 hours, std: 3.9), while the mean CPU time was 120 hours (range: 1–1,161 hours, std: 215), with a mean peak memory usage of 18 GB (range: 0.6–62 GB, std: 14).

• Coverage >500× is automatically subsampled for computational efficiency
• For large metagenomes, use --threads to parallelize processing
• --segment flag increases recall for low-depth contigs but requires more time

Driver scripts and plotting code used for analyses in development live under benchmark/.

• Use HiFi reads instead of subreads when possible (better accuracy, faster)
• Use control database for isolate genomes and low-complexity samples
• Filter MGE-host linkages: final_score > 0.5 and specificity < 0.01

If you use MODIFI in your research, please cite:

Metagenomic strain-resolved DNA modification patterns link extrachromosomal genetic elements to host strains Shuai Wang, Allison K. Guitor, Luis E. Valentin-Alvarado, Rebecca Garner, Pengfan Zhang, Ming Yan, Ling-Dong Shi, Marie C. Schoelmerich, Holly M. Steininger, Daniel M. Portik, Siyuan Zhang, Jeremy E. Wilkinson, Susan Lynch, Michael J. Morowitz, Matthias Hess, Spencer Diamond, Jillian F. Banfield, Rohan Sachdeva bioRxiv 2026.03.27.714056; doi: https://doi.org/10.64898/2026.03.27.714056

For questions or bug reports:

• 📧 Email: wshuai@berkeley.edu
• 🐛 GitHub Issues: open an issue in this repository

We’ll respond as soon as possible.