speccheck

speccheck is a Python command-line tool for collecting, validating, and summarizing genome QC metrics from multiple bioinformatics tools. It is designed for species-aware QC workflows and reproducible reporting.

The 100-sample case study processes real, read-backed Escherichia coli samples through GHRU-assembly, then applies a pinned QualiBact E. coli compatibility policy. The committed case-study outputs include accessions, provenance, reports, concordance analysis, and figures under examples/qualibact_ecoli/real_run_100.

Documentation

Project documentation is built with MkDocs Material and intended for GitHub Pages:

• Docs site: https://happykhan.github.io/speccheck/
• Local docs build: mkdocs build

Primary docs pages:

• Installation
• Quick Start
• Worked Examples
• CLI Usage
• Supported Modules
• Adding a Module
• Criteria Format
• Reports
• QualiBact Integration
• Pipeline Integration
• 100-sample E. coli Case Study
• Development

Quick Start

Install from PyPI in a Python 3.10+ environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install speccheck-qc

Collect QC metrics:

speccheck collect tests/practice_data/Sample_178db692semb --sample Sample_178db692semb

If --organism is not provided, speccheck infers it from species parser outputs and stops if no single species can be resolved. Use --allow-unknown-organism only for explicit fallback runs.

Generate a merged report:

speccheck summary qc_results --plot --qualifyr-style --xlsx-output qc_report/report.xlsx

summary merges concise collected CSV files, ignores detailed.*.csv companions, preserves sample IDs as strings, and rejects duplicate or conflicting records. Cohort reports use only PASS, WARN, FAIL, and NOT_EVALUATED for QC statuses.

Collect a recognised workflow output layout, such as GHRU Assembly, after a Nextflow run:

speccheck collect-pipeline path/to/pipeline/output qc_collect \
  --layout ghru \
  --organism "Escherichia coli" \
  --work-dir path/to/nextflow/work

Refresh criteria from QualiBact:

speccheck check --criteria-file speccheck/config/criteria.csv --update

Features

• Explicitly registered parsers for CheckM/CheckM2, native wide or transposed QUAST, Speciator, ARIBA, Sylph, depth, Fastp, and BUSCO outputs
• Criteria-driven PASS/WARN/FAIL validation
• Standalone offline HTML reporting with an exception-first review queue, sample details, species-filtered cohort metrics, lightweight inline SVG charts, collapsed diagnostics, and responsive navigation
• Compact qualifyr-style summary tables
• Optional Excel workbook export from merged reports
• Packaged default criteria and templates for pip/conda style installs
• QualiBact threshold import workflow for compatibility checks and regression testing

Development

Run tests:

pytest

Build docs:

mkdocs build

Regenerate example figures and summary tables:

python scripts/create_real_run_100_assets.py

Build a wheel:

python -m build

Citation

If you use speccheck in a paper, report, or public workflow, cite the software and include the repository URL. Structured citation metadata is provided in CITATION.cff. Zenodo archive metadata is provided in .zenodo.json; after a GitHub Release is archived by Zenodo, cite the release DOI for the exact version used.