Linear Regression Validation Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: LINEAR_REGRESSION_VALIDATION rule for calculating and validating regression parameters from quantification standards Domain: RULES-LINREG Precedence: After Quant Validation Rule
Statement
The system shall calculate and validate linear regression parameters (slope, intercept, R2, efficiency) from valid standard control coordinates within the PCR analysis workflow.
The rule excludes error wells from calculations, classifies insufficient standard control errors based on available well count, and provides resolution management for validation errors. Series-level resolutions propagate to all wells with matching error codes, and users can exclude specific wells from regression via the SKIP_FROM_LINEAR_REGRESSION resolution.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-LINREG-001 | Calculates slope, intercept, R2, and efficiency from standard coordinates | HIGH | Draft |
| REQ-RULES-LINREG-002 | Excludes error wells from regression coordinate calculations | HIGH | Draft |
| REQ-RULES-LINREG-003 | Classifies ONE_STANDARD_CONTROL vs INSUFFICIENT_STANDARD_CONTROLS errors | HIGH | Draft |
| REQ-RULES-LINREG-004 | Allows user resolutions for regression errors (except ONE_STANDARD_CONTROL) | HIGH | Draft |
| REQ-RULES-LINREG-005 | Propagates series-level resolutions to matching wells | HIGH | Draft |
| REQ-RULES-LINREG-006 | Excludes wells from regression via SKIP_FROM_LINEAR_REGRESSION | HIGH | Draft |
Key Integration Points: Quant Validation Rule (upstream), Quantification Settings (thresholds), Resolution Management
Rule Summary
| Property | Value |
|---|---|
| Name | LINEAR_REGRESSION_VALIDATION |
| Precedence | After Quant Validation Rule |
| Triggers | When processing standard control wells for quantification |
| Output | Slope, intercept, R2, efficiency values; error codes; resolutions |
Rule Flowchart (Illustrative)
This diagram illustrates the core validation and resolution logic. The actual calculation formulas and threshold comparisons follow standard mathematical operations.
Definitions
| Term | Definition |
|---|---|
| Linear Regression | Statistical method calculating slope, intercept, R2, and efficiency from standard control coordinates |
| R2 (R-squared) | Correlation coefficient measuring regression fit quality |
| CT (Cycle Threshold) | The cycle number at which fluorescence crosses the threshold |
| Efficiency | PCR amplification efficiency calculated from the regression slope |
| Series | A group of related standard control wells processed together |
| Resolution | User action to acknowledge, suppress, or dismiss a validation error |
| LIMS Code | Laboratory Information Management System code assigned to a well |
Assumptions
- Standard control wells have valid concentration and CT values before regression calculation
- Quantification Settings are configured with appropriate threshold values
- The upstream Quant Validation Rule has completed processing before this rule executes
- Users applying resolutions have appropriate permissions
Requirements
Regression Calculation (REQ-RULES-LINREG-001)
FR-LINREG-001: Calculate Linear Regression Parameters
The system shall calculate and validate linear regression parameters (slope, intercept, R2, efficiency) from valid standard control coordinates within the Linear Regression Validation rule.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Standard control wells (concentration, CT) | Series wells |
| Input | Validation thresholds (R2, slope, efficiency) | Quantification Settings |
| Output | Slope, intercept, R2, efficiency | Regression results |
| Output | Validation errors | Well records |
Acceptance Criteria
Core Calculation:
- Calculate linear regression slope from valid standard control coordinates
- Calculate linear regression intercept from valid standard control coordinates
- Calculate R-squared (R2) correlation coefficient
- Calculate efficiency from the regression parameters
- Validate calculated values against configured thresholds
- All calculation logic shall match the previous implementation from Quant Validation Rule
Formula Specifications:
- Slope:
m = sum((x - x_mean)(y - y_mean)) / sum((x - x_mean)^2) - Intercept:
b = y_mean - m * x_mean - R2:
R2 = 1 - (SS_res / SS_tot) - Efficiency:
efficiency = 10^(-1/slope) - 1
Coordinate System:
- Use log(concentration) and CT values as coordinates for regression calculation
Trace: Source: 3.0.0-Create and Validate Linear Regression (Row 1) | Jira: BT-4842 | Tests: See scenarios
Error Well Handling (REQ-RULES-LINREG-002)
FR-LINREG-002: Exclude Error Wells from Regression Calculation
The system shall exclude control wells with error status from linear regression coordinate calculations.
Acceptance Criteria
Exclusion Rules:
- Wells with any error type shall be excluded from regression coordinate calculations
- Excluded error wells shall not contribute to slope or intercept calculations
- Remaining valid wells shall still undergo regression calculation
- Error wells shall retain their original error code after exclusion
Insufficient Wells After Exclusion:
- If exclusion results in insufficient valid wells, the system shall raise appropriate error on remaining wells
- Given wells A1, A2 in series, when A1 has any error and A2 is executed through quant validation rule, then A2 shall receive error INSUFFICIENT_STANDARD_CONTROLS
- Given wells A1, A2 in series, when executed through quant validation rule and A1 gets error before coordinate calculation, then A1 shall retain its particular error and A2 shall receive error INSUFFICIENT_STANDARD_CONTROLS
Trace: Source: 3.0.0-Ignore Error Wells From Coordinates (Row 1) | Jira: BT-4842 | Tests: BT-4863, See scenarios
Error Classification (REQ-RULES-LINREG-003)
FR-LINREG-003: Classify Insufficient Standard Control Errors
The system shall distinguish between ONE_STANDARD_CONTROL and INSUFFICIENT_STANDARD_CONTROLS errors based on the number of available standard controls.
Acceptance Criteria
Error Classification Logic:
| Valid Wells | min_controls Config | Error Code |
|---|---|---|
| count = 1 | Any | ONE_STANDARD_CONTROL |
| 1 < count < min_controls | e.g., 3 | INSUFFICIENT_STANDARD_CONTROLS |
| count >= min_controls | e.g., 3 | No error (proceed) |
Classification Rules:
- If standards count is less than 2, the system shall raise error ONE_STANDARD_CONTROL
- If standards count is 2 or more AND less than configured min_controls, the system shall raise error INSUFFICIENT_STANDARD_CONTROLS
- The min_controls threshold shall be configurable in Quantification Settings
- Each error code shall be mutually exclusive - only one shall be raised based on count
Trace: Source: 3.0.0-Allow Resolution For Linear Regression Rule (Row 1) | Jira: BT-4845 | Tests: See scenarios
Resolution Management (REQ-RULES-LINREG-004)
FR-LINREG-004: Apply Resolutions to Linear Regression Errors
The system shall allow users to apply resolutions to wells that have linear regression validation errors, with specific errors designated as resolvable or non-resolvable.
Acceptance Criteria
Resolvable Errors:
- The following errors shall be resolvable: INSUFFICIENT_STANDARD_CONTROLS, BAD_R2, BAD_GRADIENT, BAD_EFFICIENCY
- The error ONE_STANDARD_CONTROL shall NOT be resolvable
- Non-resolvable errors shall be prevented from import by resolution management
Resolution Behavior:
- When user selects a resolution for a well, the well shall receive the selected resolution code
- SKIP resolution shall not prevent the rule from calculating linear regression
- SKIP resolution shall only skip the errors from the series well while calculation proceeds
- Given wells A1 (concentration=10, ct=16), A2 (concentration=1000, ct=26) in series, when A1 has resolution code SKIP, then wells A1 and A2 shall have no error, and calculated linear regression slope shall be -2, and calculated linear regression intercept shall be 36
- Given well A1 has any resolvable regression error, when user selects a resolution, then A1 shall have the selected resolution applied
Trace: Source: 3.0.0-Allow Resolution For Linear Regression Rule (Rows 2, 3, 4) | Jira: BT-4845 | Tests: See scenarios
Series-Level Resolutions (REQ-RULES-LINREG-005)
FR-LINREG-005: Propagate Series-Level Resolutions
The system shall propagate series-level resolutions to all wells in a series that share the same error code, without overriding wells with different error codes or LIMS codes.
Acceptance Criteria
Series-Level Resolution Types:
- Series-level resolutions shall include: RESOLVE_INSUFFICIENT_STANDARD_CONTROLS, RESOLVE_BAD_R2, RESOLVE_BAD_GRADIENT, RESOLVE_BAD_EFFICIENCY
Propagation Rules:
- When series-level resolution is applied to one well, all wells with matching error code in series shall receive the resolution
- Wells with different error codes shall retain their original error code (not overridden)
- Wells with LIMS codes shall retain their LIMS code (not overridden)
- Series-level resolution shall only affect wells with the specific error being resolved
Propagation Examples:
- Given wells A1, A2, A3 all with error code X and resolution RESOLVE_X targets error code X, when user applies resolution RESOLVE_X to well A1, then A1, A2, and A3 shall all be resolved as RESOLVE_X
- Given wells A1 (error X), A2 (error Y), A3 (lims L) and resolution RESOLVE_X targets error code X, when user applies resolution RESOLVE_X to well A1, then A1 shall be resolved as RESOLVE_X, A2 shall keep error code Y, and A3 shall keep lims code L
- The system shall preserve wells with error code Y or LIMS code L when series-level resolution targets error code X only
Trace: Source: 3.0.0-Allow Resolution For Linear Regression Rule (Rows 5, 6) | Jira: BT-4845 | Tests: See scenarios
Well Exclusion via Resolution (REQ-RULES-LINREG-006)
FR-LINREG-006: Exclude Wells from Regression via Resolution
The system shall allow users to exclude specific wells from the linear regression calculation by applying the SKIP_FROM_LINEAR_REGRESSION resolution, triggering recalculation of regression parameters.
Acceptance Criteria
Exclusion Behavior:
- Resolution code SKIP_FROM_LINEAR_REGRESSION shall exclude a well from regression calculation
- Excluded well coordinates shall not be used in slope calculation
- Excluded well coordinates shall not be used in intercept calculation
Recalculation:
- Remaining wells shall be recalculated for new regression line
- The recalculated slope and intercept shall reflect only non-excluded wells
- Given wells A1 (concentration=10, ct=16), A2 (concentration=1000, ct=26) in series, when A1 has resolution code SKIP_FROM_LINEAR_REGRESSION, then calculated linear regression slope shall be -0.5 and calculated linear regression intercept shall be 18
Trace: Source: 3.0.0-Allow Resolution For Linear Regression Rule (Row 7) | Jira: BT-4845 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
min_controls | 2 | Minimum number of valid standard controls required for regression calculation | REQ-RULES-LINREG-003 |
r2_threshold | [Configurable] | Minimum acceptable R2 value | REQ-RULES-LINREG-001 |
slope_min | [Configurable] | Minimum acceptable slope value | REQ-RULES-LINREG-001 |
slope_max | [Configurable] | Maximum acceptable slope value | REQ-RULES-LINREG-001 |
efficiency_min | [Configurable] | Minimum acceptable efficiency value | REQ-RULES-LINREG-001 |
efficiency_max | [Configurable] | Maximum acceptable efficiency value | REQ-RULES-LINREG-001 |
Error Codes Reference
| Error Code | Resolvable | Series-Level | Description |
|---|---|---|---|
| ONE_STANDARD_CONTROL | No | N/A | Only one standard control available |
| INSUFFICIENT_STANDARD_CONTROLS | Yes | Yes | Fewer than configured minimum controls |
| BAD_R2 | Yes | Yes | R-squared below threshold |
| BAD_GRADIENT | Yes | Yes | Slope outside acceptable range |
| BAD_EFFICIENCY | Yes | Yes | Efficiency outside acceptable range |
Resolution Codes Reference
| Resolution Code | Scope | Description |
|---|---|---|
| SKIP | Well | Skip errors, continue calculation |
| SKIP_FROM_LINEAR_REGRESSION | Well | Exclude from regression calculation |
| RESOLVE_INSUFFICIENT_STANDARD_CONTROLS | Series | Resolve insufficient standards error |
| RESOLVE_BAD_R2 | Series | Resolve bad R2 error |
| RESOLVE_BAD_GRADIENT | Series | Resolve bad gradient error |
| RESOLVE_BAD_EFFICIENCY | Series | Resolve bad efficiency error |
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | No UI-specific details identified in source material. Confirm this rule operates as backend processing without direct UI components. | UI Detail | @tbd | 2026-01-22 |
Notes
- This rule consolidates linear regression logic previously distributed across rules
- The rule operates on standard control wells within a series
- Linear Regression Rule does not handle resolution for ONE_STANDARD_CONTROL
- Resolution management prevents non-resolvable errors from being imported to the system
- The excluded well remains in the series but does not contribute to the regression line (for SKIP_FROM_LINEAR_REGRESSION)
Implementation (Illustrative)
| Component | Location |
|---|---|
| LinearRegressionValidationRule | Analyzer/Rules/LinearRegressionValidationRule.php |
| ValidateCoordinates | Analyzer/Rules/Concerns/QuantValidationRule/ValidateCoordinates.php |
| ValidateSlope | Analyzer/Rules/Concerns/QuantValidationRule/ValidateSlope.php |
| ValidateR2 | Analyzer/Rules/Concerns/QuantValidationRule/ValidateR2.php |
| ValidateEfficiency | Analyzer/Rules/Concerns/QuantValidationRule/ValidateEfficiency.php |
| HandleResolutions | Analyzer/Rules/Concerns/QuantValidationRule/HandleResolutions.php |
| SetErrorToSeriesWells | Analyzer/Rules/Concerns/QuantValidationRule/SetErrorToSeriesWells.php |
| LinearRegressionGenerator | Support/LinearRegressionGenerator.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-LINREG-001 | Calculate Linear Regression | Test | LinearRegressionValidationRule, LinearRegressionGenerator | [Pending] | Draft |
| REQ-RULES-LINREG-002 | Exclude Error Wells | Test | ValidateCoordinates | BT-4863 | Draft |
| REQ-RULES-LINREG-003 | Classify Insufficient Standard Control Errors | Test | ValidateCoordinates | [Pending] | Draft |
| REQ-RULES-LINREG-004 | Apply Resolutions to Errors | Test | HandleResolutions | [Pending] | Draft |
| REQ-RULES-LINREG-005 | Propagate Series-Level Resolutions | Test | HandleResolutions | [Pending] | Draft |
| REQ-RULES-LINREG-006 | Exclude Wells via Resolution | Test | HandleResolutions, ValidateCoordinates | [Pending] | Draft |
Acceptance Tests
Test: REQ-RULES-LINREG-001
Test: Verify regression calculation in dedicated rule
Given: A series with valid standard control wells
When: Linear Regression Validation rule executes
Then: Slope is calculated from well coordinates
And: Intercept is calculated from well coordinates
And: R2 correlation is calculated
And: Efficiency is calculated
And: All values are validated against thresholds
Test: REQ-RULES-LINREG-002
Test: Error well exclusion - insufficient remaining
Given: wells A1, A2 in series
When: A1 has <Any Error>
And: A2 is processed through quant validation rule
Then: A2 receives error INSUFFICIENT_STANDARD_CONTROLS
Test: Error from quant validation propagation
Given: wells A1, A2 in series
When: Execution through quant validation rule
And: Error occurs on A1 before coordinate calculation
Then: A1 retains particular error from quant validation rule
And: A2 receives error INSUFFICIENT_STANDARD_CONTROLS
Test: REQ-RULES-LINREG-003
Test: Single standard control
Given: Quantification Settings min_controls = 3
When: Available wells = 1
Then: Error code = ONE_STANDARD_CONTROL
Test: Below configured minimum
Given: Quantification Settings min_controls = 3
When: Available wells = 2
Then: Error code = INSUFFICIENT_STANDARD_CONTROLS
Test: REQ-RULES-LINREG-004
Test: SKIP resolution allows calculation
Given: wells A1, A2 with concentrations and CT values
| well | concentration | ct |
| A1 | 10 | 16 |
| A2 | 1000 | 26 |
When: A1 has resolution code SKIP
Then: A1 has no error
And: A2 has no error
And: Linear regression slope = -2
And: Linear regression intercept = 36
Test: Resolution selection applies to well
Given: Well A1 has resolvable regression error
When: User selects a resolution for A1
Then: A1 has selected resolution applied
Test: REQ-RULES-LINREG-005
Test: Resolution propagates to all matching wells
Given: Series wells A1, A2, A3 all with error code X
And: Resolution RESOLVE_X targets error code X
When: User applies RESOLVE_X to well A1
Then: A1 is resolved as RESOLVE_X
And: A2 is resolved as RESOLVE_X
And: A3 is resolved as RESOLVE_X
Test: Resolution does not override different errors
Given: Series wells A1 (error X), A2 (error Y), A3 (lims L)
And: Resolution RESOLVE_X targets error code X
When: User applies RESOLVE_X to well A1
Then: A1 is resolved as RESOLVE_X
And: A2 keeps error code Y
And: A3 keeps lims code L
Test: REQ-RULES-LINREG-006
Test: Well exclusion recalculates regression
Given: Series wells with known coordinates
| well | concentration | ct |
| A1 | 10 | 16 |
| A2 | 1000 | 26 |
When: A1 has resolution code SKIP_FROM_LINEAR_REGRESSION
Then: Recalculated linear regression slope = -0.5
And: Recalculated linear regression intercept = 18
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Linear Regression Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants conservatively preserved (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 via error classification requirements
- Open questions documented with owners assigned
- Conservative conversion documented in Reviewer Notes
- Module can survive a full UI redesign unchanged
- Refinements folded into acceptance criteria
- Traceability matrix is complete
- All Gherkin test scenarios preserved
- Statement section added for quick understanding
- Mermaid flowchart added (marked Illustrative)
- Tests moved to end with back-links
- Blank lines before all bullet lists
Reviewer Notes
Conservative Conversion Applied
This domain uses conservative consolidation per RULES domain guidelines:
- All 6 source requirements preserved individually
- All test scenarios preserved as detailed acceptance criteria
- No aggressive merging of error/resolution variants
- Given/When/Then scenarios converted to detailed AC statements
| Source Item | Disposition |
|---|---|
| REQ-RULES-LINREG-001 | Preserved as REQ-RULES-LINREG-001 (FR-LINREG-001) |
| REQ-RULES-LINREG-002 | Preserved as REQ-RULES-LINREG-002 (FR-LINREG-002) |
| REQ-RULES-LINREG-003 | Preserved as REQ-RULES-LINREG-003 (FR-LINREG-003) |
| REQ-RULES-LINREG-004 | Preserved as REQ-RULES-LINREG-004 (FR-LINREG-004) |
| REQ-RULES-LINREG-005 | Preserved as REQ-RULES-LINREG-005 (FR-LINREG-005) |
| REQ-RULES-LINREG-006 | Preserved as REQ-RULES-LINREG-006 (FR-LINREG-006) |
Rationale: Analytics rules require precise behavior specification. Error classification, resolution propagation, and calculation exclusion are distinct capabilities that must be independently testable.
Reversibility: Source file: output/srs/rules/rule-linear-regression-validation.md