MATPredict

Find and type the mating-type (MAT) loci of fungi in genome assemblies.

MATPredict searches a genome assembly with a curated reference database of MAT loci. It reports where each locus is, which genes it carries, and which idiomorph or mating type it is (for example Plus/Minus, MAT1-1/MAT1-2, HD/PR alleles). Every reference record traces to a publication or a validated deposit, and every call reports the evidence behind it.

Current release: v0.6.1. Changes: CHANGELOG.md.

• Project goals
• Workflow
• Supported lineages
• Curation process
• Repository layout
• Quickstart
• Usage
• Validation and known limits
• Authors
• Citation
• License

1. Curated reference loci. Develop a curated set of model MAT loci for different taxonomic groups, one record per strain and idiomorph, with provenance for every gene.
2. Detection. Use translated searches to find the key MAT genes and their flanking genes in new genome assemblies, annotated or not.
3. Typing. Classify each locus by the mating-type naming scheme of its group (for example Plus/Minus, MAT1-1/MAT1-2, HD/PR alleles), and report when the evidence is not enough to decide.
4. Standard reports. Extract the locus region and its genes, and report them in a standard format with figures and tables. Report uncalled genomes with a reason, and two idiomorphs in one genome as a flag for review.
5. Synteny. Visualize the synteny of MAT regions across sets of species.
6. Scale. Run on thousands of genomes (for example the full BFD fungal genome collection) on a SLURM cluster.

                 genome assembly (FASTA)  [+ proteins]  [+ NCBI taxid]
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────┐
 │ 1. ROUTE      taxid lineage ──► curated families in db/<Phylum>/      │
 │               order.yml. No match ──► phylum fallback, or             │
 │               "not_searched". --phylum forces one phylum.             │
 ├──────────────────────────────────────────────────────────────────────┤
 │ 2. SEARCH     tblastn (genome) / diamond (proteome) with the          │
 │               reference proteins: core MAT genes + flanking genes     │
 ├──────────────────────────────────────────────────────────────────────┤
 │ 3. CLUSTER    hits ──► candidate loci per contig (lineage gap rules)  │
 ├──────────────────────────────────────────────────────────────────────┤
 │ 4. POLISH     exonerate / miniprot gene models on a sliced window     │
 │               (at most 6 loci per family)                             │
 ├──────────────────────────────────────────────────────────────────────┤
 │ 5. GATE       modelled-gene bar, fraction floor, MAT-gene gate,       │
 │               flank-carried rule, paralog class, CAAX check           │
 ├──────────────────────────────────────────────────────────────────────┤
 │ 6. TYPE       idiomorph from gene content, or profile-HMM classifier  │
 │               (Mucoromycota sexP/sexM); margin and confidence tier    │
 └──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
     detection_report.yaml   detected_loci.gff3   [detected_loci.fasta]
     (calls, evidence, withheld loci, uncalled reason, two-idiomorph flag)

The reference database feeds steps 1, 2 and 6:

 literature / GenBank deposit
        │  propose (PMID/DOI + source text required)
        ▼
 db/candidates/ ──► automated validation ──► curator sign-off ──► db/<Phylum>/<Order>/
                    (accession resolves,       (accept or          locus.gbk, locus.gff3,
                     translation matches,       reject with         proteins.faa,
                     taxonomy current)          a reason)           metadata.yaml
                                                                         │
                                         classifiers, regression check ◄─┘

The curated families are defined in each phylum's order.yml.

Other phyla (for example Mortierellomycota, Kickxellomycota, Chytridiomycota) have no curated family. By default their genomes are reported as not_searched. Use --exhaustive to search them with every family.

Each reference record is a folder db/<Phylum>/<Order>/<record_id>/ with four files. The record id is <taxid>_<strain>_<locus>_<idiomorph>.

Rules:

1. Evidence. Tier 1: a published and experimentally validated locus. Tier 2: genome-derived coordinates, admitted only with extra checks (domain evidence, alignment to curated orthologs, or a gene tree) and a record of how the locus was derived. A source never comes from inference alone.
2. Proposal. A candidate record goes to db/candidates/ with a resolvable PMID/DOI or accession and the exact source text.
3. Automated validation. The accession must resolve, the translation must match the cited protein, and the taxonomy must be current.
4. Curator sign-off. Only the curator moves a record to accepted. Rejected candidates are kept with a reason.
5. Regression check. A change to a record, classifier or rule runs the regression panel before sign-off. See docs/regression-check.md.

Related files:

MATPredict uses pixi for its environment. The environment holds Python, BLAST+, DIAMOND, miniprot, exonerate, Augustus, pyhmmer, MAFFT and the drawing tools. Linux (x86-64) only.

git clone https://github.com/stajichlab/MATPredict.git
cd MATPredict
pixi install
pixi run matpredict --help

Docker. Each release publishes an image to the GitHub Container Registry. The image holds the environment, the package, the curated database and an NCBI taxonomy snapshot (see Offline taxonomy), so a run needs no network.

