WDCT Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: WDCT rule for detecting CT discrepancies between pcr.ai and machine CT values Domain: RULES-WDCT Precedence: After fluorescence threshold check, before Combined Outcomes
Statement
The system shall detect CT (Cycle Threshold) discrepancies between pcr.ai-calculated values and machine-reported CT values for Patient wells, flagging wells where the absolute difference exceeds the configured ct_discrepancy_delta threshold.
The rule applies only to Patient wells with non-negative classification. Three configuration-based modifiers control rule behavior: the ct_discrepancy_delta threshold determines the triggering difference; when the final CT meets or exceeds a configured max threshold, the error is suppressed; when the maximum fluorescence reading falls below a configured minimum threshold, the rule is skipped entirely. Control wells are delegated to the separate WDCTC rule.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-WDCT-001 | Detects CT discrepancies for Patient wells where absolute difference exceeds configured ct_discrepancy_delta | HIGH | Draft |
| REQ-RULES-WDCT-002 | Suppresses CT discrepancy errors when final CT >= max_ct_for_ct_discrepancy | HIGH | Draft |
| REQ-RULES-WDCT-003 | Skips rule entirely when max fluorescence < minimum_fluorescence_to_positive | HIGH | Draft |
Key Integration Points: PCR.ai CT calculation, Machine CT import, Well classification, Kit Configuration (target.ct_discrepancy_delta)
Rule Summary
| Property | Value |
|---|---|
| Name | WDCT |
| Triggers | Patient well CT comparison |
| Output | CTDISC_WELL error code |
| Threshold | > target.ct_discrepancy_delta (configurable per target) |
Rule Flowchart (Illustrative)
This diagram illustrates the rule evaluation order: fluorescence check (REQ-003) first, then classification, then max CT threshold (REQ-002), then ct_discrepancy_delta check (REQ-001). The rule only triggers when ct_discrepancy_delta is configured for the target.
Definitions
| Term | Definition |
|---|---|
| CT (Cycle Threshold) | The PCR cycle number at which fluorescence signal crosses a defined threshold |
| pcr.ai CT | The CT value calculated by the pcr.ai algorithm |
| Machine CT | The CT value reported by the thermocycler instrument |
| CT Discrepancy | A condition where the absolute difference between pcr.ai CT and machine CT exceeds the configured ct_discrepancy_delta threshold |
| Final CT | The authoritative CT value used for downstream analysis |
| Patient Well | A well containing patient sample (as opposed to control wells) |
| CTDISC_WELL | Error code indicating a CT discrepancy was detected on a well |
Assumptions
- The rule applies only to Patient wells; control wells are evaluated by separate rules (e.g., WDCTC)
- Both pcr.ai CT and machine CT values are available for comparison when the rule executes
- Well classification (positive/negative) has been determined prior to rule execution
- Target configuration parameters are accessible during rule evaluation
Requirements
CT Discrepancy Detection (REQ-RULES-WDCT-001)
FR-WDCT-001: Detect CT Discrepancies for Patient Wells
The system shall detect CT discrepancies between pcr.ai and machine CT values for Patient wells and flag wells where the absolute difference exceeds the configured ct_discrepancy_delta threshold.
Acceptance Criteria
Classification Handling:
- Skip discrepancy detection for wells with negative classification (end without error)
- Compare pcr.ai CT value against machine CT value for each Patient well with non-negative classification
Configuration Check:
- Skip discrepancy detection when target.ct_discrepancy_delta is null (rule is disabled for this target)
- The ct_discrepancy_delta threshold is configured per target via Mix and Targets import or UI (see REQ-KITCFG-001)
Discrepancy Detection:
- Flag a CT discrepancy error (CTDISC_WELL) when the absolute difference between pcr.ai CT and machine CT exceeds target.ct_discrepancy_delta
- Calculate discrepancy as: abs(machineCt - dxaiCt) > ct_discrepancy_delta
Scope and Delegation:
- Apply this rule only to Patient wells (not control wells)
- Delegate control well CT discrepancy detection to the WDCTC rule
Execution Order:
- Execute the rule in the following order: check fluorescence threshold (003), then classification, then max CT threshold (002), then ct_discrepancy_delta check
- Respect threshold conditions from REQ-RULES-WDCT-002 and REQ-RULES-WDCT-003 that may suppress or skip the discrepancy check
Error Handling
- CT discrepancy detected (difference > ct_discrepancy_delta): Flag the well with error code CTDISC_WELL
- Negative classification: Complete rule evaluation without error
- ct_discrepancy_delta is null: Complete rule evaluation without error (rule disabled for target)
Trace: Source: 3.0.0-WDCT rule (Lines 21-43) | Jira: BT-674 | Tests: See scenarios | Related: REQ-RULES-WDCT-002, REQ-RULES-WDCT-003
Threshold-Based Suppression (REQ-RULES-WDCT-002)
FR-WDCT-002: Suppress CT Discrepancy Errors Based on Max CT Threshold
The system shall suppress CT discrepancy errors when the observation's final CT value meets or exceeds the configured max CT for CT discrepancy threshold.
Acceptance Criteria
Null Threshold Behavior:
- When target.max_ct_for_ct_discrepancy is null, apply standard discrepancy detection without CT-based suppression
- Do not apply CT-based suppression when max_ct_for_ct_discrepancy is null
Suppression Logic:
- Suppress CT discrepancy errors when final_ct >= max_ct_for_ct_discrepancy
- Use greater-than-or-equal (>=) comparison for the suppression threshold
Suppression Examples:
| max_ct_for_ct_discrepancy | final_ct | Result |
|---|---|---|
| null | any | Not suppressed (standard detection applies) |
| 35 | 36 | Suppressed (36 > 35) |
| 36 | 36 | Suppressed (36 >= 36) |
| 37 | 36 | Not suppressed (36 < 37) |
Trace: Source: 3.0.0-WDCT: Consider 'Max CT for CT Discrepancy' (Lines 45-127) | Jira: BT-5308, BT-5307 | Tests: See scenarios | Related: REQ-RULES-WDCT-001
Fluorescence-Based Skip (REQ-RULES-WDCT-003)
FR-WDCT-003: Skip Rule Based on Minimum Fluorescence Threshold
The system shall skip the WDCT rule entirely when the maximum fluorescence reading in the observation is below the configured minimum fluorescence to positive threshold.
Acceptance Criteria
Fluorescence Calculation:
- Use max(observation.readings) - the highest reading value in the observation - for this comparison
Skip Behavior:
- Skip the rule entirely (not just suppress the error) when max reading is below the threshold
- Skip the rule to prevent false discrepancy errors on curves with insufficient fluorescence signal
- Evaluate the fluorescence check as a pre-condition before the main discrepancy evaluation
Threshold Examples:
| minimum_fluorescence_to_positive | max(readings) | Result |
|---|---|---|
| 100 | 99 | Skip rule entirely |
| 100 | 100 | Evaluate rule normally |
Trace: Source: 3.0.0-WDCT: Consider Minimum Fluorescence in WD Rules (Lines 129-188) | Jira: BT-5368, BT-5367 | Tests: See scenarios | Related: REQ-RULES-WDCT-001
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
target.ct_discrepancy_delta | null | CT discrepancy threshold per target. When null, CT discrepancy checking is disabled for this target. When set, the rule flags wells where abs(machineCt - dxaiCt) exceeds this value. Configured via Mix and Targets import or UI (REQ-KITCFG-001). | REQ-RULES-WDCT-001 |
target.max_ct_for_ct_discrepancy | null | Maximum CT value above which CT discrepancy checks are suppressed. When null, no CT-based suppression is applied. | REQ-RULES-WDCT-002 |
target.minimum_fl_to_be_pos | - | Minimum fluorescence threshold required for rule evaluation. Wells below this threshold skip the rule entirely. | REQ-RULES-WDCT-003 |
Notes
- Rule execution flow: fluorescence check (003) -> classification -> max CT threshold (002) -> ct_discrepancy_delta check (001)
- This rule may be suppressed by CT threshold (REQ-RULES-WDCT-002) or fluorescence threshold (REQ-RULES-WDCT-003) conditions
- The ct_discrepancy_delta threshold is configurable per target; when null, the rule is disabled for that target
- Related rules share the minimum fluorescence configuration (other WD rules)
- Combined Outcomes rules may depend on CT discrepancy status from this rule
- The WDCTC rule (for control wells) uses the same ct_discrepancy_delta configuration
UI Detail (Illustrative)
This rule operates at the analytics engine level without direct UI components. The rule produces error codes that may be displayed in well detail views or run summary screens. The presentation of CTDISC_WELL errors is determined by the UI layer and is not specified in this domain.
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/WdctRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-WDCT-001 | Detect CT Discrepancies for Patient Wells | Test | WdctRule | See scenarios | Draft |
| REQ-RULES-WDCT-002 | Suppress CT Discrepancy Errors Based on Max CT Threshold | Test | WdctRule | See scenarios | Draft |
| REQ-RULES-WDCT-003 | Skip Rule Based on Minimum Fluorescence Threshold | Test | WdctRule | See scenarios | Draft |
Acceptance Tests
Test: REQ-RULES-WDCT-001
Test: Negative classification bypasses rule
Given: A Patient well with negative classification
And: pcr.ai CT differs from machine CT by more than 2
When: The WDCT rule evaluates the well
Then: The system shall complete without flagging a CT discrepancy error
Test: CT discrepancy detected
Given: A Patient well with positive classification
And: target.ct_discrepancy_delta is 2
And: pcr.ai CT is 25.0
And: machine CT is 28.5
When: The WDCT rule evaluates the well
Then: The system shall flag the well with CTDISC_WELL error
Because: The absolute difference (3.5) exceeds ct_discrepancy_delta (2)
Test: CT values within tolerance
Given: A Patient well with positive classification
And: target.ct_discrepancy_delta is 2
And: pcr.ai CT is 25.0
And: machine CT is 26.5
When: The WDCT rule evaluates the well
Then: The system shall complete without flagging a CT discrepancy error
Because: The absolute difference (1.5) does not exceed ct_discrepancy_delta (2)
Test: ct_discrepancy_delta is null - rule disabled
Given: A Patient well with positive classification
And: target.ct_discrepancy_delta is null
And: pcr.ai CT differs from machine CT by more than 10
When: The WDCT rule evaluates the well
Then: The system shall complete without flagging a CT discrepancy error
Because: ct_discrepancy_delta is null, so the rule is disabled for this target
Test: REQ-RULES-WDCT-002
Test: Null threshold allows normal detection
Given: A Patient well A1 with observation O1
And: target.max_ct_for_ct_discrepancy is null
And: observation.final_ct is 36
And: pcr.ai CT differs from machine CT by more than 2
When: The WDCT rule evaluates the well
Then: The system shall flag the well with CT discrepancy error
Because: Threshold not applied when null
Test: Final CT exceeds threshold - suppressed
Given: A Patient well A1 with observation O1
And: target.max_ct_for_ct_discrepancy is 35
And: observation.final_ct is 36
And: pcr.ai CT differs from machine CT by more than 2
When: The WDCT rule evaluates the well
Then: The system shall NOT flag a CT discrepancy error
Because: 36 > 35, error is suppressed
Test: Final CT equals threshold - suppressed
Given: A Patient well A1 with observation O1
And: target.max_ct_for_ct_discrepancy is 36
And: observation.final_ct is 36
And: pcr.ai CT differs from machine CT by more than 2
When: The WDCT rule evaluates the well
Then: The system shall NOT flag a CT discrepancy error
Because: 36 >= 36, error is suppressed
Test: Final CT below threshold - not suppressed
Given: A Patient well A1 with observation O1
And: target.max_ct_for_ct_discrepancy is 37
And: observation.final_ct is 36
And: pcr.ai CT differs from machine CT by more than 2
When: The WDCT rule evaluates the well
Then: The system shall flag the well with CT discrepancy error
Because: 36 < 37, error is not suppressed
Test: REQ-RULES-WDCT-003
Test: Max reading below threshold - rule skipped
Given: A Patient well A1 with observation O1 on target T1
And: target.minimum_fluorescence_to_positive is 100
And: max(observation.readings) is 99
When: The WDCT rule evaluates the well
Then: The system shall skip the rule entirely
Because: 99 < 100, insufficient fluorescence
Test: Max reading meets threshold - rule evaluates
Given: A Patient well A1 with observation O1 on target T1
And: target.minimum_fluorescence_to_positive is 100
And: max(observation.readings) is 100
When: The WDCT rule evaluates the well
Then: The system shall proceed with normal rule evaluation
Because: 100 >= 100, fluorescence threshold met
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | WDCT Rule Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated appropriately (conservative 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 rule evaluation scenarios
- Open questions documented with owners assigned
- 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
- All Given/When/Then scenarios preserved as detailed ACs (RULES domain requirement)
Reviewer Notes
No Consolidation Required
The three requirements in this domain represent distinct, non-overlapping behaviors:
| Requirement | Purpose | Disposition |
|---|---|---|
| REQ-RULES-WDCT-001 | Core discrepancy detection logic | Retained as primary requirement |
| REQ-RULES-WDCT-002 | Max CT threshold suppression behavior | Retained as sub-rule (distinct configuration-based behavior) |
| REQ-RULES-WDCT-003 | Minimum fluorescence skip behavior | Retained as sub-rule (distinct pre-condition check) |
Rationale: These three requirements represent a core capability (001) with two independent modifier behaviors (002, 003) that cannot be meaningfully consolidated. Each addresses a different configuration parameter and applies at a different point in the rule execution flow. Consolidation would obscure the distinct test scenarios documented in the acceptance criteria.
Reversibility: Source requirements preserved 1:1.
- Source:
output/srs/rules/rule-wdct.md