ChromDetect

A toolkit for genome assembly classification, validation, and quality control.

Overview

ChromDetect helps you work with genome assemblies by providing six key capabilities:

Installation

pip install chromdetect

Quick Examples

# Classify scaffolds in an assembly
chromdetect assembly.fasta

# Validate against NCBI report
chromdetect assembly.fasta --assembly-report report.txt --validate

# Check chromosome count for human
chromdetect assembly.fasta --check-karyotype human

# Convert to UCSC naming (chr1, chr2, chrX)
chromdetect assembly.fasta --rename ucsc -o renamed.fasta

# Compare two assembly versions
chromdetect v1.fasta --compare-versions v2.fasta

# Generate QC dashboard for multiple assemblies
chromdetect --dashboard *.fasta -o dashboard.html --format html

Use Cases

Preparing assemblies for submission

Before submitting to NCBI, check compliance and standardize names:

# Check if names meet NCBI requirements
chromdetect assembly.fasta --check-compliance

# Rename to standard convention
chromdetect assembly.fasta --rename refseq -o submission_ready.fasta

Quality control across projects

Compare multiple assemblies from different sources:

# Generate comparative dashboard
chromdetect --dashboard sample1.fa sample2.fa sample3.fa -o qc_report.html --format html

Validating downloaded assemblies

Verify a FASTA matches its NCBI assembly report:

chromdetect GRCh38.fasta --assembly-report GRCh38_report.txt --validate --strict

Tracking assembly improvements

See what changed between versions:

chromdetect old_assembly.fasta --compare-versions new_assembly.fasta

Output shows promotions, demotions, and metric changes:

SCAFFOLD CHANGES:
  Promoted:    2 scaffolds (unplaced → chromosome)
  Unchanged:   1,150 scaffolds
  N50 change:  +6.7 Mb (+14.6%)

Checking species-specific karyotype

Verify your assembly has the expected chromosomes:

# List available species
chromdetect --list-species

# Check against expected karyotype
chromdetect mouse_assembly.fasta --check-karyotype mouse

Output Formats

Python API

from chromdetect import classify_fasta

# Classify an assembly
results, stats = classify_fasta("assembly.fasta")
print(f"Chromosomes: {stats.chromosome_count}")
print(f"N50: {stats.n50 / 1e6:.1f} Mb")

# Filter to just chromosomes
chromosomes = [r for r in results if r.classification == "chromosome"]
for c in chromosomes:
    print(f"  {c.name}: {c.length:,} bp")

Additional modules for specific tasks:

# Validation
from chromdetect.validation import validate_fasta_against_report

# Karyotype checking
from chromdetect.karyotype import validate_karyotype, KaryotypeDatabase

# Name standardization
from chromdetect.standardize import standardize_fasta, check_ncbi_compliance

# Version comparison
from chromdetect.version import compare_fasta_files

# Multi-assembly dashboard
from chromdetect.dashboard import analyze_multiple_assemblies, generate_dashboard_html

Supported Species (Karyotype Database)

ChromDetect includes karyotype data for 29 species:

Mammals: Human, mouse, rat, dog, cat, horse, cow, pig, sheep, goat, rabbit, guinea pig

Other vertebrates: Chicken, zebrafish, frog

Invertebrates: Fruit fly, C. elegans

Plants: Arabidopsis, rice, maize, wheat, soybean, tomato

Microorganisms: Yeast (S. cerevisiae), E. coli

Use chromdetect --list-species to see all available species with chromosome counts.

Recognized Naming Patterns

ChromDetect automatically recognizes common scaffold naming conventions:

• Chromosome prefixes: chr1, Chr_1, chromosome_1, Chromosome1
• Super scaffolds: Super_scaffold_1, Superscaffold_1, SUPER_1
• Linkage groups: LG1, LG_1, linkage_group_1
• NCBI accessions: NC_000001.11, CM000663.2
• Assembly tools: HiC_scaffold_1, Scaffold_1_RaGOO
• Simple numeric: 1, 2, X, MT

Custom patterns can be added via YAML configuration files.

Limitations

ChromDetect uses naming patterns and size heuristics—it cannot:

• Detect misassemblies or sequence errors
• Validate sequence correctness
• Perform synteny or homology analysis

For comprehensive assembly validation, use ChromDetect alongside tools like QUAST or Merqury.

Citation

If you use ChromDetect in your research, please cite:

@software{chromdetect,
  author = {Handley, Scott A.},
  title = {ChromDetect: A toolkit for genome assembly classification and QC},
  url = {https://github.com/shandley/chromdetect},
  version = {0.6.0},
  doi = {10.5281/zenodo.17945062},
  year = {2025}
}

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.