Metadata-Version: 2.4
Name: mtasemotif
Version: 0.3.0
Summary: Fast MTase discovery and homology-based motif inference from microbial genomes
Home-page: https://github.com/lrslab/mtasemotif
Author: LRSLab
License: MIT
Project-URL: Source, https://github.com/lrslab/mtasemotif
Project-URL: Issues, https://github.com/lrslab/mtasemotif/issues
Project-URL: Changelog, https://github.com/lrslab/mtasemotif/blob/main/CHANGELOG.md
Keywords: bioinformatics,methylation,genomics,dna
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```bash
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`.

```bash
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:

```bash
mtase-motif db fetch rebase
mtase-motif db index
```

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

```bash
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:

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

See the [database setup guide](https://github.com/lrslab/mtasemotif/blob/main/docs/database_setup.md)
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

| File | Contents |
| --- | --- |
| `results.tsv` | Compact main result; exactly one row and 25 analysis-ready columns per MTase candidate |
| `details/mtase_candidates.tsv` | Candidate-discovery audit table; exactly one row per candidate |
| `details/motif_assignments.tsv` | Assignment evidence; one or more rows per candidate for primary, alternate, hint, or unresolved routes |
| `details/methylation_support.tsv` | Experimental counts and confidence effects; generated only with `--methylation-support` |
| `details/known_motif_links.tsv` | Ranked motif-to-enzyme evidence; generated only with `--known-motifs` |
| `details/motif_loci.tsv` | Motif counts and density; generated only with `--list-loci` |
| `run_manifest.json` | Schema/software versions, privacy-safe input hashes, database version, parameters, tool versions, relative outputs, and summary counts |
| `artifacts/<candidate_id>/motif/pwm.meme` | MEME-format PWM for each candidate |

`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](https://github.com/lrslab/mtasemotif/blob/main/docs/output_schema.md)
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:

```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](https://github.com/lrslab/mtasemotif/blob/main/examples/ap1_known_motifs.tsv)
and
[*E. coli*](https://github.com/lrslab/mtasemotif/blob/main/examples/ecoli_known_motifs.tsv).
Run:

```bash
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](https://github.com/lrslab/mtasemotif/blob/main/docs/known_motif_linking.md)
for details.

### Methylation support

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

```bash
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:

```bash
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:

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

## Development and release checks

```bash
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](LICENSE). Downloaded
third-party database content is not covered by this license and is not bundled.
