mtase-motif

mtase-motif finds bacterial DNA methyltransferase (MTase) candidates in a genome and assigns recognition motifs from annotated homologs.

The default sequence-first workflow combines:

1. Prodigal gene prediction, unless a protein FASTA is supplied.
2. HMMER searches against a curated Pfam subset and optional TIGRFAMs models.
3. MMseqs2 or BLAST+ searches against motif-labeled REBASE proteins.
4. Conservative motif transfer with explicit provenance and confidence.

When experimental motifs are already known but their enzymes are not, the optional motif-first reverse-linking workflow ranks genome candidates against characterized REBASE MTases. Type III calls can also use separate M-subunit and neighboring R-subunit evidence. The sequence-first stages still run, and their default behavior is unchanged unless --known-motifs is supplied.

The important scientific boundary is that motif assignment is homology-based. A genome alone usually does not contain enough information to determine an MTase recognition motif de novo. Candidates without adequate reference or methylation evidence are reported as unresolved; they are not given a fabricated motif.

Installation

The Python package supports Python 3.10 or newer:

python -m pip install mtasemotif
mtase-motif --version

Native tools are installed separately. A source checkout includes a conda environment with the tools needed for the core workflow:

git clone https://github.com/lrslab/mtasemotif.git
cd mtasemotif
conda env create -f environment.yml
conda activate mtase
python -m pip install .

Core runs require Prodigal when proteins are not supplied, HMMER, and either MMseqs2 or BLAST+. FIMO and TIGRFAMs are optional.

Database setup

Downloaded databases are not bundled in the wheel or source distribution. The default database directory is ~/.cache/mtase-motif/db.

mtase-motif db init
mtase-motif db fetch pfam
mtase-motif db fetch rebase
mtase-motif db index
mtase-motif db status

The default REBASE fetch uses a compact motif-labeled protein set plus REBASE withref records for exact methylation types (for example, Dam/GATC as m6A). It also attempts to stage role-specific expanded protein sets used only when --known-motifs is supplied; these do not enlarge the routine whole-proteome search. Database caches created before version 0.3.0 must fetch REBASE again and rebuild their indexes before motif-first reverse linking can be used:

mtase-motif db fetch rebase
mtase-motif db index

Local Pfam or REBASE mirrors can be imported with --source:

mtase-motif db fetch pfam --source /path/to/Pfam-A.hmm.gz
mtase-motif db fetch rebase --source /path/to/rebase_directory
mtase-motif db index

TIGRFAMs is optional and local-source-only:

mtase-motif db fetch tigrfams --source /path/to/TIGRFAMs.hmm.gz
mtase-motif db index

See the database setup guide for offline REBASE protein requirements and the local database layout.

Pfam, TIGRFAMs, and REBASE remain third-party resources. No downloaded records are redistributed by this package; users are responsible for their respective access, license, and citation requirements.

Quick start

Check the genome, database, and native tools before starting:

mtase-motif doctor --genome genome.fna

Add --json for a machine-readable report and inspect its top-level ok and issues fields before launching a long run.

Run the complete sequence-first workflow:

mtase-motif run \
  --genome genome.fna \
  --out results/genome \
  -j 4

Use --db-dir with every database and run command when using a non-default database location. If proteins are already available, skip Prodigal:

mtase-motif run \
  --genome genome.fna \
  --proteins proteins.faa \
  --db-dir databases/mtase-motif \
  --out results/genome \
  -j 4

Supplying a protein FASTA skips gene prediction, but the current interface does not accept matching genomic coordinates. Neighborhood evidence is therefore unavailable for that mode; prefer the genome-only route when Type I system context is important.

The default balanced motif profile is appropriate for routine use. The sensitive profile admits more remote REBASE family evidence:

mtase-motif run \
  --genome genome.fna \
  --out results/genome-sensitive \
  --motif-sensitivity sensitive

Outputs

