Skip to content

Quick Start

This page assumes you already have QC output files from upstream tools.

1. See what Speccheck can read

speccheck inspect path/to/qc_outputs/
speccheck modules

inspect does not write outputs. Use it before collect, especially when you are connecting a new workflow.

2. Collect one sample

mkdir -p qc_collect

speccheck collect path/to/qc_outputs/SAMPLE_001/ \
  --sample SAMPLE_001 \
  --organism "Escherichia coli" \
  --assembly-type short \
  --output-file qc_collect/SAMPLE_001.csv

The output CSV contains:

  • parsed metrics, for example Quast.N50 or Checkm.Contamination;
  • status/check columns from the criteria CSV;
  • provenance, including Speccheck version and criteria checksum.

3. Collect many samples

For a directory-per-sample layout:

mkdir -p qc_collect

for sample_dir in path/to/run/*; do
  sample="$(basename "$sample_dir")"
  speccheck collect "$sample_dir" \
    --sample "$sample" \
    --organism "Escherichia coli" \
    --assembly-type short \
    --output-file "qc_collect/${sample}.csv"
done

If the organism is not supplied, Speccheck tries to infer it from parser outputs configured as species fields in the criteria file. If no single species can be resolved, collection stops by default. Use --allow-unknown-organism only when generic fallback thresholds are the intended policy.

4. Build the report

speccheck summary qc_collect \
  --output qc_report \
  --plot \
  --xlsx-output qc_report/report.xlsx

Outputs:

File Use
report.csv compact merged result for review and downstream scripts
report.full.csv human-ordered parser, metadata, and provenance table
report.html interactive human review report
report.xlsx optional workbook with summary and full sheets

5. Read the first three columns

Start with:

  • overall_qc: worst current PASS, WARN, or FAIL result;
  • speccheck_qc: native Speccheck result, including non-QualiBact criteria;
  • reason_summary: compact explanation of warnings, failures, and missing checks.

NOT_EVALUATED means Speccheck expected a metric but could not find it. It is not the same as failing a threshold; under the default policy it contributes a sample-level WARN.

6. Pipeline layout shortcut

For a published workflow output layout such as GHRU Assembly:

speccheck collect-pipeline results/ qc_collect \
  --layout ghru \
  --organism "Escherichia coli" \
  --work-dir work/

speccheck summary qc_collect --output qc_report --plot

See Pipeline Integration for details.