Metadata-Version: 2.5
Name: speccheck-qc
Version: 1.3.0
Summary: A bioinformatics software focused on quality control based on species criteria
Project-URL: Homepage, https://github.com/happykhan/speccheck
Project-URL: Documentation, https://happykhan.github.io/speccheck/
Project-URL: Repository, https://github.com/happykhan/speccheck
Project-URL: Bug Tracker, https://github.com/happykhan/speccheck/issues
Author-email: Nabil-Fareed Alikhan <nabil@happykhan.com>
Maintainer-email: Nabil-Fareed Alikhan <nabil@happykhan.com>
License: GPLv3
License-File: LICENSE
Keywords: bioinformatics,genomic-analysis,genomics,qc,quality-control
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer<0.26.0,>=0.9.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: coverage>=7.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pylint>=2.15.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: safety>=2.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# speccheck

[![CI](https://github.com/happykhan/speccheck/actions/workflows/tests.yml/badge.svg)](https://github.com/happykhan/speccheck/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/happykhan/speccheck/branch/main/graph/badge.svg)](https://codecov.io/gh/happykhan/speccheck)
[![GPLv3 License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python Version](https://img.shields.io/badge/python->=3.10-blue.svg)](https://www.python.org/)

`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`](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](docs/installation.md)
- [Quick Start](docs/quickstart.md)
- [Worked Examples](docs/worked-examples.md)
- [CLI Usage](docs/cli.md)
- [Supported Modules](docs/modules.md)
- [Adding a Module](docs/extending.md)
- [Criteria Format](docs/criteria.md)
- [Reports](docs/reports.md)
- [QualiBact Integration](docs/qualibact.md)
- [Pipeline Integration](docs/ghru.md)
- [100-sample E. coli Case Study](docs/case-study.md)
- [Development](docs/development.md)

## Quick Start

Install from PyPI in a Python `3.10+` environment:

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

Collect QC metrics:

```bash
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:

```bash
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:

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

Refresh criteria from QualiBact:

```bash
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:

```bash
pytest
```

Build docs:

```bash
mkdocs build
```

Regenerate example figures and summary tables:

```bash
python scripts/create_real_run_100_assets.py
```

Build a wheel:

```bash
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`](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.
