Metadata-Version: 2.4
Name: mtasemotif
Version: 0.2.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.

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

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