MagCluster

English | 中文说明

MagCluster is a tool for finding, annotating, and visualizing magnetosome gene clusters (MGCs) in bacterial genomes.

What's New in v1.0

• One command: magcluster run runs everything from gene prediction to cluster visualization in a single step.
• No Prokka needed: gene calling is handled natively by Pyrodigal (fast, no Perl or external setup).
• 92 HMM profiles: curated protein HMMs covering 8 magnetosome families (Mam, Mms, Mad, Man, Mae, Maq, Mca, Feo), searched using PyHMMER.
• Flexible inputs: accepts GenBank (.gbk/.gbff), nucleotide FASTA contigs (.fasta/.fna/.fa), and protein FASTA (.faa), including .gz compressed files.
• Per-genome outputs: writes separate {genome}_mgc_genes.tsv and {genome}_magnetosome_proteins.faa files for each genome.

Installation

1. Create a Conda environment (recommended)

conda create -n magcluster-1.0 -c conda-forge -c bioconda python=3.12 pip
conda activate magcluster-1.0

2. Install MagCluster

From GitHub:

pip install git+https://github.com/RunJiaJi/magcluster.git

Or from local source:

git clone https://github.com/RunJiaJi/magcluster.git
cd MagCluster
pip install -e .

Verify the installation:

magcluster --version
magcluster run --help

Quick Start

1. Annotated GenBank file (.gbff / .gbk)

magcluster run genome.gbff -o results/

2. Unannotated FASTA contigs (.fasta / .fna / .fa)

MagCluster automatically predicts genes and uses all CPU cores by default:

magcluster run contigs.fasta -o results/ -t 8

3. Multiple genomes in a folder

magcluster run genomes_dir/ -o results/

4. Protein FASTA (.faa)

Note if your input contains protein sequences without coordinates, MagCluster will annotate magnetosome proteins and output TSV table and FASTA files without plotting the gene cluster:

magcluster run proteins.faa -o results/

5. Overwrite an existing output folder

magcluster run genome.gbff -o results/ --force

Commands & Options

magcluster run

magcluster run [OPTIONS] INPUTS...

magcluster db

View the built-in reference database, the 10 core defining families, and all 92 HMM profiles sorted by sequence count:

magcluster db

Output Files

Running magcluster run <inputs> -o results/ produces:

results/
├── {genome}_mgc_genes.tsv              # Table of all identified magnetosome genes
├── {genome}_magnetosome_proteins.faa   # Extracted magnetosome protein sequences
├── MGC_align.html                      # Interactive gene cluster map (open in browser)
└── clusters_gbk/                       # Sliced GenBank file for each cluster
    └── {cluster_id}.gbk

1. Gene table ({genome}_mgc_genes.tsv)

2. Protein sequences ({genome}_magnetosome_proteins.faa)

Amino acid sequences of all magnetosome proteins found in that genome, with detailed header info:

>MGMSRV2_RS11765 [MSR-1_genome] cluster=MSR-1_genome_MGC family=MamE profile=MamE_full score=1000.4 evalue=1.97e-301
MSERRPVGRTL...

3. Interactive visualization (MGC_align.html)

Open this file in your webbrowser:

• Gene labels: Arrows show specific domain annotations like MamE_Cter, MamE_Nter, and MamQ_greigite.
• Family colors:
  • Red: mam family
  • Yellow: mms family
  • Green: mad family
  • Blue: man family
  • Gold: feo family
  • Purple: mae family
  • Teal: maq family
  • Pink: mca family
  • Grey: Other neighboring non-magnetosome genes
• Customizable: Drag genes, change colors, re-align, and export publication-ready SVG figures directly from the browser.

Helpful Tips

Faster Clinker plotting on large datasets

Pairwise sequence alignments between large clusters can take time. Use --clinker-opts to speed it up:

# Skip pairwise sequence alignment:
magcluster run *.gbff -o results/ --clinker-opts "-na"

# Keep the original file order instead of automatic reordering:
magcluster run *.gbff -o results/ --clinker-opts "-ufo"

# Both:
magcluster run *.gbff -o results/ --clinker-opts "-na -ufo"

To see all Clinker visualization options, run:

magcluster run --clinker-help

Core Magnetosome Families

MagCluster considers an MGC authentic if it contains at least 3 distinct magnetosome families. The 10 core defining families are:

$$\text{MamA, MamB, MamE, MamI, MamK, MamL, MamM, MamO, MamP, MamQ}$$

Citation

If you use MagCluster, please cite:

Runjia Ji, Wensi Zhang, Yongxin Pan, and Wei Lin. (2022).
MagCluster: a Tool for Identification, Annotation, and Visualization of Magnetosome Gene Clusters.
Microbiology Resource Announcements, 11:e01031-21.
https://doi.org/10.1128/mra.01031-21

Dependencies used by MagCluster:

• Pyrodigal: doi:10.21105/joss.04296
• PyHMMER: doi:10.1093/bioinformatics/btad211
• Clinker: doi:10.1093/bioinformatics/btab007

Contact

Questions or suggestions? Feel free to reach out:

• GitHub Issues: Open an issue
• Email: Runjia Ji (jirunjia@gmail.com) or Wei Lin (weilin@mail.iggcas.ac.cn)