qPCR CLI

Configuration-driven qPCR CLI for laboratory workflows.

This tool ingests instrument-exported csv/txt, normalizes records into a canonical schema, runs relative quantification analysis, and writes auditable outputs with strict gating decisions.

Install

python -m pip install -e ".[dev]"

For quick orientation, use this README.
For lab execution steps (WSL setup, template-based run flow, Prism handoff rules), see SOP.md.

Core Commands

Validate config:

qpcr validate-config tests/fixtures/configs/minimal_valid.yaml

Single-file preview:

qpcr inspect tests/fixtures/raw/generic_qpcr.csv tests/fixtures/configs/instrument_generic_csv.yaml

Project parse:

qpcr parse-project tests/fixtures/configs/project_valid.yaml --output out/project

Project analysis:

qpcr analyze-project tests/fixtures/configs/project_analysis_single_ref.yaml --analysis-config tests/fixtures/analysis/analysis_single_ref.yaml --output out/analysis

This command also writes:

• analysis_workbook.xlsx (audit/reporting intermediate workbook)

Start From Templates

For real project runs, start from:

• templates/project_template.yaml
• templates/analysis_template.yaml

Copy them, then fill in your own input file paths, sample groups, reference genes, and statistical control group before running:

qpcr analyze-project path/to/project.yaml --analysis-config path/to/analysis.yaml --output out/analysis

Tool Positioning

qPCR CLI is designed to:

• adapt to multiple instrument export styles through configuration,
• standardize data into canonical records,
• run relative quantification with explicit biological replicate semantics,
• enforce layered gating (project/target/comparison),
• emit eligible result tables and blocked audit tables for downstream reporting.

Current Analysis Method (Stable Contract)

• Technical replicates are summarized first.
• Reference-gene normalization is applied.
• Relative quantification is computed via:
  • deltaCt
  • deltaDeltaCt
  • fold change = 2^(-deltaDeltaCt)
• Statistical testing is executed in delta_ct space.
• Biological replicate inference policy is explicit_only (no implicit guessing).

Three-Layer Gating Philosophy

1) Project-level blocked

Only project-level blocking can fail analyze-project with exit code 1.

Examples:

• plate_correction_mode == inter_plate_calibrator (hard-blocked in current version),
• canonical analysis dataset globally unavailable,
• global statistical_control_group missing from project data,
• other global interpretability failures.

2) Target-level blocked (minimal unit)

Minimal blocking unit is:

• target_gene x calibrator_group

Target-level blocking is only for contexts where the target-level main result is not interpretable.

Typical reasons:

• missing_reference_baseline
• missing_calibrator_baseline
• required_control_group_missing
• other failures that invalidate target-level fold-change/summary interpretation.

Blocked targets are excluded from:

• eligible_relative_expression_records
• eligible_group_summary_records
• plotting main input
• eligible_stats_results

And are recorded in:

• blocked_target_audit_rows

3) Comparison-level blocked

For "computable but not testable" comparisons:

• summary/plot can remain,
• stats are disabled for that comparison,
• p-values are null,
• significance_label = "blocked",
• comparison is excluded from eligible_stats_results,
• comparison is recorded in blocked_comparison_stats_rows and blocked_comparison_audit_rows.

Two Critical Business Rules

1. No treatment comparison is not equal to target blocked.
   If target-level expression/summary remains interpretable, keep it.
   Only the comparison-level stats are blocked.

2. statistical_control_group is a target-level viability line.
   If required control context is missing in a target x calibrator context, that target context is blocked.

CLI Exit Code Contract

• exit code 1: project-level blocked only.
• exit code 0: target/comparison blocking allowed; eligible outputs continue with warnings and audit files.

Analysis Output Files and Semantics

Main eligible outputs:

• relative_expression.csv
  Eligible biological replicate expression rows.
• biological_replicate_expression.csv
  Same biological replicate layer, explicit export for downstream tools.
• group_summary.csv
  Eligible target-level group summaries.
• stats_results.csv
  Eligible (testable) statistics only.

Blocked/audit outputs:

• blocked_comparison_stats.csv
  Blocked-for-stats comparison rows (significance_label=blocked, p-values null).
• blocked_target_audit.csv
  Target-level blocked audit.
• blocked_comparison_audit.csv
  Comparison-level blocked audit.
• target_decisions.csv / comparison_decisions.csv
  Decision-layer contracts.
• project_decision.json
  Project-level pass/block decision.
• analysis_issues.jsonl
  Structured issue events.
• analysis_metadata.yaml
  Provenance metadata for analysis run.
• analysis_workbook.xlsx
  Traceable workbook with long-form audit tables, eligible result sheets, calibrator-specific Prism-ready sheets, and unified audit log. Prism-ready sheets are convenience-oriented and must not be used alone to infer statistical eligibility for significance annotation.

Workbook sheet structure (first version):

• metadata
• raw_ct_long
• tech_rep_summary
• reference_baseline
• template_audit_long
• group_summary
• stats_results
• prism_<calibrator_group> (one sheet per calibrator)
• prism_ready_notes
• audit_log
• blocked_comparison_stats (additional blocked-for-stats detail sheet)

Prism-ready sheet layout:

• rows: target_gene
• datasets (column groups): sample_group
• side-by-side subcolumns: biological replicate fold-change values

Typical Prism workflow:

1. Copy one prism_<calibrator_group> sheet data block into a Prism Grouped table.
2. Use GraphPad Prism Graph by Row.
3. Use stats_results for significance eligibility.
4. Use audit_log / template_audit_long / raw long sheets for troubleshooting.

Hard Constraints for Future Excel/Plot Layers

• Excel main result sheets must consume eligible surfaces only.
• Blocked comparisons must be shown in dedicated blocked/audit sheets.
• Significance annotations are allowed only where allow_significance_annotation == True.
• Comparison-blocked cases may still show bars/error bars for summary/plot, but must not show stars or p-values.
• Prism-ready sheets are convenience-oriented and do not redefine analysis eligibility.
• Do not infer significance from Prism-ready sheets alone.
• Do not add significance stars from Prism-ready sheets alone.
• template_audit_long is exported at summarized_techrep_level; paired target/reference well-level mapping is not inferred unless a reliable pairing contract exists.

Example:

• TARGET_X has valid fold-change summary in Control and DrugB.
• DrugB vs Control has insufficient biological replicates.
• Report behavior:
  • keep bar/error representation for TARGET_X,
  • do not render significance stars for that comparison,
  • show the comparison in blocked stats/audit sheets.

Project-blocked behavior:

• analyze-project still writes analysis_workbook.xlsx in audit-first mode.
• Metadata/audit/raw tracking sheets are available for failure diagnosis.
• Main eligible result sheets may be present but empty; no result rows are fabricated.

More Detailed Contracts

• Developer analysis contract: docs/analysis-contract.md
• Reporting/Excel/plot input contract: docs/reporting-contract.md

Citation and reuse

If you use this tool in a manuscript, thesis, teaching material, or benchmark/demo workflow, please cite the repository URL and the exact version/commit used.

Suggested format:

Lijie Zhou. qPCR CLI: configuration-driven qPCR parsing, relative quantification, gated statistical outputs, and auditable reporting surfaces. GitHub repository, 2026.

Please also cite upstream methods/resources relevant to your own analysis pipeline where appropriate.