docker pull ghcr.io/stajichlab/matpredict:latest     # or a release version, :<version>
docker run --rm -v "$PWD":/data \
  ghcr.io/stajichlab/matpredict:latest \
  detect --genome /data/genome.fna --taxid 4837 --out-dir /data/out

On an HPC system without Docker, use Apptainer/Singularity:

apptainer pull matpredict.sif docker://ghcr.io/stajichlab/matpredict:latest
apptainer run matpredict.sif detect --genome genome.fna --taxid 4837 --out-dir out

Conda / mamba. environment.yml lists the same packages as pixi.toml (exported with pixi workspace export conda-environment). Run from the repository root, because it installs MATPredict from the checkout:

mamba env create -f environment.yml
mamba activate matpredict
matpredict --help

The exact versions used for releases are in pixi.lock.

This example uses Phycomyces blakesleeanus NRRL 1555 (NCBI taxid 4837).

# 1. Download the assembly from NCBI
curl -L -o phybl.zip \
  "https://api.ncbi.nlm.nih.gov/datasets/v2/genome/accession/GCF_001638985.1/download?include_annotation_type=GENOME_FASTA"
unzip -q phybl.zip

# 2. Detect MAT loci (run from the repository root, so db/ is found).
#    Set your e-mail for NCBI first (see Configuration).
export MATPREDICT_NCBI_EMAIL=you@example.org
pixi run matpredict detect \
  --genome ncbi_dataset/data/GCF_001638985.1/GCF_001638985.1_Phybl2_genomic.fna \
  --taxid 4837 \
  --out-dir phybl_out

The run takes about 1.5 minutes on one CPU. phybl_out/detection_report.yaml reports one locus:

Mucoromycota:MAT  Minus  high  mat_locus  NW_017265134.1:3978283-3991589
genes: tptA, sexM, rnhA, algA

This genome is the source of a curated record (4837_nrrl1555_MAT_Minus), so the example shows that the tool works. It is not an independent test.

matpredict detect --genome GENOME [--proteins PROTEINS] [--taxid TAXID]
                  --out-dir OUT_DIR [options]

Outputs (in --out-dir):

Routing modes (routing_mode in the report): lineage (taxid matched a family scope), phylum_fallback, explicit_phylum (--phylum), exhaustive, not_searched.

matpredict report genome --run OUT_DIR [--out report.html] [--pdf report.pdf] [--sample NAME]

detect writes this report itself by default; use this command to re-render a run (for example one made before the report existed, or with --pdf). Writes a self-contained HTML report of one detect run (default OUT_DIR/report.html): the result in plain words, a gene-order figure and evidence table per called locus, what was searched, withheld candidates and provenance. Open it in any browser; "Save as PDF" prints it. --pdf writes the PDF directly with WeasyPrint (part of the pixi environment, environment.yml and the Docker image), or, where WeasyPrint is missing, a headless Chrome or Chromium on PATH. detect --sample and --organism set the names the report shows.

Call the MAT idiomorph of a strain from raw reads, with no assembly. It counts k-mers that occur in only one idiomorph reference. It needs a reference sequence for each idiomorph of the same species or lineage.

Steps

1. Get one FASTA per idiomorph (two or more). Use the idiomorph sequence with a little shared flank on both ends, from a GenBank record or from a genome that matpredict detect has typed. A reference from the same lineage works better than one from another species: the Fola MAT1-2 locus differs from the GenBank F. oxysporum record at 0.9% of its positions, and the panel built from Fola genomes agreed with more strains (see below). Ready panels: panels/fusarium_oxysporum_fola/ and panels/aspergillus_fumigatus/ (A1163 and Af293 locus segments from the database).

2. Run one strain:

   matpredict reads-type \
     --idiomorph MAT1-1=panels/fusarium_oxysporum_fola/MAT1-1.fasta \
     --idiomorph MAT1-2=panels/fusarium_oxysporum_fola/MAT1-2.fasta \
     --reads strain_R1.fastq.gz strain_R2.fastq.gz --sample strain \
     --max-reads 8000000 --out strain.mat.tsv

3. Run many strains: give a TSV with columns sample and reads (files separated by commas), and use --samples in place of --reads.

4. Read the output (one row per strain) as described below.

Options

