Qualitative Reporting Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: RQUAL rule for determining qualitative reporting outcomes by comparing CT values against cutoff thresholds Domain: RULES-RQUAL Precedence: After COMBINED_OUTCOME
Statement
The system shall apply the RQUAL rule to determine qualitative reporting outcomes (Detected/Not Detected) based on comparison of sample CT (cycle threshold) values against configured cutoff boundaries.
The rule supports specimen-type-specific reporting configurations when sample type mode is enabled, falling back to the most recently modified configuration when disabled. This enables different cutoff thresholds for different specimen types (e.g., Plasma vs. Serum) within the same test assay.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-RQUAL-001 | Determines qualitative outcome (Detected/Not Detected) by CT vs cutoff comparison | HIGH | Draft |
| REQ-RULES-RQUAL-002 | Selects reporting configuration based on specimen type or last-modified fallback | HIGH | Draft |
Key Integration Points: Reporting Configuration, Rule Engine, Sample Data, System Settings
Rule Summary
| Property | Value |
|---|---|
| Name | RQUAL |
| Triggers | Samples configured for qualitative (non-quantified) reporting |
| Output | Sets result status (Detected/Not Detected/Error) on sample |
Rule Flowchart (Illustrative)
This diagram illustrates the RQUAL rule execution logic. The relationship between CT and outcome may appear counter-intuitive: lower CT values (< CutOff) indicate Error/Not Detected, while higher CT values (>= CutOff) indicate Detected.
Definitions
| Term | Definition |
|---|---|
| CT (Cycle Threshold) | The PCR cycle number at which fluorescence signal crosses a threshold |
| CutOff / Upper Boundary | The configured CT threshold used to determine qualitative outcome |
| Qualitative Reporting | Reporting method that produces categorical outcomes (Detected/Not Detected) rather than quantitative values |
| RQUAL | Rule identifier for Reporting Qualitative samples |
| Specimen Type | Classification of sample material (e.g., Plasma, Serum) |
Assumptions
- The RQUAL rule is applied only to samples configured for qualitative (non-quantified) reporting
- CT values are available from instrument data before rule execution
- Reporting configurations with valid Upper Boundary values exist before rule execution
- When using sample type mode, rule mappings associate specimen types with the RQUAL rule
Requirements
Qualitative Threshold Evaluation (REQ-RULES-RQUAL-001)
FR-RQUAL-001: Qualitative Reporting Outcome Determination
The system shall apply the RQUAL rule to determine qualitative reporting outcomes based on comparison of the sample CT value against the configured cutoff boundary.
Acceptance Criteria
Outcome Determination:
- When CT < CutOff, the system shall flag the result as Error (Not Detected)
- When CT >= CutOff, the system shall report the result as valid (Detected)
Scope:
- The rule shall be applied only to samples configured for qualitative (non-quantified) reporting
- The cutoff boundary shall be retrieved from the applicable reporting configuration
Trace: Source: 3.0.0-Reporting Qual (Row 1) | Jira: BT-674 (Epic - Rules) | Tests: [Pending]
Specimen-Specific Configuration Selection (REQ-RULES-RQUAL-002)
FR-RQUAL-002: Specimen-Specific Reporting Configuration Selection
The system shall select the appropriate reporting configuration based on specimen type when sample type mode is enabled, and shall fall back to the most recently modified configuration when sample type mode is disabled.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Sample specimen type | Sample record |
| Input | Sample CT value | Instrument data |
| Input | System setting (use_sample_type) | System configuration |
| Input | Reporting configurations | Kit configuration |
| Output | Selected reporting configuration | Rule context |
| Output | Qualitative outcome | Sample record |
Acceptance Criteria
Sample Type Mode Enabled:
- When "use sample type" is enabled, the system shall match the sample's specimen type to the corresponding reporting configuration
- Specimen type matching shall use Mix, Target, and Specimen type fields to identify the correct reporting configuration
- Each specimen type may have different Upper Boundary (cutoff) values configured
- The system shall support different cutoff thresholds for Plasma and Serum specimens with the same Mix/Target combination
Sample Type Mode Disabled:
- When "use sample type" is disabled, the system shall use the reporting configuration with the most recent "last modified" timestamp
- The system shall use the "last modified" timestamp to ensure deterministic configuration selection
Configuration Data Sources:
- The system shall use Reportings (with specimen type and Upper Boundary), Rule mappings (specimen to rule), and sample type system setting for configuration selection
- The rule outcome (Detected/Not Detected) shall be determined by comparing the sample CT against the selected reporting's Upper Boundary
Error Handling
- Missing reporting configuration: Fall through to subsequent rules or raise configuration error
- No specimen type match: Use fallback selection logic
Assumptions
- Reporting configurations exist for each specimen type that will be processed when sample type mode is enabled
- Rule mappings are configured to associate specimen types with the RQUAL rule
Trace: Source: 3.0.0-RQUAL Rule - Should use unique reporting based on specimen (Row 1) | Jira: BT-4205, BT-4204 (Epic) | Tests: TC-RQUAL-002-01, TC-RQUAL-002-02 | Related: REQ-RULES-RQUAL-001
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
use_sample_type | [Configurable] | When enabled, specimen-type-specific reporting configurations are used; when disabled, most recently modified configuration is used | REQ-RULES-RQUAL-002 |
UI Notes (Illustrative)
REQ-RULES-RQUAL-001 Flow Diagram
- Flow diagram available at:
media/image165.png - Illustrates the RQUAL rule execution logic
Flow Description:
- Start - Rule begins execution on sample well
- Retrieve CT value for the well/target
- Retrieve CutOff threshold from reporting configuration
- Decision: Is CT < CutOff?
- Yes: Set Error status (qualitative fail / Not Detected)
- No: Continue processing (qualitative pass / Detected)
- Determine outcome based on specimen-specific reporting
REQ-RULES-RQUAL-002 Configuration Example
Reportings Configuration Table:
| Configuration | Mix | Target | Specimen Type | Quant or CT | Group | Upper Boundary | Last Modified |
|---|---|---|---|---|---|---|---|
| Plasma Config | HEV | HEV | Plasma | Ct | 1 LoD | 30 | 2023-11-08 00:00:00 |
| Serum Config | HEV | HEV | Serum | Ct | 1 LoD | 10 | 2023-11-08 00:01:00 |
Rule Mappings Table:
| Mix | Target | Specimen Type | Rule |
|---|---|---|---|
| HEV | HEV | Plasma | RQUAL |
| HEV | HEV | Serum | RQUAL |
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/RqualRule.php |
| Error Setter | Analyzer/Rules/Concerns/SetErrorToWell.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-RQUAL-001 | Qualitative Reporting Outcome Determination | Test | RqualRule.handle() | [Pending] | Draft |
| REQ-RULES-RQUAL-002 | Specimen-Specific Reporting Configuration Selection | Test | RqualRule.handle(), ConfigurationRepository.getFirstGroupReportingForObservation() | TC-RQUAL-002-01, TC-RQUAL-002-02 | Draft |
Notes
- The RQUAL rule is used for samples that are not quantified - outcomes are categorical (Detected/Not Detected) rather than numeric
- The relationship between CT and outcome may appear counter-intuitive: lower CT values (< CutOff) indicate Error/Not Detected, while higher CT values (>= CutOff) indicate Detected
- This rule is part of the broader Rules engine governed by Epic BT-674
Acceptance Tests
Test: REQ-RULES-RQUAL-002
Test TC-RQUAL-002-01: Sample type enabled - Specimen-specific reporting applied
Given: Reportings configured as follows:
- Plasma: Mix=HEV, Target=HEV, Specimen=Plasma, Quant/CT=Ct, Group=1 LoD, Upper Boundary=30, Last modified=2023-11-08 00:00:00
- Serum: Mix=HEV, Target=HEV, Specimen=Serum, Quant/CT=Ct, Group=1 LoD, Upper Boundary=10, Last modified=2023-11-08 00:01:00
And: Rule mappings configured as follows:
- Plasma: Mix=HEV, Target=HEV, Specimen=Plasma, Rule=RQUAL
- Serum: Mix=HEV, Target=HEV, Specimen=Serum, Rule=RQUAL
And: Runfile contains:
- Well A1: Mix=HEV, Target=HEV, Specimen=Plasma, Ct=25
- Well A2: Mix=HEV, Target=HEV, Specimen=Serum, Ct=25
When: Use sample type is enabled
And: Import the runfile
And: Open imported run and observe A1 and A2 wells
Then: A1 shall have Not Detected outcome
(Rationale: Ct 25 < Upper Boundary 30, so below cutoff = Not Detected)
And: A2 shall have Detected outcome
(Rationale: Ct 25 > Upper Boundary 10, so above cutoff = Detected)
Test TC-RQUAL-002-02: Sample type disabled - Last modified reporting used
Given: Same configuration as above (Serum has later "last modified" timestamp)
And: Same runfile as above
When: Use sample type is disabled
And: Import the runfile
And: Open imported run and observe A1 and A2 wells
Then: A1 shall have Detected outcome
(Rationale: Uses Serum reporting (last modified), Ct 25 > Upper Boundary 10 = Detected)
And: A2 shall have Detected outcome
(Rationale: Uses Serum reporting (last modified), Ct 25 > Upper Boundary 10 = Detected)
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Qualitative Reporting Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion - N/A, only 2 distinct requirements)
- 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 (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 Performed
The source contained 2 requirements representing distinct system capabilities:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-RULES-RQUAL-001 | 3.0.0-Reporting Qual (Row 1) | Preserved as REQ-RULES-RQUAL-001 |
| REQ-RULES-RQUAL-002 | 3.0.0-RQUAL Rule - Should use unique reporting based on specimen | Preserved as REQ-RULES-RQUAL-002 |
Rationale: These requirements represent distinct capabilities:
- RQUAL-001: Core rule algorithm (CT threshold comparison logic)
- RQUAL-002: Configuration selection behavior (specimen-type-specific vs fallback)
No consolidation was appropriate per RULES domain guidance requiring conservative handling and preservation of analytics precision.
Reversibility: Source preserved at:
- Source:
output/pilot/rules/rule-reporting-qual/rule-reporting-qual-restructured.md - SDD:
output/pilot/rules/rule-reporting-qual/sdd/rule-reporting-qual-design.md