ADJ Zika Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: ADJ_Zika rule for detecting potential cross-contamination between adjacent wells in Zika PCR assays Domain: RULES-ADJZIKA Precedence: Standard rule order
Statement
The system shall evaluate wells for potential adjacent cross-contamination in Zika PCR assay results by comparing observation quantities against configured thresholds and apply the ZIKA_ADJ_CT error code when contamination conditions are met.
The rule identifies potentially contaminated low-quantity samples adjacent to high-quantity samples. To reduce false positives, the system suppresses errors for repeat accessions that have prior low-positive test results. When multiple wells share the same accession on a single run, the system uses the well with the highest well number (latest position) as the historical reference.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-ADJZIKA-001 | Applies contamination thresholds to adjacent wells | HIGH | Draft |
| REQ-RULES-ADJZIKA-002 | Suppresses errors for repeat accessions with low-positive history | HIGH | Draft |
| REQ-RULES-ADJZIKA-003 | Uses latest well number for same-accession history determination | HIGH | Draft |
Key Integration Points: Run file import, Kit Configuration, Error code system, Historical accession tracking
Rule Summary
| Property | Value |
|---|---|
| Name | Adj_Zika |
| Error Codes | ZIKA_ADJ_CT, ZIKA_ADJ_LIMITS_MISSED |
| Triggers | When evaluating wells with Mix: Zika, Target: Zika |
| Output | Sets error code on well when contamination conditions met |
Rule Flowchart (Illustrative)
This diagram illustrates the core decision logic. Low-positive range is defined as quantity > 0 AND quantity <= POTENTIAL_CONTAMINATED threshold.
Definitions
| Term | Definition |
|---|---|
| Adjacent well | A well positioned immediately next to another well in the plate layout (horizontal adjacency) |
| POTENTIAL_CONTAMINATED threshold | Upper quantity bound for wells considered "at risk" of contamination |
| POTENTIAL_CONTAMINATING threshold | Lower quantity bound for wells considered potential "source" of contamination |
| Low-positive | A sample with quantity between 1 and POTENTIAL_CONTAMINATED threshold, indicating weak positive detection |
| Repeat accession | A sample that has been previously tested and has historical results in the system |
| Well number ordering | Alphanumeric sort order (A1 < A2 < ... < B1 < B2 < ...) |
Assumptions
- Rule mapping is configured linking Mix: Zika, Target: Zika to the ADJ_Zika rule
- Cross-contamination limits are configured with QUANT or CT mode, POTENTIAL_CONTAMINATED, and POTENTIAL_CONTAMINATING thresholds
- Wells being evaluated have valid quantity observations
- Historical accession data is accessible for repeat sample lookup
Requirements
Contamination Detection (REQ-RULES-ADJZIKA-001)
FR-ADJZIKA-001: Apply Adjacent Well Contamination Thresholds
The system shall evaluate wells for potential adjacent contamination by comparing observation quantities against configured thresholds and apply the ZIKA_ADJ_CT error code when contamination conditions are met.
Acceptance Criteria
Threshold Evaluation:
- Apply ZIKA_ADJ_CT error when a well's quantity is below POTENTIAL_CONTAMINATED threshold AND an adjacent well's quantity exceeds POTENTIAL_CONTAMINATING threshold
- Both wells shall match the configured Mix and Target values for the rule to apply
- Determine evaluation mode by the QUANT OR CT configuration parameter
Error Code Assignment:
- Use the rule identifier
Adj_Zika - Apply error code
ZIKA_ADJ_CTfor contamination detected - Apply error code
ZIKA_ADJ_LIMITS_MISSEDfor limits validation failure
Error Handling
- Neither threshold met: no error applied to well
- Contaminating threshold not exceeded: no error applied
- Contaminated threshold not met: no error applied
Trace: Source: 3.0.0-Adj Zika rule (Row 1) | Jira: BT-4313 | Epic: BT-4303 | Tests: See scenarios
Historical Suppression (REQ-RULES-ADJZIKA-002)
FR-ADJZIKA-002: Suppress Errors for Repeat Accessions with Low-Positive History
The system shall suppress ADJ_Zika errors for wells when the accession has a previous result with quantity within the low-positive range (between 1 and POTENTIAL_CONTAMINATED threshold).
Acceptance Criteria
Historical Lookup:
- Track historical test results by accession number
- Perform historical lookup using accession number across all previous runs
Suppression Logic:
- Suppress ZIKA_ADJ_CT error when the accession has a previous result with quantity > 0 AND quantity <= POTENTIAL_CONTAMINATED threshold
- Do not suppress when historical quantity is above POTENTIAL_CONTAMINATED threshold
Low-Positive Range Definition:
- Low-positive range: quantity > 0 AND quantity <= POTENTIAL_CONTAMINATED threshold
- Suppress errors when historical quantity is within this range
Error Handling
- No historical accession found: apply standard threshold evaluation
- Historical quantity above threshold: apply error if other conditions met
Trace: Source: 3.0.0-Adj Zika rule (Row 2) | Jira: BT-4313 | Epic: BT-4303 | Tests: See scenarios | Related: REQ-RULES-ADJZIKA-001, REQ-RULES-ADJZIKA-003
History Determination (REQ-RULES-ADJZIKA-003)
FR-ADJZIKA-003: Use Latest Well Number for Same-Accession History
The system shall use the well with the highest well number (latest position) as the historical reference when multiple wells on a single run file share the same accession number.
Acceptance Criteria
Well Ordering:
- Determine well ordering using alphanumeric sort (A1 < A2 < A3 < ... < B1 < B2 < ...)
- Use the highest well position in the run file as the historical reference for that accession
Scope:
- This rule applies to history determination, not to within-run adjacent well evaluation
Error Handling
- Single well for accession: use that well as reference
- Multiple wells same accession: always use highest well number
Trace: Source: 3.0.0-Adj Zika rule (Row 3) | Jira: BT-4313 | Epic: BT-4303 | Tests: See scenarios | Related: REQ-RULES-ADJZIKA-002
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
QUANT_OR_CT | Quant | Determines evaluation mode (Quant or CT) for threshold comparison | REQ-RULES-ADJZIKA-001 |
POTENTIAL_CONTAMINATED | (varies) | Upper bound for wells considered "at risk" of contamination | REQ-RULES-ADJZIKA-001, REQ-RULES-ADJZIKA-002, REQ-RULES-ADJZIKA-003 |
POTENTIAL_CONTAMINATING | (varies) | Lower bound for wells considered potential "source" of contamination | REQ-RULES-ADJZIKA-001, REQ-RULES-ADJZIKA-002, REQ-RULES-ADJZIKA-003 |
Mix | Zika | Mix value for rule mapping | REQ-RULES-ADJZIKA-001 |
Target | Zika | Target value for rule mapping | REQ-RULES-ADJZIKA-001 |
UI Notes (Illustrative)
This is a backend analytics rule with no dedicated UI screens. All interactions occur through existing system configuration interfaces.
Rule Mapping Configuration:
- Mix: Zika
- Target: Zika
- Rule: ADJ_Zika
Cross Contamination Limits Configuration:
- MIX field
- Target field
- QUANT OR CT selector
- POTENTIAL CONTAMINATED numeric input
- POTENTIAL CONTAMINATING numeric input
Error Code Display:
- ZIKA_ADJ_CT and ZIKA_ADJ_LIMITS_MISSED codes displayed in standard results/observation interface
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/AdjZikaRule.php |
| Base Class | Analyzer/Rules/BaseAdjRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-ADJZIKA-001 | Apply Adjacent Well Contamination Thresholds | Test | AdjZikaRule, BaseAdjRule | [Pending] | Draft |
| REQ-RULES-ADJZIKA-002 | Suppress Errors for Repeat Accessions with Low-Positive History | Test | AdjZikaRule | [Pending] | Draft |
| REQ-RULES-ADJZIKA-003 | Use Latest Well Number for Same-Accession History | Test | AdjZikaRule | [Pending] | Draft |
Notes
- This rule is a backend analytics rule that operates during run file processing
- The purpose is to detect potential cross-contamination artifacts in Zika PCR testing where high-quantity wells may contaminate adjacent low-quantity wells
- Historical suppression prevents diagnostic noise from repeat testing of confirmed low-positive samples
- Rule applies to horizontally adjacent wells (A1-A2, B1-B2, etc.)
Acceptance Tests
Test: REQ-RULES-ADJZIKA-001
Test: Error triggered when both thresholds exceeded
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Well A1 (Zika/Zika) has quantity 100
And: Well A2 (Zika/Zika) has quantity 600
When: ADJ_Zika rule is evaluated
Then: A1 shall receive ZIKA_ADJ_CT error
Test: No error when contaminating threshold not exceeded
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Well A1 (Zika/Zika) has quantity 100
And: Well A2 (Zika/Zika) has quantity 300
When: ADJ_Zika rule is evaluated
Then: A1 shall NOT receive ZIKA_ADJ_CT error
Test: No error when contaminated threshold not met
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Well A1 (Zika/Zika) has quantity 300
And: Well A2 (Zika/Zika) has quantity 600
When: ADJ_Zika rule is evaluated
Then: A1 shall NOT receive ZIKA_ADJ_CT error
Test: No error when neither threshold met
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Well A1 (Zika/Zika) has quantity 300
And: Well A2 (Zika/Zika) has quantity 300
When: ADJ_Zika rule is evaluated
Then: A1 shall NOT receive ZIKA_ADJ_CT error
Test: REQ-RULES-ADJZIKA-002
Test: Suppressed when accession had prior low-positive
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Historical Well 1: A1, Accession 123, quantity 100 (below threshold)
And: Current Well A1 (Accession 123, qty 100) adjacent to A2 (Accession 456, qty 600)
When: ADJ_Zika rule is evaluated
Then: A1 shall NOT receive ZIKA_ADJ_CT error
Because: Accession 123 previously tested at 100 (within 1-200 range)
Test: Error triggered when accession had prior result above threshold
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=200, POTENTIAL_CONTAMINATING=400
And: Historical Well: B1, Accession 999, quantity 300 (above threshold)
And: Current Well A1 (Accession 999, qty 100) adjacent to A2 (Accession 456, qty 600)
When: ADJ_Zika rule is evaluated
Then: A1 shall receive ZIKA_ADJ_CT error
Because: Accession 999 previously tested at 300 (above 200 threshold)
Test: REQ-RULES-ADJZIKA-003
Test: Latest well with low quantity clears history
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=25, POTENTIAL_CONTAMINATING=100000
And: Run 1: A1 (Accession 12345, qty 111K), A2 (Accession 12345, qty 24 with ADJ_ZIKA_ERROR)
When: Run 2 imported: A1 (Accession 12345, qty 24), A2 (Accession 12345, qty 111K)
Then: A1 of Run 2 shall NOT receive ADJ_Zika error
Because: A2 in Run 1 (latest well) had qty 24, which is < POTENTIAL_CONTAMINATED (25)
Test: Latest well with high quantity persists in history
Given: Rule mapping Mix: Zika, Target: Zika maps to ADJ_Zika rule
And: Cross-contamination limits: QUANT mode, POTENTIAL_CONTAMINATED=25, POTENTIAL_CONTAMINATING=100000
And: Run 1: A1 (Accession 12345, qty 24), A2 (Accession 12345, qty 111K)
When: Run 2 imported: A1 (Accession 12345, qty 24), A2 (Accession 12345, qty 111K)
Then: A1 of Run 2 shall receive ADJ_Zika error
Because: A2 in Run 1 (latest well) had qty 111K, which is > POTENTIAL_CONTAMINATING
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Adjacent Well Rules |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- 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
- 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
The three requirements in this domain represent distinct, independently testable system capabilities:
| Requirement | Capability | Disposition |
|---|---|---|
| REQ-RULES-ADJZIKA-001 | Threshold-based contamination detection | Preserved as-is |
| REQ-RULES-ADJZIKA-002 | Historical suppression for repeat accessions | Preserved as-is |
| REQ-RULES-ADJZIKA-003 | Latest well number for history determination | Preserved as-is |
Rationale: These requirements are not variants of a single capability but distinct analytical behaviors that must be independently verified. Per RULES domain guidance, conservative consolidation is applied to preserve analytical precision.
Reversibility: Source: output/pilot/rules/rule-adj-zika/rule-adj-zika-restructured.md