Skip to main content
Version: Next

Quantity Standard Validation Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: QUANT_VALIDATION rule for validating standard curve controls and calculating linear regression for PCR quantification Domain: RULES-QUANTVAL Precedence: Executes during run import pipeline after upstream observation processing


Statement

The system shall validate quantitative standard controls and calculate linear regression parameters for PCR-based sample quantification workflows.

The rule assigns known quantities to observations, excludes non-quantifiable targets, calculates standard curve parameters (gradient, intercept, R2, efficiency), validates results against configured thresholds, and generates appropriate errors when validation fails. Standard controls with known quantities create the linear regression curve used to calculate unknown sample quantities.


Quick Reference

IDCore BehaviorPriorityStatus
REQ-RULES-QUANTVAL-001Assigns known quantity values to observations from configurationHIGHDraft
REQ-RULES-QUANTVAL-002Excludes IC targets, negative classifications, and non-quantifiable rolesHIGHDraft
REQ-RULES-QUANTVAL-003Calculates linear regression parameters from quantitative controlsHIGHDraft
REQ-RULES-QUANTVAL-004Validates standard controls and generates errors for threshold failuresHIGHDraft
REQ-RULES-QUANTVAL-005Validates CT values against configured range boundsHIGHDraft
REQ-RULES-QUANTVAL-006Supports error resolution for specific error typesMEDIUMDraft

Key Integration Points: Known Quantities Configuration, Calculated Quantification Settings, Curve Control Range Settings, Run Import Pipeline

Rule Summary

PropertyValue
NameQUANT_VALIDATION
PrecedenceAfter upstream import rules
TriggersWhen processing quantitative control observations
OutputSets quantity, regression parameters, and validation errors

Rule Flowchart (Illustrative)

This diagram illustrates the validation flow. Threshold validation errors (BAD_R2, BAD_GRADIENT, BAD_EFFICIENCY) still allow regression storage; only INSUFFICIENT_STANDARD_CONTROLS prevents storage.


Definitions

TermDefinition
CTCycle Threshold - the number of PCR cycles required for fluorescent signal to cross the detection threshold
R2R-squared (Squared Pearson Correlation Coefficient) - statistical measure of linear regression fit quality
GradientSlope of the linear regression line relating log(quantity) to CT
EfficiencyPCR amplification efficiency, calculated as -1 + 10^(-1/slope)
ICInternal Control - a target type excluded from quantification processing
Known QuantityPre-configured quantity value associated with a specific target/role combination
Standard CurveLinear relationship between log(quantity) and CT values used for sample quantification
Run TargetAggregated regression data for a specific target within a run
Quantifiable RoleRole types that participate in quantification: "Quantification" and "Quantification & PC"

Assumptions

  • Observations have been processed through upstream import rules before reaching this rule
  • Target and role information is available on each observation
  • Classification (positive/negative) has been determined before quantification processing
  • Configuration data (Known Quantities, Calculated Quantification Settings, Curve Control Range Settings) is loaded and accessible

Requirements

Quantity Assignment (REQ-RULES-QUANTVAL-001)

FR-QUANTVAL-001: Assign Known Quantities to Observations

The system shall assign quantity values to observations from the Known Quantities configuration when the quantity is not available from the runfile.

Inputs/Outputs

DirectionDataSource/Target
InputObservation (target, role, quantity)Run import
InputKnown Quantity Configuration (target, role, known_quantity)Kit configuration
OutputAssigned quantity valueObservation record

Acceptance Criteria

Quantity Assignment:

  • When an observation has no quantity from the runfile, retrieve quantity from Known Quantity Configuration matching the observation's target and role
  • Wells with role type "Quantification & PC" shall receive quantity assignment through this rule
  • The assigned quantity shall be set on the observation record

Configuration Matching:

  • Configuration lookup shall match both target and role for quantity assignment
  • The Known Quantity Configuration shall include target, role, and known_quantity fields
  • Both target AND role must match for quantity assignment

Error Handling

  • No matching Known Quantity Configuration: Handled by REQ-RULES-QUANTVAL-004 (STANDARD_WITHOUT_QUANT error)

