CT Cutoff Rule (WFINALCLS)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Evaluates CT values against configured cutoff boundaries to determine final classification Domain: RULES-CTCUTOFF Precedence: After thermocycler import, before reporting
Statement
The system shall evaluate CT (Cycle Threshold) values against configured cutoff boundaries to set final classification to Negative when values exceed the threshold.
The rule implements specimen-type-aware reporting selection when enabled, handles NULL values asymmetrically (NULL CT triggers Negative, NULL Quantity preserves classification), and reports CUTOFF_LIMITS_MISSED errors when configuration is missing.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-CTCUTOFF-001 | Sets classification to Negative when CT exceeds cutoff | HIGH | Draft |
| REQ-RULES-CTCUTOFF-002 | Selects reporting configuration based on specimen type | HIGH | Draft |
| REQ-RULES-CTCUTOFF-003 | Treats NULL CT as boundary exceeded (sets Negative) | HIGH | Draft |
| REQ-RULES-CTCUTOFF-004 | Preserves classification when Quantity is NULL | HIGH | Draft |
| REQ-RULES-CTCUTOFF-005 | Reports CUTOFF_LIMITS_MISSED error for missing config | HIGH | Draft |
Key Integration Points: Thermocycler instruments, Kit Configuration, Reporting Configuration, Classification Engine
Rule Summary
| Property | Value |
|---|---|
| Name | WFINALCLS |
| Triggers | CT value evaluation against cutoff boundaries |
| Output | Sets machine_cls and dx_ai.cls fields |
| Default Cutoff | 40 |
Rule Flowchart (Illustrative)
This diagram illustrates the core decision logic. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| CT (Cycle Threshold) | The number of PCR cycles required to detect a target; lower values indicate higher viral load |
| WFINALCLS | Rule identifier for "Set Final Classification Based on Cutoffs" |
| machine_cls | Machine-determined classification field |
| dx_ai.cls | Diagnostic AI classification field |
| LoD (Limit of Detection) | The lowest quantity of a target that can be reliably detected |
| Specimen Type | The type of biological sample (e.g., Plasma, Serum) |
Assumptions
- Cutoff configuration exists for the target being evaluated
- Reporting configurations are defined for applicable specimen types
- The observation has a valid target_id unless error handling applies
- Rule mappings exist for each specimen type that should use specimen-specific reporting
- Reporting configurations have "last modified" timestamps for fallback ordering
Requirements
Core CT Evaluation (REQ-RULES-CTCUTOFF-001)
FR-CTCUTOFF-001: Set Classification to Negative When CT Exceeds Cutoff
The system shall set the final classification to Negative when the CT (Cycle Threshold) value exceeds the configured cutoff boundary.
Acceptance Criteria
Classification Setting:
- When CT value exceeds the configured cutoff boundary, the system shall set machine_cls to Negative
- When CT value exceeds the configured cutoff boundary, the system shall set dx_ai.cls to Negative
- When CT exceeds the cutoff, the system shall set both machine_cls AND dx_ai.cls fields to Negative
Boundary Behavior:
- When CT value is within the configured boundary (CT <= cutoff), the system shall not modify the classification
Configuration:
- The cutoff value shall be configurable per target
- The default CT cutoff threshold shall be 40
Trace: Source: 3.0.0-Ct cutoff rule - WFINALCLS (Context, Row 1) | Jira: BT-467 | CST: CST-155 | Epic: BT-471 | Tests: See scenarios
Specimen-Based Reporting (REQ-RULES-CTCUTOFF-002)
FR-CTCUTOFF-002: Select Reporting Configuration Based on Specimen Type
The system shall select the reporting configuration based on specimen type when sample type usage is enabled in the WFINALCLS rule.
Acceptance Criteria
Specimen Type Matching:
- When use sample type is enabled, the system shall match the observation's specimen type to the corresponding reporting configuration
- When use sample type is disabled, the system shall use the last modified reporting configuration regardless of specimen type
Behavioral Examples:
- Given: Reporting for Plasma with CT Upper Boundary=30, Reporting for Serum with CT Upper Boundary=10, Rule mappings for WFINALCLS to both specimen types, Runfile with Well A1 (Plasma, CT=25) and Well A2 (Serum, CT=25); When: Use sample type is enabled; Then: A1 shall have Positive classification (25 < 30), A2 shall have Negative classification (25 > 10)
- Given: Same configuration as above; When: Use sample type is disabled; Then: Both A1 and A2 shall have Negative classification (using last modified reporting with boundary=10)
Trace: Source: 3.0.0-Should use unique reporting based on specimen (Row 1) | Jira: BT-4205 | Test Jira: BT-4283 | Epic: BT-4204 | Tests: See scenarios
NULL Value Handling (REQ-RULES-CTCUTOFF-003 & 004)
FR-CTCUTOFF-003: Treat NULL CT as Boundary Exceeded
The system shall treat NULL CT values as having exceeded the cutoff boundary and set classification to Negative.
Acceptance Criteria
NULL CT Behavior:
- Given: An observation with final CT value = NULL; When: The observation is executed through the WFINALCLS rule; Then: The observation classification shall be set to Negative
- NULL CT handling shall apply regardless of other field values
- NULL CT shall be treated as boundary exceeded (distinct from NULL Quantity behavior which preserves classification)
Asymmetric NULL Handling:
- The system shall handle NULL values asymmetrically: NULL CT shall be treated as boundary exceeded (set Negative); NULL Quantity shall be treated as boundary NOT passed (do not modify)
Trace: Source: 3.0.0-Consider NULL for CT and Quantity (Row 1) | Jira: BT-4845 | Related: REQ-RULES-CTCUTOFF-004 | Tests: See scenarios
FR-CTCUTOFF-004: Preserve Classification When Quantity is NULL
The system shall NOT modify classification when the Quantity value is NULL in the WFINALCLS rule.
Acceptance Criteria
NULL Quantity Behavior:
- Given: An observation with Quantity value = NULL; When: The observation is executed through the WFINALCLS rule; Then: The observation classification shall NOT be modified by the WFINALCLS rule
- The existing classification shall be preserved when Quantity is NULL
- NULL Quantity shall be treated as boundary NOT passed (distinct from NULL CT behavior which sets Negative)
Asymmetric NULL Handling:
- The system shall handle NULL values asymmetrically: NULL CT shall be treated as boundary exceeded (set Negative); NULL Quantity shall be treated as boundary NOT passed (do not modify)
Trace: Source: 3.0.0-Consider NULL for CT and Quantity (Row 2) | Jira: BT-4845 | Related: REQ-RULES-CTCUTOFF-003 | Tests: See scenarios
Error Handling (REQ-RULES-CTCUTOFF-005)
FR-CTCUTOFF-005: Report CUTOFF_LIMITS_MISSED Error for Missing Configuration
The system shall set the CUTOFF_LIMITS_MISSED error when the WFINALCLS rule cannot find cutoff configuration for an observation.
Acceptance Criteria
Error Triggering:
- Given: A well with an observation where target_id = null; When: The WFINALCLS rule analyzes the observation; Then: The well shall have the CUTOFF_LIMITS_MISSED error set
- The error code shall be exactly: CUTOFF_LIMITS_MISSED
- The error shall be set when the observation cannot be matched to any configured cutoff limits
Error Conditions
| Condition | Response |
|---|---|
| target_id is NULL | Set CUTOFF_LIMITS_MISSED error on the well |
| Cutoff configuration not found for target | Set CUTOFF_LIMITS_MISSED error on the well |
Trace: Source: 3.0.0-WFINALCLS rule - add CUTOFF_LIMITS_MISSED error (Row 1) | Jira: BT-4154 | Test Jira: BT-4167 | Epic: BT-4148 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
ct_cutoff_threshold | 40 | Maximum CT value before classification becomes Negative | REQ-RULES-CTCUTOFF-001 |
use_sample_type | System setting | Enables specimen-type-aware reporting selection | REQ-RULES-CTCUTOFF-002 |
UI Notes (Illustrative)
No UI specifications identified in source material. This rule operates at the analytics/data layer with no direct UI components.
Implementation (Illustrative)
| Component | Location | Purpose |
|---|---|---|
| WfinalclsRule | Analyzer/Rules/WfinalclsRule.php | Core rule implementation - CT cutoff evaluation, specimen-type reporting, NULL handling |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-CTCUTOFF-001 | Set Classification When CT Exceeds Cutoff | Test | WfinalclsRule.php | [Pending] | Draft |
| REQ-RULES-CTCUTOFF-002 | Select Reporting Based on Specimen Type | Test | WfinalclsRule.php | BT-4283 | Draft |
| REQ-RULES-CTCUTOFF-003 | Treat NULL CT as Boundary Exceeded | Test | WfinalclsRule.php | [Pending] | Draft |
| REQ-RULES-CTCUTOFF-004 | Preserve Classification When Quantity NULL | Test | WfinalclsRule.php | [Pending] | Draft |
| REQ-RULES-CTCUTOFF-005 | Report CUTOFF_LIMITS_MISSED Error | Test | WfinalclsRule.php | BT-4167 | Draft |
Notes
- Customer change request origin: CT values evaluated as >40 by thermocycler software should be considered negative
- Future enhancement planned: GUI-configurable cutoff value
- Part of Phase 2A: Verify Rules have needed well/config info to run
- Related rules that may need updates to avoid conflicts: RQUAL, RQUANT, RQUANTASQUAL
NULL Value Handling Rationale
The asymmetric treatment of NULL values is intentional:
| NULL Field | Interpretation | Action | Rationale |
|---|---|---|---|
| CT | Boundary exceeded | Set Negative | Missing CT data indicates measurement failure; conservative approach treats as negative |
| Quantity | Boundary NOT passed | Do not modify | Missing quantity should not trigger classification change; preserve existing classification |
Specimen-Type Fallback Logic
When specimen-type-aware processing is disabled, the system falls back to using the most recently modified reporting configuration. This ensures:
- Backward compatibility with systems not using specimen types
- Deterministic behavior when specimen type is unavailable
- Preference for the most current configuration
Acceptance Tests
Test: REQ-RULES-CTCUTOFF-001
Test: CT exceeds cutoff sets Negative
Given: An observation with CT value = 45
And: Configured CT cutoff = 40
When: The observation is processed by WFINALCLS rule
Then: The system shall set machine_cls to Negative
And: The system shall set dx_ai.cls to Negative
Test: CT within cutoff preserves classification
Given: An observation with CT value = 35
And: Configured CT cutoff = 40
And: Current classification = Positive
When: The observation is processed by WFINALCLS rule
Then: The classification shall remain unchanged
Test: REQ-RULES-CTCUTOFF-002
Test: Specimen-specific cutoffs applied when enabled
Given: Reporting for Plasma with Mix=HEV, Target=HEV, CT Upper Boundary=30
And: Reporting for Serum with Mix=HEV, Target=HEV, CT Upper Boundary=10
And: Rule mappings WFINALCLS mapped to both Plasma and Serum specimen types
And: Runfile with Well A1 (Plasma, CT=25) and Well A2 (Serum, CT=25)
When: Use sample type is enabled
And: The runfile is imported
Then: A1 shall have Positive classification (25 < 30)
And: A2 shall have Negative classification (25 > 10)
Test: Last modified reporting used when specimen type disabled
Given: Same reporting and runfile configuration as above
And: Serum reporting has later "last modified" timestamp
When: Use sample type is disabled
And: The runfile is imported
Then: Both A1 and A2 shall have Negative classification (using Serum boundary=10)
Test: REQ-RULES-CTCUTOFF-003
Test: NULL CT sets Negative
Given: An observation with final CT value = NULL
When: The observation is executed through the WFINALCLS rule
Then: The observation classification shall be set to Negative
Test: REQ-RULES-CTCUTOFF-004
Test: NULL Quantity preserves classification
Given: An observation with Quantity value = NULL
And: Current classification = Positive
When: The observation is executed through the WFINALCLS rule
Then: The observation classification shall remain Positive (not modified)
Test: REQ-RULES-CTCUTOFF-005
Test: Missing target_id sets error
Given: A well with an observation where target_id = null
When: The WFINALCLS rule analyzes the observation
Then: The well shall have the CUTOFF_LIMITS_MISSED error set
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | CT Cutoff Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A, all distinct capabilities
- 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 - N/A, none identified
- 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 Required
All 5 requirements in the source represent distinct, independently testable system capabilities:
| Requirement | Capability | Disposition |
|---|---|---|
| REQ-RULES-CTCUTOFF-001 | Core CT cutoff evaluation | Preserved as-is |
| REQ-RULES-CTCUTOFF-002 | Specimen-based reporting selection | Preserved as-is |
| REQ-RULES-CTCUTOFF-003 | NULL CT handling | Preserved as-is |
| REQ-RULES-CTCUTOFF-004 | NULL Quantity handling | Preserved as-is |
| REQ-RULES-CTCUTOFF-005 | Error code for missing config | Preserved as-is |
Rationale: This is a RULES domain with analytics precision requirements. Each requirement addresses a distinct scenario with different triggering conditions and outcomes. Consolidation would reduce testability and clarity.
Reversibility: Source file: output/srs/rules/rule-ct-cutoff-wfinalcls.md