Docs / Guide

Parameters

Required#

Optional#

Recore matches FASTA and GFF files by exact matrix column name first, then by an embedded ASxxxxx identifier. For single-contig genomes, GFF seqids are normalized internally to the FASTA contig name so --synteny can work when a GFF uses contig_1 or L4_AS00146 but the FASTA contig is AS00146.

Numeric parameters are validated before the pipeline starts: percentages must be finite values between 0 and 100, fractions between 0 and 1, thread count and NSC k-mer size must be at least 1, and --nsc-engine must be minhash or mmseqs2.

Alignment#

Filtering#

Rescue options#

Nucleotide Similarity Clustering#

Logging#

Parameter Guide by Organism#

M. tuberculosis complex (MTBC)#

MTBC has >99.95% average nucleotide identity across strains. This has two consequences:

1. Real genes have very high identity; PARALOGs (90-94%) are nearly always noise
2. PE/PPE genes (~170 families with high mutual similarity) are a major source of cross-matches

Recommended command:

recore \
  -p gene_presence_absence.csv \
  -r pan_genome_reference.fa \
  -g genomes/ \
  -a annotations/ \
  --synteny \
  --multi-allele \
  --nscluster \
  --nsc-engine mmseqs2 \
  --nsc-min-seq-id 0.9 \
  --nsc-coverage 0.8 \
  --preset asm5 \
  --min-prevalence 0.0 \
  -t 8

Why --min-prevalence 0.0: In MTBC, even rare accessory clusters can have real false absences due to annotation differences. 0.0 ensures nothing is skipped.

Why asm5: Strains are <5% divergent. asm5 is faster and more accurate at this range.

Why mmseqs2 for NSC: More precise than MinHash for detecting the redundant annotation clusters common in MTBC pangenome analyses.

More divergent bacteria / pan-genome with 95% ANI#

recore \
  -p gene_presence_absence.csv \
  -r pan_genome_reference.fa \
  -g genomes/ \
  -a annotations/ \
  --synteny \
  --multi-allele \
  --nscluster \
  --preset asm20 \
  --min-prevalence 0.05 \
  -t 8

Why asm20: Allows up to 20% divergence, which is needed when comparing strains from the same species but different lineages.

Why --min-prevalence 0.05: Rare accessory clusters (present in <5% of genomes) generate excessive cross-match noise across the matrix.

Threshold Effects#

--min-identity (alignment filter)#

Affects PARALOG counts most strongly. If you see an unexpectedly large number of PARALOGs:

• Check if --min-identity was set below 90% by mistake
• For MTBC: real genes should be >99% identical; PARALOGs at 90-94% are noise
• Increasing to 95% eliminates most PE/PPE cross-matches but may miss a few rare variants

--min-coverage (coverage filter)#

Controls the boundary between PSEUDOGENE:PartialDeletion (60-80%) and no rescue (<60%):

• Increasing to 90%: only rescues nearly complete genes; misses short pseudogenes
• Decreasing to 60%: rescues more partial genes but increases false positives

--min-prevalence (gap filter)#

Affects total rescues and PARALOG rate:

• 0.0: search all gaps (maximum sensitivity, higher PARALOG noise)
• 0.05: skip clusters present in <5% of genomes
• 0.1 (default): skip clusters present in <10% of genomes

For core/soft-core analysis, --min-prevalence 0.0 is recommended. For reducing runtime on large datasets, 0.05 is a reasonable compromise.

--nsc-threshold (NSC similarity)#

Controls how aggressively redundant clusters are merged:

• 0.8 (default): merge if 80% of one cluster's k-mers are contained in the other
• 0.9: stricter, fewer merges
• 0.7: more aggressive, may merge genuinely distinct paralogs

For MTBC, prefer MMseqs2 with --nsc-min-seq-id 0.9 over MinHash, as it uses exact alignment identity.

Edit this page on GitHub