Standard Quantity (STDQT) Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: STDQT rule for calculating patient sample quantities using standard curve quantification Domain: RULES-STDQT Precedence: After CT Calculation, Before Result Reporting
Statement
The system shall calculate patient sample quantities using standard curve quantification parameters (gradient and intercept) derived from quantitative standard controls on each run.
The rule uses the formula quantity = 10^((CT - intercept) / gradient) to compute quantities for positive-classified sample observations. When standard curve parameters are missing or run targets have quantification errors, the system propagates UNABLE_TO_QUANTIFY errors to affected patient wells. Configuration options control fallback standard controls from alternate mixes and error propagation scope.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-STDQT-001 | Calculates quantity using standard curve formula | HIGH | Draft |
| REQ-RULES-STDQT-002 | Applies quantity multiplier to calculated result | HIGH | Draft |
| REQ-RULES-STDQT-003 | Uses fallback controls from alternate mixes | MEDIUM | Draft |
| REQ-RULES-STDQT-004 | Propagates run target quantification errors | HIGH | Draft |
| REQ-RULES-STDQT-005 | Configures well failure scope (positive-only vs all) | MEDIUM | Draft |
Key Integration Points: Run Target (gradient/intercept), Well Classification, CT Calculation, Result Reporting
Rule Summary
| Property | Value |
|---|---|
| Name | STDQT |
| Precedence | After CT Calculation, Before Result Reporting |
| Triggers | When quantifying positive sample observations |
| Output | Sets quantity value or UNABLE_TO_QUANTIFY error on observations |
Rule Flowchart (Illustrative)
This diagram illustrates the core quantification logic. Fallback controls and well failure scope configurations follow additional paths not shown.
Definitions
| Term | Definition |
|---|---|
| Standard Curve | A calibration curve created from quantitative standard controls with known concentrations |
| Gradient | The slope of the standard curve (log quantity vs CT), typically negative |
| Intercept | The y-intercept of the standard curve equation |
| Quantity Multiplier | A scaling factor applied to calculated quantities (e.g., dilution factor) |
| Run Target | The combination of mix and target being analyzed within a run |
| Fallback Controls | Backup standard controls from a mapped alternate mix used when primary mix lacks standards |
| CT | Cycle Threshold - the PCR amplification cycle at which detection occurs |
Assumptions
- Run targets have been processed and gradient/intercept values calculated before STDQT rule execution
- Well classification has been completed before quantity calculation
- CT values are available for positive-classified sample wells
- Quantitative standard controls are configured in the system
- Default quantity_multiplier is 1.0 if not specified
Requirements
Quantity Calculation (REQ-RULES-STDQT-001)
FR-STDQT-001: Calculate Standard Quantity
The system shall calculate patient sample quantities using standard curve quantification parameters (gradient and intercept) from the run target.
Acceptance Criteria
Scope and Eligibility:
- Calculate quantity for observations with role = Sample
- Calculate quantity only for observations with classification = Positive
- Exclude roles Extraction Control, Control, Quantitative Control, and Ignore from quantification
- Exclude classifications Negative and Ambiguous from quantification
- Set quantity to null for non-positive classifications (no error)
Calculation Formula:
- Use the run target's gradient and intercept values for calculation
- Compute the intermediate log_quantity value as (CT - intercept) / gradient before exponentiating
- Apply the formula: quantity = 10^((CT - intercept) / gradient)
- Replace any pre-existing quantity value with the newly calculated quantity
Missing Parameters:
- Set error code UNABLE_TO_QUANTIFY when gradient is null or missing
- Set error code UNABLE_TO_QUANTIFY when intercept is null or missing
- When UNABLE_TO_QUANTIFY error is set, preserve any existing quantity from the runfile
Error Handling
- Gradient is null or missing: Set UNABLE_TO_QUANTIFY error and preserve existing quantity
- Intercept is null or missing: Set UNABLE_TO_QUANTIFY error and preserve existing quantity
- Observation role is not Sample: Skip quantification (no error)
- Observation classification is not Positive: Set quantity to null (no error)
Trace: Source: 3.0.0-Standard quantity (STDQT) (Rows 1-6) | Jira: BT-3172 (Epic), BT-3179 (Task) | Tests: BT-3407
Multiplier Application (REQ-RULES-STDQT-002)
FR-STDQT-002: Apply Quantity Multiplier
The system shall multiply the calculated standard quantity by the well's configured quantity multiplier value.
Acceptance Criteria
Multiplier Application:
- Multiply the calculated quantity by the well's quantity_multiplier value
- Perform multiplication after the base quantity calculation
- The final quantity shall reflect the product of calculated quantity and multiplier
Trace: Source: 3.0.0-StdQt Rule - multiply calculated quantity by quantity multiplier (Row 1) | Jira: BT-3893 (Epic), BT-3899 (Task) | Tests: [Pending]
Fallback Controls (REQ-RULES-STDQT-003)
FR-STDQT-003: Use Fallback Standard Controls
The system shall use backup standard controls from a configured alternate mix when the primary mix lacks standard controls and the fallback shared controls feature is enabled.
Acceptance Criteria
Fallback Behavior:
- Use backup standard controls when no standards exist for the primary mix
- Use backup controls only when "use fallback shared controls" feature is enabled
- When the feature is disabled, wells without primary standards shall not be quantified
- Control mappings shall define which controls from alternate mixes serve as backups
- Define backup relationships at the mix level through control mappings (e.g., BKV CONTROL QS1-4 as backups for BKV)
Trace: Source: 3.0.0-Stdqt Rule - Work with fallback controls (Row 1) | Jira: BT-4747 | Tests: [Pending]
Error Propagation (REQ-RULES-STDQT-004)
FR-STDQT-004: Propagate Run Target Quantification Errors
The system shall propagate run target quantification errors to patient wells by setting the UNABLE_TO_QUANTIFY error code.
Acceptance Criteria
Error Propagation:
- Set UNABLE_TO_QUANTIFY error on patient wells when run target has quantification errors
- Apply the error to patient wells associated with the affected run target
Triggering Errors:
| Run Target Error | Result |
|---|---|
| INSUFFICIENT_STANDARD_CONTROLS | Set UNABLE_TO_QUANTIFY on patient wells |
| STANDARD_WITHOUT_QUANT | Set UNABLE_TO_QUANTIFY on patient wells |
| BAD_R2 | Set UNABLE_TO_QUANTIFY on patient wells |
| BAD_GRADIENT | Set UNABLE_TO_QUANTIFY on patient wells |
| BAD_EFFICIENCY | Set UNABLE_TO_QUANTIFY on patient wells |
Trace: Source: 3.0.0-STD_QT Rule - Trigger 'UNABLE_TO_QUANTIFY' from Run Target Quantification Errors (Row 1) | Jira: BT-4493 (Epic), BT-4492 (Task) | Tests: [Pending]
Failure Scope Configuration (REQ-RULES-STDQT-005)
FR-STDQT-005: Configure Well Failure Scope
The system shall provide configuration to control whether only positive wells or all patient wells receive the UNABLE_TO_QUANTIFY error when associated controls fail.
Acceptance Criteria
Configuration Behavior:
| only_fail_positive | Classification | Receives Error? |
|---|---|---|
| true | Positive | Yes |
| true | Negative | No |
| true | Ambiguous | No |
| false | Positive | Yes |
| false | Negative | Yes |
| false | Ambiguous | Yes |
Scope:
- Apply configuration when associated controls have failed
- Negative and ambiguous wells shall be protected from error when "only fail positive" is true
Trace: Source: 3.0.0-STD_QT Rule - Fail All Wells Instead only Positive Wells (Row 1) | Jira: BT-4925 (Epic), BT-4926 (Task) | Tests: BT-4931
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
use_fallback_shared_controls | false | Enable backup standard controls from alternate mixes | REQ-RULES-STDQT-003 |
only_fail_positive_wells | true | Limit UNABLE_TO_QUANTIFY error propagation to positive-classified wells | REQ-RULES-STDQT-005 |
quantity_multiplier | 1.0 | Default scaling factor for calculated quantities (per-well) | REQ-RULES-STDQT-002 |
Notes
Calculation Formula
The standard quantity calculation uses the standard curve equation:
log_quantity = (CT - intercept) / gradient
quantity = 10^log_quantity
Example Calculation:
- Input: CT = 27, gradient = -1, intercept = 33
- log_quantity = (27 - 33) / (-1) = 6
- quantity = 10^6 = 1,000,000
Example with Multiplier:
- Input: CT = 32, gradient = -1, intercept = 33, multiplier = 160
- log_quantity = (32 - 33) / (-1) = 1
- base_quantity = 10^1 = 10
- final_quantity = 10 * 160 = 1,600
Quantification Method Context
Labs use PCR to quantify patient results to determine not only infection presence but also viral load (e.g., monitoring treatment efficacy). The system supports two quantification methods:
- Pre-selected Gradient Method: Uses a configured slope and intercept to calculate quantity based on CT value
- Standard Curve Method (this rule): Uses multiple standards (known quantity positive controls) within each run to create a dynamic slope, reducing run-to-run PCR variability effects
Processing Pipeline Position
[Run Import] --> [Well Classification] --> [CT Calculation] --> [STDQT Rule] --> [Result Reporting]
^
|
[Run Target: gradient, intercept]
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | No UI detail specified in source material; confirm none is required for this backend rule. | UI Detail | @tbd | 2026-01-23 |
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/StdqtRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-STDQT-001 | Calculate Standard Quantity | Test | StdqtRule | BT-3407 | Draft |
| REQ-RULES-STDQT-002 | Apply Quantity Multiplier | Test | StdqtRule | [Pending] | Draft |
| REQ-RULES-STDQT-003 | Use Fallback Standard Controls | Test | StdqtRule | [Pending] | Draft |
| REQ-RULES-STDQT-004 | Propagate Run Target Quantification Errors | Test | StdqtRule | [Pending] | Draft |
| REQ-RULES-STDQT-005 | Configure Well Failure Scope | Test | StdqtRule | BT-4931 | Draft |
Acceptance Tests
Test: REQ-RULES-STDQT-001
Test: Basic Quantity Calculation
Given: run_target has gradient = -1, intercept = 33
And: well A1 has role = Sample, ct = 27, quantity = null, cls = Pos
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = 1,000,000
Test: Override Existing Quantity
Given: run_target has gradient = -1, intercept = 33
And: well A1 has role = Sample, ct = 27, quantity = 100, cls = Pos
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = 1,000,000
Test: Non-Sample Roles Excluded
Given: run_target has gradient = -1, intercept = 33
And: well A1 has role = Extraction Control | Control | Quantitative Control | Ignore
And: well A1 has ct = 27, quantity = 100, cls = Pos
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = null
Test: Non-Positive Classification Excluded
Given: run_target has gradient = -1, intercept = 33
And: well A1 has role = Sample, ct = 27, quantity = 100, cls = Neg | Amb
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = null
Test: Missing Parameters Without Existing Quantity
Given: run_target has gradient = null, intercept = null
And: well A1 has role = Sample, ct = 27, quantity = null
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = null
And: well A1 shall have error = UNABLE_TO_QUANTIFY
Test: Missing Parameters With Existing Quantity
Given: run_target has gradient = null, intercept = null
And: well A1 has role = Sample, ct = 27, quantity = 1000
When: Import the well through the STDQT rule
Then: well A1 shall have quantity = 1000
And: well A1 shall have error = UNABLE_TO_QUANTIFY
Test: REQ-RULES-STDQT-002
Test: Quantity Multiplier Application
Given: run_target has slope = -1, intercept = 33
And: well has quantity_multiplier = 160
And: observation A has role = Sample, final_ct = 32, final_cls = Pos
When: Execute STDQT rule on Observation A
Then: Quantity of Observation A shall be 1600
Test: REQ-RULES-STDQT-003
Test: Fallback Controls Enabled
Given: Mixes BKV and BKV CONTROL are configured
And: Controls mapping defines BKV CONTROL QS1-4 as backup for BKV
And: A1 is a BKV Patient well
And: A5-A8 are BKV CONTROL QS1-4 wells
And: use_fallback_shared_controls feature is enabled
When: The run is imported
Then: A1 well shall be quantified using A5, A6, A7, A8
Test: Fallback Controls Disabled
Given: Mixes BKV and BKV CONTROL are configured
And: Controls mapping defines BKV CONTROL QS1-4 as backup for BKV
And: A1 is a BKV Patient well
And: A5-A8 are BKV CONTROL QS1-4 wells
And: use_fallback_shared_controls feature is disabled
When: The run is imported
Then: A1 well shall not be quantified
Test: REQ-RULES-STDQT-004
Test: Error Propagation
Given: well A1 has role alias = Patient, run target = Run Target A
When: Run Target A has error codes containing a quantification error
Then: well A1 shall have error code = UNABLE_TO_QUANTIFY
Test: REQ-RULES-STDQT-005
Test: Fail Only Positive Wells
Given: well A1 is type = Patient, cls = Pos
And: well A2 is type = Patient, cls = Neg
And: well A3 is type = Associated control, outcome = Failed
And: configuration only_fail_positive = true
When: STDQT rule executes
Then: well A1 shall have error
And: well A2 shall not have error
Test: Fail All Wells
Given: well A1 is type = Patient, cls = Pos
And: well A2 is type = Patient, cls = Neg
And: well A3 is type = Associated control, outcome = Failed
And: configuration only_fail_positive = false
When: STDQT rule executes
Then: well A1 shall have error
And: well A2 shall have error
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Standard Quantity Calculation |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion - N/A, all requirements are distinct)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
No Consolidation Applied
All five requirements in this domain represent genuinely distinct system capabilities:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-STDQT-001 | Base quantity calculation | Core calculation logic with formula and eligibility rules |
| REQ-RULES-STDQT-002 | Quantity multiplier application | Post-calculation scaling operation |
| REQ-RULES-STDQT-003 | Fallback standard controls | Alternate source configuration for missing standards |
| REQ-RULES-STDQT-004 | Error propagation from run target | Cascading error handling from upstream failures |
| REQ-RULES-STDQT-005 | Configurable failure scope | Selective error application based on classification |
Rationale: This is a RULES domain where analytics precision is critical. Each requirement represents a distinct capability that can be independently tested and verified. Consolidation would obscure the specific behavior guarantees required for laboratory informatics accuracy.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-stdqt/rule-stdqt-restructured.md