Trace: Source: 3.0.0-Quantity Standard Validation (QUANT_VALIDATION) Row 1, 3.0.0-Quant Validation Rule - Consider Quantitative Standard Role Row 1 | Jira: BT-3179, BT-4377 | Tests: [BT-3452](#test-req-rules-quantval-001)


Observation Filtering (REQ-RULES-QUANTVAL-002)

FR-QUANTVAL-002: Exclude Non-Quantifiable Observations

The system shall NOT apply quantity validation to observations that meet any of the defined exclusion criteria.

Acceptance Criteria

Exclusion Conditions:

  • The rule shall NOT trigger for observations where the target type is IC (Internal Control)
  • The rule shall NOT trigger for observations classified as Negative
  • The rule shall NOT trigger for observations with a non-quantifiable role type

Processing Behavior:

  • Excluded observations shall retain null quantity values
  • Exclusion shall be evaluated before any quantity assignment or validation processing

Trace: Source: 3.0.0-Quantity Standard Validation (QUANT_VALIDATION) Row 2, Row 3, Row 4 | Tests: See scenarios


Linear Regression (REQ-RULES-QUANTVAL-003)

FR-QUANTVAL-003: Calculate Linear Regression Parameters

The system shall calculate linear regression parameters from quantitative control observations and store them on the run target.

Inputs/Outputs

DirectionDataSource/Target
InputQuantitative control observations (quantity, CT)Validated wells
OutputGradient, Intercept, R2, Efficiencyrun_target record

Acceptance Criteria

Regression Calculation:

  • The system shall calculate gradient (slope) from quantitative control data
  • The system shall calculate intercept from quantitative control data
  • The system shall calculate squared Pearson correlation coefficient (R2)
  • The system shall calculate PCR efficiency using formula: Efficiency = -1 + 10^(-1/slope)

Coordinate System:

  • Calculations shall use X coordinate = log(Quantity), Y coordinate = CT
  • The system shall calculate sample quantity using: x = (CT - intercept) / slope, then Quantity = 10^x

Role Inclusion:

  • Wells with role type "Quantification & PC" shall be included in linear regression calculation
  • Quantifiable role types shall include: "Quantification" and "Quantification & PC"

Storage:

  • Calculated parameters shall be stored on the run_target record

Assumptions

  • Linear regression calculation may be performed externally; this rule consumes pre-calculated values or triggers calculation through a separate mechanism

Trace: Source: 3.0.0-Quantity Standard Validation (QUANT_VALIDATION) Row 6, 3.0.0-Quant Validation Rule - Consider Quantitative Standard Role Row 2, 3.0.0-Remove Linear Regression Calculation Row 1 | Jira: BT-3179 | Tests: See scenarios


Standard Controls Validation (REQ-RULES-QUANTVAL-004)

FR-QUANTVAL-004: Validate Standard Controls Against Thresholds

The system shall validate standard controls against configured thresholds and generate appropriate well errors when validation fails.

Inputs/Outputs

DirectionDataSource/Target
InputCalculated regression parametersREQ-RULES-QUANTVAL-003
InputCalculated Quantification SettingsKit configuration
OutputValidation errorsWell records
OutputRegression parameters (conditional)run_target record

Acceptance Criteria

Missing Quantity Validation:

  • When both Machine Quantity and Known Quantity are absent for a quantitative observation, set well error STANDARD_WITHOUT_QUANT
  • When STANDARD_WITHOUT_QUANT is set, the observation quantity shall remain null

Minimum Controls Validation:

  • Require a minimum number of quantitative controls with unique quantity and CT values
  • Minimum control count shall be defined in Calculated Quantification Settings (min_controls), defaulting to 2
  • When insufficient controls exist, set error INSUFFICIENT_STANDARD_CONTROLS on all same-target quantitative control wells
  • When INSUFFICIENT_STANDARD_CONTROLS is set, do NOT set linear regression details on run_target (gradient, intercept, R2, efficiency remain null)

R2 Validation:

  • The R2 value shall be validated against min_r2 from Calculated Quantification Settings
  • When R2 is below threshold, set error BAD_R2 on all same-target quantitative control wells
  • When BAD_R2 is set, still calculate and store linear regression parameters on run_target

Gradient Validation:

  • The gradient shall be validated against min_slope and max_slope from Calculated Quantification Settings
  • When gradient is outside the configured range, set error BAD_GRADIENT on all same-target quantitative control wells
  • When BAD_GRADIENT is set, still calculate and store linear regression parameters on run_target

Efficiency Validation:

  • The PCR efficiency shall be validated against min_efficiency and max_efficiency from Calculated Quantification Settings
  • When efficiency is outside the configured range, set error BAD_EFFICIENCY on all same-target quantitative control wells
  • When BAD_EFFICIENCY is set, still calculate and store linear regression parameters on run_target

Error Propagation:

  • INSUFFICIENT_STANDARD_CONTROLS shall be the only error that prevents linear regression storage
  • BAD_R2, BAD_GRADIENT, and BAD_EFFICIENCY errors shall not prevent linear regression storage
  • Errors shall be applied to all same-target quantitative control wells, not just the failing well

Error Handling

  • No machine or known quantity: Set error STANDARD_WITHOUT_QUANT
  • Below minimum control count: Set error INSUFFICIENT_STANDARD_CONTROLS and prevent regression storage
  • R2 below threshold: Set error BAD_R2 (regression still stored)
  • Gradient below min_slope: Set error BAD_GRADIENT (regression still stored)
  • Gradient above max_slope: Set error BAD_GRADIENT (regression still stored)
  • Efficiency below min_efficiency: Set error BAD_EFFICIENCY (regression still stored)
  • Efficiency above max_efficiency: Set error BAD_EFFICIENCY (regression still stored)

Trace: Source: 3.0.0-Quantity Standard Validation (QUANT_VALIDATION) Row 5, Row 7, Row 8, Row 9, Row 10 | Jira: BT-3179 | Tests: [BT-3527, BT-3529, BT-3530, BT-3531](#test-req-rules-quantval-004)


CT Range Validation (REQ-RULES-QUANTVAL-005)

FR-QUANTVAL-005: Validate CT Values Against Range Bounds

The system shall validate observation CT values against configured range bounds and generate errors for out-of-range values.

Acceptance Criteria

Range Comparison:

  • The system shall compare observation final_ct against Curve Control Range Settings low_bound and upper_bound
  • When final_ct > upper_bound, set well error STANDARD_OUTSIDE_CT_RANGE
  • When final_ct < low_bound, set well error STANDARD_OUTSIDE_CT_RANGE

Boundary Handling:

  • When final_ct equals upper_bound (boundary), no CT range error shall be set
  • When final_ct equals low_bound (boundary), no CT range error shall be set
  • When final_ct is within bounds (exclusive of boundaries), no CT range error shall be set
  • Boundary values shall be inclusive (no error when CT equals bound)

Configuration Absence:

  • When no Curve Control Range Settings exist for the observation, no CT range error shall be set regardless of CT value
  • CT range validation shall use Curve Control Range Settings (distinct from Calculated Quantification Settings)

Error Handling

  • CT above upper bound: Set error STANDARD_OUTSIDE_CT_RANGE
  • CT below lower bound: Set error STANDARD_OUTSIDE_CT_RANGE
  • No configuration present: Do not perform CT range validation

Trace: Source: 3.0.0-CT Range Check Row 1 | Jira: BT-4603 | Tests: See scenarios


Error Resolution (REQ-RULES-QUANTVAL-006)

FR-QUANTVAL-006: Support Error Resolution for Specific Errors

The system shall support resolution application for specific Quant Validation Rule errors while prohibiting resolution for others.

Acceptance Criteria

Resolvable Errors:

  • STANDARD_OUTSIDE_CT_RANGE shall be resolvable
  • When a user selects a resolution for a well with STANDARD_OUTSIDE_CT_RANGE, the well shall have the selected resolution applied

Non-Resolvable Errors:

  • STANDARD_WITHOUT_QUANT shall NOT be resolvable
  • Resolution management shall prevent resolutions from being imported for non-resolvable errors

Assumptions

  • Resolution management is handled by a separate system component
  • The Quant Validation Rule defines which errors are resolvable but does not implement resolution application

Trace: Source: 3.0.0-Allow Resolution Management for Quant Validation Rule Row 1, Row 2 | Tests: See scenarios


Configuration Options

OptionDefaultDescriptionAffects
min_controls2Minimum unique quantitative controls required for regressionREQ-RULES-QUANTVAL-004
min_r2(none)Minimum acceptable R2 valueREQ-RULES-QUANTVAL-004
min_slope(none)Minimum acceptable gradient valueREQ-RULES-QUANTVAL-004
max_slope(none)Maximum acceptable gradient valueREQ-RULES-QUANTVAL-004
min_efficiency(none)Minimum acceptable PCR efficiencyREQ-RULES-QUANTVAL-004
max_efficiency(none)Maximum acceptable PCR efficiencyREQ-RULES-QUANTVAL-004
low_bound(none)Lower CT limit for range validationREQ-RULES-QUANTVAL-005
upper_bound(none)Upper CT limit for range validationREQ-RULES-QUANTVAL-005

Configuration Types

ConfigurationFieldsUsed By
Known Quantity Configurationtarget, role, known_quantityREQ-RULES-QUANTVAL-001, REQ-RULES-QUANTVAL-002
Calculated Quantification Settingstarget, role, min_controls, min_r2, min_slope, max_slope, min_efficiency, max_efficiencyREQ-RULES-QUANTVAL-003, REQ-RULES-QUANTVAL-004
Curve Control Range Settingslow_bound, upper_boundREQ-RULES-QUANTVAL-005

Open Questions

IDQuestionSourceOwnerDate Raised
OQ-001No UI detail specified in source material; confirm none is required for this backend rule.UI Detail@tbd2026-01-22

Notes

  • Standard controls with quantities (e.g., 1E2, 1E4, 1E6, 1E8) and corresponding CT values create the linear regression curve
  • Patient sample quantification is calculated by inverting the regression equation
  • The rule is part of the run import pipeline and processes observations after upstream rules have established basic observation data
  • Rule programmatic name: QUANT_VALIDATION

Error Code Summary

Error CodeTriggerResolvableEffect on Run Target
STANDARD_WITHOUT_QUANTNo machine or known quantityNoN/A
INSUFFICIENT_STANDARD_CONTROLSBelow minimum control countN/APrevents storage
BAD_R2R2 below thresholdN/AParameters still stored
BAD_GRADIENTSlope outside rangeN/AParameters still stored
BAD_EFFICIENCYEfficiency outside rangeN/AParameters still stored
STANDARD_OUTSIDE_CT_RANGECT outside boundsYesN/A

UI Notes (Illustrative)

[REVIEW REQUIRED: No UI-specific details identified in source material. This rule operates within the backend processing pipeline. Verify if any UI elements exist for error display or resolution management.]


Implementation (Illustrative)

ComponentLocation
Rule ClassAnalyzer/Rules/QuantValidationRule.php
Fill QuantityAnalyzer/Rules/Concerns/QuantValidationRule/FillObservationQuantity.php
CT ValidationAnalyzer/Rules/Concerns/QuantValidationRule/ValidateCT.php
Resolution HandlingAnalyzer/Rules/Concerns/QuantValidationRule/HandleResolutions.php
Error SettingAnalyzer/Rules/Concerns/QuantValidationRule/SetErrorToSeriesWells.php

Traceability Matrix

RequirementTitleVerificationImplementationTest CasesStatus
REQ-RULES-QUANTVAL-001Known Quantity AssignmentTestQuantValidationRule, FillObservationQuantityBT-3452Draft
REQ-RULES-QUANTVAL-002Observation Exclusion CriteriaTestQuantValidationRule.shouldNotBeQuantified()[Pending]Draft
REQ-RULES-QUANTVAL-003Linear Regression CalculationTestQuantValidationRule[Pending]Draft
REQ-RULES-QUANTVAL-004Standard Controls ValidationTestSetErrorToSeriesWellsBT-3527, BT-3529, BT-3530, BT-3531Draft
REQ-RULES-QUANTVAL-005CT Range ValidationTestValidateCT[Pending]Draft
REQ-RULES-QUANTVAL-006Error Resolution SupportTestHandleResolutions[Pending]Draft

Acceptance Tests

Test: REQ-RULES-QUANTVAL-001

Back to requirement

Test: Basic Known Quantity Assignment

Given: Known Quantity Configuration with target A, role A, known_quantity 1000
And: Runfile with well A1 containing observation with no quantity
When: Import through quant validation rule
Then: Well A1 observation quantity shall be 1000

Test: Quantification & PC Role Assignment

Given: Known Quantity Configuration with target Target A, role Role A, known_quantity x
And: Well A1 with observation for target Target A, role Role A, quantity null
And: Role A has role type "Quantification & PC"
When: Well A1 executed through Quant Validation Rule
Then: Well A1 observation quantity shall be x

Test: REQ-RULES-QUANTVAL-002

Back to requirement

Test: IC Target Exclusion

Given: Known Quantity Configuration with target A (type IC), role A, known_quantity 1000
And: Runfile with well A1
When: Import through quant validation rule
Then: Well A1 observation quantity shall be null

Test: Negative Classification Exclusion

Given: Known Quantity Configuration with target A, role A, known_quantity 1000
And: Runfile with well A1 containing observation classified as Negative
When: Import through quant validation rule
Then: Well A1 observation quantity shall be null

Test: Non-Quantifiable Role Exclusion

Given: Known Quantity Configuration with target A, role A (non-quantification type), known_quantity 1000
And: Runfile with well A1
When: Import through quant validation rule
Then: Well A1 observation quantity shall be null

Test: REQ-RULES-QUANTVAL-003

Back to requirement

Test: Linear Regression Output

Given: Runfile with quantitative control wells
When: Import through quant validation rule
Then: run_target shall have gradient -1
And: run_target shall have intercept 33
And: run_target shall have R2 1
And: run_target shall have efficiency 9

Test: Quantification & PC Role Included

Given: Well A1 with role Role A, target Target A, quantity 10000, ct 30
And: Well A2 with role Role A, target Target A, quantity 1000, ct 31
And: Role A has role type "Quantification & PC"
When: Wells executed through Quant Validation Rule
Then: run_target A shall have slope -1
And: run_target A shall have intercept 34

Test: REQ-RULES-QUANTVAL-004

Back to requirement

Test: STANDARD_WITHOUT_QUANT Error

Given: No Known Quantity Configuration for target and role
And: Runfile with well A1 containing no machine quantity
When: Import through quant validation rule
Then: Well A1 shall have error STANDARD_WITHOUT_QUANT
And: Well A1 observation quantity shall be null

Test: INSUFFICIENT_STANDARD_CONTROLS (default threshold)

Given: No Calculated Quantification Settings (default min_controls 2)
And: Runfile with only 1 standard control
When: Import through quant validation rule
Then: Wells A1, B1 shall have error INSUFFICIENT_STANDARD_CONTROLS
And: run_target gradient shall be null
And: run_target intercept shall be null
And: run_target R2 shall be null
And: run_target efficiency shall be null

Test: INSUFFICIENT_STANDARD_CONTROLS (configured threshold)

Given: Calculated Quantification Settings with target A, role Quantitative 1, min_controls 3
And: Runfile with only 2 standard controls
When: Import through quant validation rule
Then: Wells A1, B1 shall have error INSUFFICIENT_STANDARD_CONTROLS
And: run_target gradient shall be null
And: run_target intercept shall be null
And: run_target R2 shall be null
And: run_target efficiency shall be null

Test: BAD_R2 Error

Given: Calculated Quantification Settings with target A, role Quantitative 1, min_r2 1
And: Runfile with controls producing R2 0.964
When: Import through quant validation rule
Then: Wells A1, B1, C1 shall have error BAD_R2
And: run_target gradient shall be -1
And: run_target intercept shall be 33
And: run_target R2 shall be 1
And: run_target efficiency shall be 9

Test: BAD_GRADIENT Error (below minimum)

Given: Calculated Quantification Settings with target A, role Quantitative 1, min_slope 0
And: Runfile producing gradient -1
When: Import through quant validation rule
Then: Wells A1, B1, C1 shall have error BAD_GRADIENT
And: run_target regression parameters shall still be stored

Test: BAD_GRADIENT Error (above maximum)

Given: Calculated Quantification Settings with target A, role Quantitative 1, max_slope -2
And: Runfile producing gradient -1
When: Import through quant validation rule
Then: Wells A1, B1, C1 shall have error BAD_GRADIENT
And: run_target regression parameters shall still be stored

Test: BAD_EFFICIENCY Error (below minimum)

Given: Calculated Quantification Settings with target A, role Quantitative 1, min_efficiency 10
And: Runfile producing efficiency 9
When: Import through quant validation rule
Then: Wells A1, B1, C1 shall have error BAD_EFFICIENCY
And: run_target regression parameters shall still be stored

Test: BAD_EFFICIENCY Error (above maximum)

Given: Calculated Quantification Settings with target A, role Quantitative 1, max_efficiency 8
And: Runfile producing efficiency 9
When: Import through quant validation rule
Then: Wells A1, B1, C1 shall have error BAD_EFFICIENCY
And: run_target regression parameters shall still be stored

Test: REQ-RULES-QUANTVAL-005

Back to requirement

Test: CT Above Upper Bound

Given: Curve Control Range Settings with low_bound 28, upper_bound 30
And: Observation with final_ct 31
When: CT range validation executes
Then: Well shall have error STANDARD_OUTSIDE_CT_RANGE

Test: CT At Upper Bound (inclusive)

Given: Curve Control Range Settings with low_bound 28, upper_bound 30
And: Observation with final_ct 30
When: CT range validation executes
Then: Well shall have no CT range error

Test: CT Within Range

Given: Curve Control Range Settings with low_bound 28, upper_bound 30
And: Observation with final_ct 29
When: CT range validation executes
Then: Well shall have no CT range error

Test: CT At Lower Bound (inclusive)

Given: Curve Control Range Settings with low_bound 28, upper_bound 30
And: Observation with final_ct 28
When: CT range validation executes
Then: Well shall have no CT range error

Test: CT Below Lower Bound

Given: Curve Control Range Settings with low_bound 28, upper_bound 30
And: Observation with final_ct 27
When: CT range validation executes
Then: Well shall have error STANDARD_OUTSIDE_CT_RANGE

Test: No Configuration - Low CT

Given: No Curve Control Range Settings for observation
And: Observation with final_ct 27
When: CT range validation executes
Then: Well shall have no CT range error

Test: No Configuration - High CT

Given: No Curve Control Range Settings for observation
And: Observation with final_ct 31
When: CT range validation executes
Then: Well shall have no CT range error

Test: REQ-RULES-QUANTVAL-006

Back to requirement

Test: Apply Resolution to Resolvable Error

Given: Well A1 with error_code STANDARD_OUTSIDE_CT_RANGE
When: User selects a resolution
Then: Well A1 shall have selected resolution applied

Design DocumentRelevant Sections
SDD AlgorithmsQuantification Algorithm

Appendix: Process Artifacts

Completion Checklist

  • All requirements are capability-level (describe behavior, not UI)
  • Requirement variants consolidated (no requirement explosion) - N/A, no consolidation needed for RULES domain
  • 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 - One open question pending
  • Consolidations documented in Reviewer Notes with reversibility info
  • Module can survive a full UI redesign unchanged
  • Refinements folded into acceptance criteria
  • Traceability matrix is complete

Reviewer Notes

No Consolidation Applied

All six requirements in this domain represent genuinely distinct system capabilities:

RequirementCapabilityJustification
REQ-RULES-QUANTVAL-001Known Quantity AssignmentRetrieves and assigns quantity values from configuration
REQ-RULES-QUANTVAL-002Observation ExclusionFilters out IC, negative, and non-quantifiable observations
REQ-RULES-QUANTVAL-003Linear Regression CalculationComputes slope, intercept, R2, efficiency
REQ-RULES-QUANTVAL-004Standard Controls ValidationValidates thresholds and generates multiple error types
REQ-RULES-QUANTVAL-005CT Range ValidationSeparate validation against CT bounds
REQ-RULES-QUANTVAL-006Error Resolution SupportDefines which errors are resolvable

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 file: /home/aron/code/req_docs/output/pilot/rules/rule-quant-validation/rule-quant-validation-restructured.md