Output columns: sample, call, <NAME>_breadth (fraction of the idiomorph's unique k-mers seen), <NAME>_depth (mean count of those k-mers), reads_used, shared_depth (mean count of the k-mers that both idiomorphs share; a single-copy depth control), flags.

Calls

An idiomorph is present when its depth is at least 0.10 of shared_depth and its breadth is at least 0.50 of the breadth that its depth predicts (1 - exp(-depth)). These cut-offs are set in src/MATPredict/reads/typing.py.

Flags: trace_<NAME> means some k-mers of an idiomorph were seen but not enough to call it. idiomorph_depth_ratio_below_0.25 on a both call means the minor idiomorph has less than a quarter of the depth of the major one.

What was measured (Fola, F. oxysporum f. sp. lactucae; details in analysis/2026-10-06_fola-reads-type.md):

• 147 of 148 strains agree with a samtools breadth call (the one difference has no signal in either method). With the GenBank panel, 145 of 148.
• Simulated mixes of two strains (3 pairs): both is called from a 10% minor MAT1-2 share in 3 of 3 pairs, from 5% in 2 of 3, and from a 20% minor MAT1-1 share in 3 of 3. trace_MAT1-2 also appears in pure MAT1-1 strains (background), so it is not evidence of a minor idiomorph.
• A. fumigatus (304 assemblies, 331 read sets): reads agree with an assembly BLAST truth in 293 of 296 strains (99.0%); detect on the assemblies agrees in 288 of 297 and reports a single idiomorph for all 8 assemblies that hold both. Seven of those 8 are both from reads (report).
• Speed: about 1.5 minutes for 8 million reads on one CPU (Python).
• A reference that differs from the strain at about one position in 40 gives none; at one in 60 it is called correctly.

Not part of the subcommand yet (scripts, tested on a few strains only): scripts/build_blastx_tiers.py (protein references by taxonomic distance, for DIAMOND blastx of reads), scripts/recruit_pairs.py (collect read pairs for a local assembly), scripts/simulate_mixes.sh (mixed samples) and scripts/compare_reads_type.py. Figure scripts for the two reports are in scripts/figures/; outputs are in analysis/figures/. A protein search works with references from the same genus and fails with distant ones; see the analysis note.

Run a batch from a frozen git worktree on shared storage, not from a tree you are editing. Set SRC and MATPREDICT_DB_ROOT to that worktree, so the code and the database come from the same commit.

MATPredict looks up NCBI taxonomy (for --taxid routing and the genetic code) through NCBI E-utilities. NCBI asks every caller to send an e-mail address. MATPredict has no default address. Set yours once, in one of two ways:

1. Config file (recommended). Create ~/.config/matpredict/config.toml:

   [ncbi]
   email = "you@example.org"
   # api_key = "your-ncbi-api-key"   # optional: higher request rate

   MATPredict reads $MATPREDICT_CONFIG instead when it is set, or $XDG_CONFIG_HOME/matpredict/config.toml when XDG_CONFIG_HOME is set.

2. Environment variables, for example in ~/.bashrc or a SLURM script:

   export MATPREDICT_NCBI_EMAIL=you@example.org
   export MATPREDICT_NCBI_API_KEY=your-ncbi-api-key   # optional

An environment variable wins over the config file. With no address set, the tool still runs, sends no e-mail, and logs one warning.

detect needs the lineage, phylum and genetic code of a --taxid. A local table answers these without NCBI E-utilities. Build it from a dated NCBI archive and point MATPREDICT_TAXONOMY at it:

curl -O https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump_archive/taxdmp_2026-10-01.zip
matpredict curate-db build-taxonomy --taxdump taxdmp_2026-10-01.zip \
    --snapshot 2026-10-01 --out ncbi_taxonomy.tsv.zst
export MATPREDICT_TAXONOMY=$PWD/ncbi_taxonomy.tsv.zst
export MATPREDICT_OFFLINE=1        # optional: never call NCBI

All taxa, about 24 MB; loading it takes about 2 s and 80 MB of memory. Each report records the source in taxonomy_source (for example local NCBI taxonomy snapshot 2026-10-01). The Docker image builds this table at image build time and sets both variables.

pixi run -e test pytest -q

Measured results (details in analysis/INDEX.md):

Known limits (open items in analysis/open-questions.md):

• Only three phyla have curated families.
• Ascomycota outside the curated orders has had no full-scale run. A genome far from every reference often fails the evidence bar, so an uncalled genome is weak evidence that the genome has no MAT locus.
• Fragmented assemblies can split a locus or lose its flanking genes.
• In Mucoromycota, Absidia flanking genes are often off-scaffold, and the gene order of the Lichtheimiaceae is not yet known.
• Basidiomycota pheromone-receptor calls that depend only on the CAAX motif are marked unverified. Each pheromone-receptor call also carries receptor_array_id, receptor_array_size, receptor_array_members and an receptor_array_support flag; receptor arrays occur for mating and non-mating receptors alike, so membership does not make a locus a mating receptor (docs/receptor-arrays.md).
• A two-idiomorph result is a flag for review. It can come from homothallism, a mixed culture or a duplication.

• Jason E. Stajich — University of California, Riverside (jason.stajich@ucr.edu, ORCID 0000-0002-7591-0020)

No paper describes MATPredict yet. Cite the software and the release you used. The citation metadata is in CITATION.cff; GitHub shows it under "Cite this repository".

Stajich JE. MATPredict: MAT locus identification in Fungi. Version 0.6.1. https://github.com/stajichlab/MATPredict

@software{matpredict,
  author  = {Stajich, Jason E.},
  title   = {MATPredict: MAT locus identification in Fungi},
  version = {0.6.1},
  url     = {https://github.com/stajichlab/MATPredict},
  year    = {2026}
}

Please also cite the publications behind the reference records you rely on. Each record's metadata.yaml lists its source (PMID/DOI or accession).

MATPredict is released under the MIT License. See LICENSE.