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.

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). 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 every generated detail table. results.tsv is the table to use for routine analysis; the candidate and assignment 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 candidate IDs 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

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.