sample-qc-triage
Deterministic multi-sample QC triage for identity, sex, contamination, and batch-shift outliers
- License 许可
- MIT
- 最近更新
- 2026-09-20
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sample-qc-triage
- license
- MIT
- metadata
- { "tags": [ "quality-control", "sequencing-qc", "triage" ], "author": "ClawBio", "domain": "genomics", "inputs": [ { "name": "input_file", "type": "file", "format": [ "csv" ], "required": true, "description": "Sample-level QC metrics table with optional identity checks" } ], "outputs": [ { "name": "report", "type": "file", "format": [ "md" ], "description": "QC triage report" }, { "name": "result", "type": "file", "format": [ "json" ], "description": "Machine-readable sample flags" } ], "version": "0.1.0", "openclaw": { "os": [ "darwin", "linux" ], "emoji": "🔬", "always": false, "install": null, "homepage": "https://github.com/ClawBio/ClawBio", "requires": { "bins": [ "python3" ] }, "trigger_keywords": [ "sample QC triage", "sequencing QC outliers", "sex mismatch", "fingerprint concordance", "contamination batch shift" ] }, "demo_data": [ { "path": "demo_qc_metrics.csv", "description": "Synthetic five-sample QC metrics table" } ], "endpoints": { "cli": "python skills/sample-qc-triage/sample_qc_triage.py --input {input_file} --output {output_dir}" }, "dependencies": { "python": ">=3.10", "packages": null } }
- description
- Deterministic multi-sample QC triage for identity, sex, contamination, and batch-shift outliers
02 资源文件 60
- 脚本clawbio/__init__.py211 B
- 脚本clawbio/cli.py138.8 KB
- 脚本clawbio/common/__init__.py1.6 KB
- 脚本clawbio/common/audit.py5.9 KB
- 脚本clawbio/common/checksums.py706 B
- 脚本clawbio/common/html_report.py24.9 KB
- 脚本clawbio/common/parsers.py16.1 KB
- 脚本clawbio/common/portable_commands.py7.1 KB
- 脚本clawbio/common/profile.py4.8 KB
- 脚本clawbio/common/rec_shortener.py12.7 KB
- 脚本clawbio/common/report.py4.3 KB
- 脚本clawbio/common/reproducibility.py11.7 KB
- 脚本clawbio/common/sarek.py14.3 KB
- 脚本clawbio/common/scrna_io.py8.4 KB
- 脚本clawbio/common/tests/__init__.py—
- 脚本clawbio/common/tests/test_audit.py5.4 KB
- 脚本clawbio/common/tests/test_html_report.py9.4 KB
- 脚本clawbio/common/tests/test_parser_bom.py1.5 KB
- 脚本clawbio/common/tests/test_parser_partial_gt.py1.1 KB
- 脚本clawbio/common/tests/test_rec_shortener.py6.0 KB
- 脚本clawbio/common/tests/test_report.py2.9 KB
- 脚本clawbio/common/tests/test_reproducibility.py19.8 KB
- 脚本clawbio/common/tests/test_textio.py2.3 KB
- 脚本clawbio/common/textio.py2.7 KB
- 脚本clawbio/common/vcf_qc.py19.6 KB
- 脚本clawbio/contract_alerts.py9.6 KB
- 脚本clawbio/gi/__init__.py—
- 脚本clawbio/gi/gi_client.py18.0 KB
- 脚本clawbio/gi/gi_runner.py28.3 KB
- 脚本clawbio/mcp_server.py8.9 KB
- 脚本clawbio/providers/__init__.py357 B
- 脚本clawbio/providers/__main__.py2.0 KB
- 脚本clawbio/providers/chat.py9.9 KB
- 脚本clawbio/providers/flock.py5.1 KB
- 参考文档clawbio/providers/README.md6.8 KB
- 脚本clawbio/runner.py436 B
- 脚本clawbio/skill_intents.py51.0 KB
- 参考文档clawbio/tests/fixtures/mock_23andme.txt145 B
- 参考文档clawbio/tests/fixtures/mock_ancestry.txt132 B
- 资产文件clawbio/tests/fixtures/mock_myheritage.csv124 B
- 其他clawbio/tests/fixtures/mock_single_sample.vcf234 B
- 脚本clawbio/tests/test_checksums.py975 B
- 脚本clawbio/tests/test_gi_contract.py9.9 KB
- 脚本clawbio/tests/test_gi_request_construction.py7.9 KB
- 脚本clawbio/tests/test_gi_response_shape.py36.3 KB
- 脚本clawbio/tests/test_package_api.py1.7 KB
- 脚本clawbio/tests/test_packaging.py3.3 KB
- 脚本clawbio/tests/test_parsers.py11.1 KB
- 脚本clawbio/tests/test_pipeline_config_forwarding.py3.2 KB
- 脚本clawbio/tests/test_pipeline_flag_spelling.py5.4 KB
- 脚本clawbio/tests/test_portable_commands.py3.5 KB
- 脚本clawbio/tests/test_profile.py4.6 KB
- 脚本clawbio/tests/test_providers.py14.2 KB
- 脚本clawbio/tests/test_pubmed_runner.py1.8 KB
- 脚本clawbio/tests/test_report.py3.5 KB
- 脚本clawbio/tests/test_runner.py2.2 KB
- 资产文件demo_qc_metrics.csv421 B
- 脚本run.py2.0 KB
- 脚本sample_qc_triage.py8.1 KB
- 参考文档skill.json845 B
03 SKILL.md 正文
Sample QC Triage
You are Sample QC Triage, a specialised ClawBio agent for deterministic sample-level quality-control triage.
Trigger
Fire this skill when the user says any of:
- "sample QC triage"
- "find sequencing QC outliers"
- "check sample identity and sex mismatches"
- "review fingerprint concordance"
- "which samples have contamination or batch effects"
- "triage multi-sample QC metrics"
Do NOT fire when:
- The user asks for variant pathogenicity; route to clinical variant skills.
- The user asks for expression differential testing; route to RNA-seq skills.
- The user asks for raw FASTQ trimming or alignment; route to sequence wrangling.
Why This Exists
- Without it: Users manually inspect disconnected QC columns and miss sample-level patterns.
- With it: A local CSV is converted into a report, JSON flags, and reproducibility bundle.
- Why ClawBio: Deterministic thresholds are visible and no sample data leaves the machine.
Core Capabilities
- Schema validation: Requires sample, batch, read-depth, mapping, duplication, mitochondrial, contamination, and complexity fields.
- Identity checks: Optionally flags expected/observed sex mismatches and low fingerprint concordance.
- Outlier scoring: Flags low complexity, contamination, batch shifts, and mapping drops.
- Report pack: Writes
report.md,result.json,tables/sample_flags.csv, andreproducibility/commands.sh.
Scope
One skill, one task. This skill triages sample-level QC metrics and does not realign reads, run canonical contamination tools, infer kinship, or make clinical claims. It works on supplied summary columns only. It does not implement VerifyBamID, Conpair, Somalier, PLINK IBD, or SNP fingerprint barcoding.
Input Formats
| Format | Extension | Required Fields | Example |
|---|---|---|---|
| CSV | .csv |
sample_id, batch, total_reads, mapped_pct, duplicate_pct, mitochondrial_pct, contamination_pct, complexity_score; optional expected_sex, observed_sex, fingerprint_match_pct | demo_qc_metrics.csv |
Workflow
- Validate: Confirm required columns and numeric metric fields.
- Check identity: Compare optional sex labels and fingerprint match percentages.
- Score: Apply deterministic flags for complexity, contamination, and batch/read-depth shifts.
- Summarise: Count flagged samples and issue categories.
- Report: Write markdown, JSON, tabular output, and reproducibility command.
CLI Reference
python skills/sample-qc-triage/sample_qc_triage.py --input metrics.csv --output /tmp/sample_qc
python skills/sample-qc-triage/sample_qc_triage.py --demo --output /tmp/sample_qc
python clawbio.py run sample-qc --demo
Demo
python clawbio.py run sample-qc --demo
Expected output: a synthetic five-sample report with three flagged samples.
Algorithm / Methodology
- Sex mismatch: optional
expected_sexandobserved_sexdiffer after normalisation. - Identity mismatch: optional
fingerprint_match_pct < 95. - Low complexity:
complexity_score < 0.60orduplicate_pct > 35. - Contamination:
contamination_pct > 5. - Batch shift: read-depth median absolute deviation outlier,
mapped_pct < 80, ormitochondrial_pct > 15.
Example Queries
- "Run sample QC triage on this metrics CSV"
- "Find contamination and batch-shift outliers"
- "Which sequencing samples should I rerun?"
Example Output
# Sample QC Triage Report
| Sample | Batch | Status | Dominant issue |
|---|---|---|---|
| CB_QC_005 | C | flagged | sex_mismatch |
Output Structure
output_directory/
├── report.md
├── result.json
├── tables/
│ └── sample_flags.csv
└── reproducibility/
└── commands.sh
Dependencies
- Python 3.10+ standard library only.
Gotchas
- Do not infer clinical suitability: QC flags are operational, not diagnoses.
- Do not upload data: All parsing and scoring are local-only.
- Do not use hidden thresholds: Thresholds must remain documented in this file.
Safety
- Local-first: No external APIs or uploads.
- Disclaimer: Every report includes the ClawBio medical disclaimer.
- Audit trail: Commands are written to
reproducibility/commands.sh.
Agent Boundary
The agent dispatches and explains. The Python skill validates and scores.
Integration with Bio Orchestrator
Trigger conditions: sample QC, contamination, batch shift, sequencing QC outliers.
Chaining Partners
seq-wrangler: downstream remediation after QC flags.multiqc-reporter: upstream aggregate QC summaries.
Maintenance
- Review cadence: Recheck thresholds quarterly.
- Staleness signals: New QC metrics become standard in ClawBio workflows.
- Deprecation: Archive if replaced by a richer QC engine.
Author & Attribution
Prepared by Mrinal Joshi, Imperial College London and UK Dementia Research Institute, using his genomics and bioinformatics background to scope a local deterministic QC triage helper for supplied sample-level summary metrics. The implementation is intentionally not a replacement for canonical contamination, sample-swap, kinship, or fingerprinting tools.
Citations
- ClawBio local QC heuristics in
sample_qc_triage.py; thresholds are operational defaults documented above, not clinical standards.
04 同仓库更多 Skills
uncertainty-and-units
Track physical units and propagate measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.
scikit-survival
Build, evaluate, and audit right-censored or competing-risk survival workflows with scikit-survival, including leakage-safe preprocessing, model selection, probability prediction, and censoring-aware metrics.
pytdc
Use Therapeutics Data Commons through the PyTDC Python package for registry discovery, approved dataset access, task-aware splits, evaluator metrics, benchmark groups, and bounded molecular-oracle workflows.
pysam
Python/HTSlib workflows for genomic files. Use when reading, querying, filtering, or writing SAM/BAM/CRAM, VCF/BCF, FASTA/FASTQ, or tabix data with pysam, including pileup, coverage, indexing, and CRAM references.
pymatgen
Analyze, validate, convert, and transform materials structures and computed materials data with current pymatgen APIs, including local phase diagrams, symmetry sensitivity, electronic-structure I/O, and explicitly bounded Materials Project queries.
pydicom
Use pydicom to read, inspect, write, transform, and safely preflight local DICOM datasets and pixel data. Applies to DICOM metadata, transfer syntaxes, compression plugins, frames, private elements, JSON, and bounded de-identification review.