The output layout separates the routine result from audit-level detail:

candidate_id links results.tsv to candidate-oriented detail rows. details/known_motif_links.tsv is instead organized by observed motif; it may contain several candidate rows per motif or a blank candidate for an unresolved motif. results.tsv is the table to use for routine analysis; the detail tables explain discovery evidence and every assignment route. Internal files under work/ are deleted after a successful validation; use --keep-work only when debugging. The CLI validates IDs, ranks, and summary counts across the public outputs before reporting success.

For methylation fields, methylation is the normalized class (m6A, m5C, or m4C), and mod_position is 1-based within the displayed motif. methylation_source and mod_position_source explain how the main call was obtained. Raw REBASE notation such as 2(6) and conflict details remain in the assignment audit table. Named Dam/Dcm fallback is used only when both the enzyme name and its canonical motif agree. With no experimental support input, the main support state is not_provided; count and fraction columns are not added to the main table.

See the output schema for the table relationships, field definitions, controlled values, and null semantics.

Optional evidence

Motif-first reverse linking

When the motifs have already been measured but their enzymes are unknown, provide a motif-first TSV:

known_motif_id	motif_iupac	methylation	mod_position	source
motif_1	CGAAG	m6A		experiment
motif_2	CATCTC	m6A	2	experiment

The input file is UTF-8 and tab-delimited, with one motif per row. The preferred exact, lower-case header is motif_iupac, and a minimal file can contain that single column. Compatibility aliases are documented in the full guide. methylation is m6A, m5C, or m4C, and mod_position is a plain 1-based integer within the displayed motif. Leave either field empty when it is unknown. Ready-to-run examples are provided for AP1 and E. coli. Run:

mtase-motif run \
  --genome genome.fna \
  --known-motifs known_motifs.tsv \
  --out results/genome-known \
  -j 4

This writes details/known_motif_links.tsv, with ranked genome candidates for each observed motif. Exact or compatible motif agreement and strong full-length protein homology provide the primary evidence. A nearby independently detected Type III R subunit can raise a Type III M link to high confidence. A one-position motif difference is capped at medium confidence, close candidates remain ambiguous, and a candidate already strongly assigned to another known motif is penalized. Only a unique linked/high result can replace a sequence-first primary call; medium and ambiguous links remain hints. The link score is a ranking heuristic, not a probability. See the known-motif linking guide for details.

Methylation support

Provide a normalized support table to validate sequence-derived calls:

mtase-motif run \
  --genome genome.fna \
  --out results/genome \
  --methylation-support methylation_support.tsv

The table requires motif_iupac plus methylated and unmethylated instance counts. Candidate-specific evidence may rescue unresolved calls only when --methylation-rescue-unresolved is explicitly enabled.

Hammerhead motif output can be converted to this schema:

mtase-motif convert-hammerhead-support \
  --motifs-tsv motifs.tsv \
  --out-tsv methylation_support.tsv

Motif loci

Add --list-loci to scan the genome for resolved motifs and write FIMO and QC outputs plus details/motif_loci.tsv. The detail table still contains one row per candidate; unresolved candidates receive a blank motif, zero counts, and a no_motif warning. This requires FIMO from the MEME suite.

Retaining intermediates

Successful runs remove the large internal work/ directory by default. Keep it for troubleshooting with:

mtase-motif run \
  --genome genome.fna \
  --out results/genome \
  --keep-work

Development and release checks

python -m pip install -e '.[dev]'
make lint
make test
make package-check

Releases are built by GitHub Actions from tags matching the package version. After updating mtase_motif.__version__ and CHANGELOG.md, create a tag such as vX.Y.Z. The workflow verifies the tag, builds the wheel and source distribution, publishes through PyPI Trusted Publishing, and then creates the GitHub release using the matching CHANGELOG.md section as its release notes.

License

The package source is released under the MIT License. Downloaded third-party database content is not covered by this license and is not bundled.