ADJ Rule (Cross Contamination)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Detects and manages potential cross-contamination between adjacent wells on a thermocycler plate Domain: RULES-ADJ Precedence: Standalone detection rule
Statement
The system shall detect and flag potential cross-contamination between adjacent wells when a non-IC target has a high Ct value (potential contaminated) and an adjacent well contains the same target with a low Ct value (potential contaminating source).
The ADJ rule evaluates both Ct-based and Quant-based detection modes, persists error flags through export and re-analysis operations, supports user resolution through Manage Outcomes, and logs all configuration changes to the audit trail. When required configuration is missing, the rule flags wells with a limits-missed error.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-ADJ-001 | Detect cross-contamination between adjacent wells | HIGH | Draft |
| REQ-RULES-ADJ-002 | Persist errors after export and re-analysis | HIGH | Draft |
| REQ-RULES-ADJ-003 | Allow resolution through Manage Outcomes | MEDIUM | Draft |
| REQ-RULES-ADJ-004 | Capture configuration changes in audit log | MEDIUM | Draft |
| REQ-RULES-ADJ-005 | Support Quant-based detection mode | MEDIUM | Draft |
| REQ-RULES-ADJ-006 | Flag wells with missing configuration | HIGH | Draft |
Key Integration Points: Kit Configuration (thresholds), Manage Outcomes (resolution), Audit Log (changes)
Rule Summary
| Property | Value |
|---|---|
| Name | ADJ (Adjacent CT Rule) |
| Error Codes | ADJ_CT, ADJ_LIMITS_MISSED |
| Triggers | When analyzing positive wells for cross-contamination |
| Output | Sets error code on contaminated well |
Rule Flowchart (Illustrative)
This diagram illustrates the core detection logic. Resolution and audit logging follow separate paths not shown.
Definitions
| Term | Definition |
|---|---|
| Adjacent Well | Any well vertically, horizontally, or diagonally adjacent to a target well (up to 8 positions) |
| Ct (Cycle Threshold) | PCR cycle number at which fluorescence exceeds threshold, indicating presence of target |
| Potential Contaminated Ct | Ct threshold above which a well may be considered contaminated (high Ct = low quantity) |
| Potential Contaminating Ct | Ct threshold below which a well may be a contamination source (low Ct = high quantity) |
| IC (Internal Control) | Control target used to verify assay performance, excluded from cross-contamination analysis |
| Quant | Quantification value representing amount of target material in a well |
Assumptions
- Wells are arranged in a standard thermocycler plate grid format (rows and columns)
- ADJ rule configuration is completed before rule execution
- Only positive wells are evaluated for cross-contamination
- IC targets are excluded from cross-contamination analysis
Requirements
Cross-Contamination Detection (REQ-RULES-ADJ-001)
FR-ADJ-001: Detect Cross-Contamination Between Adjacent Wells
The system shall detect and flag potential cross-contamination between adjacent wells when a non-IC target in a well has a Ct value greater than the configured "potential contaminated Ct" threshold, and an adjacent well contains the same target with a Ct value less than the configured "potential contaminating Ct" threshold.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well observations (position, target, Ct, positive status) | PCR analysis |
| Input | Contamination thresholds (per mix/target) | Kit configuration |
| Output | ADJ_CT error code | Well record |
Acceptance Criteria
Detection Scope:
- The rule shall only evaluate positive wells for cross-contamination
- The rule shall only fire for non-IC (Internal Control) targets
- The rule shall compare the same target across the well and its adjacent wells
Adjacent Well Definition:
- An adjacent well shall be defined as any well vertically, horizontally, or diagonally adjacent to the target well (up to 8 adjacent positions)
- For well B2, adjacent wells shall be: A1, B1, C1 (row above), A2, C2 (same row), A3, B3, C3 (row below)
Threshold Configuration:
- Threshold values shall be configured within client configuration settings for each relevant mix/target combination
Error Assignment:
- When cross-contamination is detected, the system shall set an error with outcome message "Cross-contamination concern"
Error Handling
- Cross-contamination detected: Set ADJ_CT error with message "Cross-contamination concern"
Trace: Source: 3.0.0-ADJ - Cross contamination rule (Rows 1, 2, 3, 4) | Jira: BT-146, BT-690 | Tests: See scenarios
Error Persistence (REQ-RULES-ADJ-002)
FR-ADJ-002: Persist Cross-Contamination Errors After Export and Re-Analysis
The system shall maintain cross-contamination error flags on affected wells even when the adjacent well(s) that triggered the error are subsequently exported from the run file and the run file is re-analysed.
Acceptance Criteria
Persistence Rules:
- When a well is flagged with a cross-contamination error, the error shall remain after adjacent wells are exported
- Re-analysis of the run file shall not clear previously flagged cross-contamination errors
- The error status shall be preserved regardless of changes to adjacent well data
Trace: Source: 3.0.0-ADJ - Cross contamination rule (Row 5) | Jira: BT-146, BT-692 | Tests: See scenarios
Error Resolution (REQ-RULES-ADJ-003)
FR-ADJ-003: Allow Resolution of Cross-Contamination Errors
The system shall provide users the ability to resolve cross-contamination concern errors through the Manage Outcomes interface, with available resolution options determined by client configuration settings.
Acceptance Criteria
Resolution Interface:
- Cross-contamination concern errors shall be resolvable in the Manage Outcomes interface
- Resolution options shall be loaded from client configuration settings
- User shall be able to select an appropriate resolution for the flagged well
Trace: Source: 3.0.0-ADJ - Cross contamination rule (Row 6) | Jira: BT-146, BT-226, BT-691 | Related: DELTA configuration sheet (resolution codes) | Tests: [Pending]
Audit Logging (REQ-RULES-ADJ-004)
FR-ADJ-004: Capture Configuration Changes in Audit Log
The system shall record all configuration changes related to cross-contamination rule settings in the audit log, including changes to both the contaminating and contaminated Ct threshold values.
Acceptance Criteria
Audit Log Format:
- When "Set Contamination Ct" (potential contaminating) is configured, the system shall log: Area=Configuration, Change type=Contamination, Action=Set Contamination Ct, Change location=Target, Value before=[previous value or blank], Value after={potential_contaminating_ct}
- When "Set Contaminated Ct" (potential contaminated) is configured, the system shall log: Area=Configuration, Change type=Contamination, Action=Set Contaminated Ct, Change location=Target, Value before=[previous value or blank], Value after={potential_contaminated_ct}
- Both threshold settings shall be captured independently in the audit log
Trace: Source: 3.0.0-ADJ - Cross contamination rule (Row 7), Audit log section | Jira: BT-146, BT-694 | Tests: [Pending]
Quant-Based Detection (REQ-RULES-ADJ-005)
FR-ADJ-005: Support Quant-Based Cross-Contamination Detection
The system shall support configuring the ADJ rule to evaluate cross-contamination based on quantity (quant) values instead of Ct values.
Acceptance Criteria
Configuration:
- Configuration shall allow selection between Ct-based or Quant-based evaluation per mix/target
- Quant-based mode shall be supported for ZIKA rules
Evaluation Logic:
- Given Rules Mapping configured with ADJ rule for a mix/target, Cross Contamination Limits configured with QUANT OR CT: Quant, and POTENTIAL CONTAMINATED and POTENTIAL CONTAMINATING values set for quant
- When a run file is imported with wells containing quantity observations
- Then the rule shall evaluate quant values against configured thresholds
Example Scenario:
- Given: Mix HEV, Target HEV with QUANT OR CT: Quant, POTENTIAL CONTAMINATED: 200, POTENTIAL CONTAMINATING: 400
- When: Well A1 (HEV) has Quantity: 100, Well A2 (HEV) has Quantity: 600
- Then: Well A1 shall have the ADJ_CT error (A1 quantity 100 < 200, adjacent A2 quantity 600 > 400)
Trace: Source: 3.0.0-Adj Rule - work with quant conditions (Row 1) | Jira: BT-4303, BT-4313 | Tests: See scenarios
Missing Configuration Handling (REQ-RULES-ADJ-006)
FR-ADJ-006: Flag Wells with Missing Configuration
The system shall set an error on wells when the ADJ rule cannot execute due to missing required configuration values.
Acceptance Criteria
Missing Threshold Detection:
- Given: A well observation with potential_contaminated_ct: null; When: The ADJ rule analyzes the observation; Then: The well shall have ADJ_LIMITS_MISSED error
- Given: A well observation with potential_contaminating_ct: null; When: The ADJ rule analyzes the observation; Then: The well shall have ADJ_LIMITS_MISSED error
Error Code:
- Error code shall be: ADJ_LIMITS_MISSED
Error Handling
- potential_contaminated_ct is null: Set ADJ_LIMITS_MISSED error
- potential_contaminating_ct is null: Set ADJ_LIMITS_MISSED error
Trace: Source: 3.0.0-AdjRule - add ADJ_LIMITS_MISSED error (Row 1) | Jira: BT-4148, BT-4154, BT-4167 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
potential_contaminated_ct | per mix/target | Ct threshold above which a well may be considered contaminated | REQ-RULES-ADJ-001 |
potential_contaminating_ct | per mix/target | Ct threshold below which a well may be a contamination source | REQ-RULES-ADJ-001 |
quant_or_ct | Ct | Selection between Ct-based or Quant-based evaluation | REQ-RULES-ADJ-005 |
potential_contaminated_quant | per mix/target | Quant threshold for potentially contaminated well | REQ-RULES-ADJ-005 |
potential_contaminating_quant | per mix/target | Quant threshold for potentially contaminating well | REQ-RULES-ADJ-005 |
resolution_codes | per client | Available resolutions for cross-contamination errors (DELTA config sheet) | REQ-RULES-ADJ-003 |
UI Notes (Illustrative)
FR-ADJ-001 Visualizations
Adjacent Well Grid:
+----+----+----+
| A1 | B1 | C1 |
+----+----+----+
| A2 | B2 | C2 |
+----+----+----+
| A3 | B3 | C3 |
+----+----+----+
- Well B2 has 8 adjacent wells: A1, B1, C1, A2, C2, A3, B3, C3
- Process flow diagram available in SDD (image146.png)
- Test file layout available in SDD (image106.png)
FR-ADJ-003 Resolution Interface
- Error resolution performed via Manage Outcomes modal interface
- Resolution codes defined in DELTA configuration sheet
FR-ADJ-004 Audit Log Entry Format
| Field | Set Contamination Ct | Set Contaminated Ct |
|---|---|---|
| Area | Configuration | Configuration |
| Change type | Contamination | Contamination |
| Action | Set Contamination Ct | Set Contaminated Ct |
| Change location | Target | Target |
| Value before | blank | blank |
| Value after | {potential_contaminating_ct} | {potential_contaminated_ct} |
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/AdjRule.php |
| Base Class | Analyzer/Rules/BaseAdjRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-ADJ-001 | Detect Cross-Contamination Between Adjacent Wells | Test | AdjRule, BaseAdjRule | BT-690 | Draft |
| REQ-RULES-ADJ-002 | Persist Cross-Contamination Errors After Export and Re-Analysis | Test | AdjRule | BT-692 | Draft |
| REQ-RULES-ADJ-003 | Allow Resolution of Cross-Contamination Errors | Test | AdjRule | BT-691 | Draft |
| REQ-RULES-ADJ-004 | Capture Configuration Changes in Audit Log | Test | AdjRule | BT-694 | Draft |
| REQ-RULES-ADJ-005 | Support Quant-Based Cross-Contamination Detection | Test | AdjRule, BaseAdjRule | [Pending] | Draft |
| REQ-RULES-ADJ-006 | Flag Wells with Missing Configuration | Test | AdjRule, BaseAdjRule | BT-4167 | Draft |
Notes
- The ADJ rule is also known as "Adjacent CT rule"
- Error ADJ_CT indicates cross-contamination detected; ADJ_LIMITS_MISSED indicates missing configuration
- Cross-contamination errors persist for audit trail integrity
- Quant-based mode was added to support ZIKA assay rules (BT-4303)
Acceptance Tests
Test: REQ-RULES-ADJ-001
Test: Cross-contamination detection with Ct values
Given: A thermocycler plate with wells containing positive results
And: Well D2 has target NCOV1 with Ct value greater than potential_contaminated_ct threshold
And: Adjacent well C1 has target NCOV1 with Ct value less than potential_contaminating_ct threshold
When: The ADJ rule analyzes the plate
Then: Well D2 shall have ADJ_CT error with message "Cross-contamination concern"
Test: IC targets excluded
Given: A thermocycler plate with wells containing positive results
And: Well A1 has IC target with Ct value greater than potential_contaminated_ct threshold
And: Adjacent well A2 has IC target with Ct value less than potential_contaminating_ct threshold
When: The ADJ rule analyzes the plate
Then: Well A1 shall NOT have ADJ_CT error
Test: REQ-RULES-ADJ-002
Test: Error persistence after adjacent well export
Given: Well B2 has ADJ_CT error triggered by adjacent well B1
When: Well B1 is exported from the run file
And: The run file is re-analyzed
Then: Well B2 shall still have ADJ_CT error
Test: REQ-RULES-ADJ-005
Test: Quant-based cross-contamination detection
Given: Mix HEV, Target HEV with configuration QUANT OR CT: Quant
And: POTENTIAL CONTAMINATED: 200
And: POTENTIAL CONTAMINATING: 400
And: Well A1 has Mix HEV, Target HEV with Quantity: 100
And: Well A2 has Mix HEV, Target HEV with Quantity: 600
When: The ADJ rule analyzes the plate
Then: Well A1 shall have ADJ_CT error
Test: REQ-RULES-ADJ-006
Test: Missing contaminated Ct threshold
Given: A well observation with potential_contaminated_ct: null
When: The ADJ rule analyzes the observation
Then: The well shall have ADJ_LIMITS_MISSED error
Test: Missing contaminating Ct threshold
Given: A well observation with potential_contaminating_ct: null
When: The ADJ rule analyzes the observation
Then: The well shall have ADJ_LIMITS_MISSED error
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | ADJ Rule 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 - No open questions identified
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
No Consolidation Required
All 6 source requirements represent distinct, non-overlapping capabilities:
| Original ID | Capability | Disposition |
|---|---|---|
| REQ-RULES-ADJ-001 | Detection and flagging | Retained as-is |
| REQ-RULES-ADJ-002 | Error persistence | Retained as-is |
| REQ-RULES-ADJ-003 | Error resolution | Retained as-is |
| REQ-RULES-ADJ-004 | Audit logging | Retained as-is |
| REQ-RULES-ADJ-005 | Quant-based detection | Retained as-is |
| REQ-RULES-ADJ-006 | Missing config handling | Retained as-is |
Rationale: Per RULES domain guidance, conservative consolidation is required for analytics. These requirements address different aspects of the rule lifecycle (detection, persistence, resolution, audit, configuration) and merging would lose precision required for testing and traceability.
Reversibility: Source file: output/pilot/rules/rule-adj/rule-adj-restructured.md