mgnifam

Iterative HMM-based protein family generation over very large sequence databases.

Given a chunk of MMseqs2 clusters and a protein FASTA, mgnifam generate_families builds an HMM from each cluster, recruits new members from the whole database, re-aligns, and either converges on a family or discards the cluster. It is the core algorithm of the mgnifams Nextflow pipeline, extracted into a standalone, tested package.

Documentation: vagkaratzas.github.io/mgnifam

Install

pip install mgnifam        # or: uv tool install mgnifam

Or from bioconda, into its own environment:

conda create -n mgnifam -c conda-forge -c bioconda mgnifam
conda activate mgnifam

Channel order matters — put conda-forge before bioconda, per the bioconda setup. The package is noarch, and conda pulls in a Python 3.13 interpreter itself, so it does not have to be the one already on your PATH. mamba/micromamba work the same way with the same flags.

Requires Python >= 3.13. Verify with mgnifam --version.

To work on the package itself, or to reproduce published results byte-for-byte, install from the repository against the committed lockfile instead — see Reproducibility, which is scoped to that resolved dependency set:

git clone https://github.com/vagkaratzas/mgnifam && cd mgnifam
uv sync --frozen

Quick start

Build families from a chunk of clusters:

mgnifam generate_families \
    --clusters_chunk clusters.tsv \
    --fasta_file mgnifams_input.fa

Refresh existing families against a new release:

mgnifam update_families \
    --hmm_input previous_output/hmm \
    --fasta_file new_release.fa

--fasta_file must be an uncompressed FASTA with unique sequence names. Pass every threshold explicitly on a production run.

The documentation covers the rest:

• Generating families: input formats, sequence naming, every flag, and sharing one SSI index across chunks
• Updating families: --skip_refine, family identity, and retrying a chunk in place
• Outputs: every file, exit status, and the MultiQC summary
• Reproducibility: what is byte-identical, and how outputs differ from the legacy script
• Python API

Development

uv lock --check && uv sync --frozen
uv run pre-commit install
uv run pre-commit run --all-files
uv run pytest

The documentation site lives in docs/; see Development to build it.