Systemic Inhibition Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Detects systemic inhibition patterns when multiple associated wells show inhibition Domain: RULES-SYSINH Precedence: After well association grouping
Statement
The system shall detect systemic inhibition patterns by evaluating whether multiple associated wells show inhibition, indicating a systematic processing issue rather than isolated well-specific inhibition.
When more than 2 wells in an associated group (same mix, extraction instrument, extraction date, and batch) have inhibited LIMS outcomes, the system assigns SYSTEMIC_INHIBITON_DETECTED error to positive patient wells. Wells with at least one positive observation receive INHN instead. Control wells and detected-type wells (DETECTED_LOQ, DETECTED_QUANT, DETECTED_HIQ) are excluded from both the inhibition count and error assignment.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-SYSINH-001 | Detect systemic inhibition across associated wells and assign errors | HIGH | Draft |
| REQ-RULES-SYSINH-002 | Exclude control wells from evaluation and error assignment | HIGH | Draft |
| REQ-RULES-SYSINH-003 | Exclude detected-type wells from error assignment | HIGH | Draft |
Key Integration Points: Well Association Engine, LIMS Outcome Processor, Error Assignment Engine, Observation Classification System
Rule Summary
| Property | Value |
|---|---|
| Name | SYSTEMIC_INHIBITION |
| Triggers | When evaluating wells for systemic inhibition patterns |
| Output | Assigns SYSTEMIC_INHIBITON_DETECTED or INHN error codes |
| Threshold | More than 2 inhibited wells (3+) |
Rule Flowchart (Illustrative)
This diagram illustrates the core systemic inhibition detection logic. Association grouping occurs in upstream processing.
Definitions
| Term | Definition |
|---|---|
| Associated Wells | Wells sharing the same Mix, Extraction Instrument, Extraction Date, and Batch |
| Inhibited Outcome | A LIMS outcome where is_inhibited: true |
| Positive Well | A well where all non-IC, active observations have negative classification |
| Systemic Inhibition | Condition where more than 2 associated wells show inhibition, indicating a systematic problem |
| IC | Internal Control - a control target used to validate sample processing |
| Detected-Type LIMS | LIMS outcomes classified as DETECTED_LOQ, DETECTED_QUANT, or DETECTED_HIQ |
Assumptions
- Wells are pre-grouped by association criteria before rule execution
- LIMS outcomes have
is_inhibitedflag populated from upstream processing - Observation classifications (positive/negative) are determined prior to systemic inhibition evaluation
- Patient and control well types are distinguishable in the data model
Requirements
Core Detection (REQ-RULES-SYSINH-001)
FR-SYSINH-001: Detect Systemic Inhibition Across Associated Wells
The system shall assign the SYSTEMIC_INHIBITON_DETECTED error to positive associated wells when more than 2 associated wells have an inhibited outcome.
Acceptance Criteria
Well Association:
- Evaluate wells as associated when they share the same mix, extraction instrument, extraction date, and batch
- Require ALL four association criteria to match: same mix, same extraction instrument, same extraction date, same batch
- Wells differing in any association criterion shall be evaluated as separate groups
Inhibition Detection:
- Identify inhibited outcomes by LIMS with is_inhibited: true
- Trigger systemic inhibition error when more than 2 wells in an associated group have inhibited outcomes (threshold is >2, meaning 3+ inhibited wells)
- Given exactly 2 associated wells with inhibited outcomes, no error shall be assigned (threshold not met)
- Given wells where is_inhibited is FALSE, no error shall be assigned
- Use "more than 2" (strictly greater than) as the inhibition threshold, meaning 3 or more inhibited wells trigger the rule
Positive Well Determination:
- Identify a well as "positive" when all non-IC, active observations have negative classification
- Determine a positive well by examining only non-IC, active observations where all must have negative classification
Error Assignment:
- Given more than 2 associated wells with inhibited outcomes, when the systemic inhibition rule executes on a positive well, the well shall receive SYSTEMIC_INHIBITON_DETECTED error
- Assign error code SYSTEMIC_INHIBITON_DETECTED (note: preserved typo for backward compatibility)
INHN Override:
- Given a well with at least one positive observation among non-IC active observations, when systemic inhibition is detected, the well shall receive INHN instead of SYSTEMIC_INHIBITON_DETECTED
- Given a well with all negative non-IC active observations, when systemic inhibition is detected, the well shall receive SYSTEMIC_INHIBITON_DETECTED
- Assign INHN instead of SYSTEMIC_INHIBITON_DETECTED to wells with at least one positive observation
Trace: Source: 3.0.0-Systemic Inhibition Rule (Row 1) | Jira: BT-4150, BT-4523 | Tests: BT-4163 | Related: REQ-RULES-SYSINH-002, REQ-RULES-SYSINH-003
Control Well Exclusion (REQ-RULES-SYSINH-002)
FR-SYSINH-002: Exclude Control Wells from Systemic Inhibition Evaluation
The system shall only evaluate patient wells when determining systemic inhibition, excluding control wells from the affected well count and error assignment.
Acceptance Criteria
Exclusion Rules:
- Do not count control wells toward the "more than 2 inhibited wells" threshold
- Do not assign SYSTEMIC_INHIBITON_DETECTED error to control wells even if associated with affected patient wells
- Only patient-type wells shall participate in systemic inhibition rule evaluation
Threshold Calculation:
- Given patient wells with inhibited LIMS and control wells with errors affecting systemic inhibition, when the threshold would be met only by including controls, the error shall not be triggered
- Given 2 patient wells with inhibited LIMS and 1 control well with inhibited LIMS, no error shall be assigned (only 2 patient wells, threshold not met)
- Given 3+ patient wells with inhibited LIMS regardless of control well status, patient wells shall receive SYSTEMIC_INHIBITON_DETECTED error
Trace: Source: 3.0.0-Exclude Every Detected Typed Wells from Affecting (Row 1) | Jira: BT-4943, BT-5049 | Tests: [Pending] | Related: REQ-RULES-SYSINH-001
Detected-Type Exclusion (REQ-RULES-SYSINH-003)
FR-SYSINH-003: Exclude Detected-Type Wells from Systemic Inhibition Error
The system shall exclude wells with detected-type LIMS outcomes from receiving the SYSTEMIC_INHIBITON_DETECTED error, allowing them to retain their original detected LIMS status.
Acceptance Criteria
Detected-Type Recognition:
- Recognize DETECTED_LOQ, DETECTED_QUANT, and DETECTED_HIQ as detected-type LIMS outcomes
- Limit detected types to: DETECTED_LOQ, DETECTED_QUANT, DETECTED_HIQ
Error Exclusion:
- Wells with detected-type LIMS shall retain their original outcome and not receive SYSTEMIC_INHIBITON_DETECTED error
- Retain the original LIMS code for detected wells without modification
- Wells without detected-type LIMS in the same associated group shall still receive SYSTEMIC_INHIBITON_DETECTED error when threshold is met
Group Behavior:
- Given a well with detected-type LIMS (DETECTED_LOQ, DETECTED_QUANT, or DETECTED_HIQ) in an associated group with systemic inhibition, the detected well shall retain its original LIMS and not receive SYSTEMIC_INHIBITON_DETECTED
- Given a well without detected-type LIMS in an associated group with systemic inhibition, the well shall receive SYSTEMIC_INHIBITON_DETECTED error
- Given an associated group where all wells have detected-type LIMS, when systemic inhibition is detected, all wells shall retain their detected LIMS
Trace: Source: 3.0.0-Exclude Every Detected Typed Wells from Affecting (Row 2) | Jira: BT-4943, BT-5049 | Tests: [Pending] | Related: REQ-RULES-SYSINH-001
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
inhibitionThreshold | 2 | Number of inhibited wells required (rule triggers when count > threshold) | REQ-RULES-SYSINH-001 |
detectedTypes | ["DETECTED_LOQ", "DETECTED_QUANT", "DETECTED_HIQ"] | LIMS types excluded from error assignment | REQ-RULES-SYSINH-003 |
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/SystemicInhibitionRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-SYSINH-001 | Detect Systemic Inhibition Across Associated Wells | Test | SystemicInhibitionRule | BT-4163 | Draft |
| REQ-RULES-SYSINH-002 | Exclude Control Wells from Systemic Inhibition Evaluation | Test | SystemicInhibitionRule | [Pending] | Draft |
| REQ-RULES-SYSINH-003 | Exclude Detected-Type Wells from Systemic Inhibition Error | Test | SystemicInhibitionRule | [Pending] | Draft |
Notes
- The error code "SYSTEMIC_INHIBITON_DETECTED" contains a typo ("INHIBITON" instead of "INHIBITION"). This is preserved intentionally for backward compatibility with existing systems and test cases.
- This rule is part of the systemic inhibition detection feature set (Epic BT-4142: Phase A)
- The sub-rule "Exclude Every Detected Typed Wells from Affecting" is implemented across REQ-RULES-SYSINH-002 and REQ-RULES-SYSINH-003
Acceptance Tests
Test: REQ-RULES-SYSINH-001
Test: Case 1a - Basic trigger with 3+ inhibited wells
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A (positive well, no inhibited LIMS)
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix A, Extraction A, Date A, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive SYSTEMIC_INHIBITON_DETECTED error
Test: Case 1b - Trigger with different inhibited LIMS
Given: LIMS A, LIMS B, LIMS C all with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A (positive well)
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS B
And: Well A4 with Mix A, Extraction A, Date A, Batch A, LIMS C
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive SYSTEMIC_INHIBITON_DETECTED error
Test: Case 2 - No trigger when inhibited is FALSE
Given: LIMS A with is_inhibited: FALSE
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix A, Extraction A, Date A, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 3 - No trigger with only 2 inhibited wells (threshold not met)
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 4 - No trigger when mix differs
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 5 - No trigger when extraction instrument differs
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction B, Date A, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 6 - No trigger when extraction date differs
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date B, Batch A, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 7 - No trigger when batch differs
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch B, LIMS A
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 8 - No trigger with mixed inhibited status
Given: LIMS A with is_inhibited: true
And: LIMS B with is_inhibited: FALSE
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch B, LIMS B
When: Well A1 is analysed through systemic inhibition rule
Then: Well A1 shall receive no error
Test: Case 9 - Mixed results with positive observations
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 has observation: target=non-ic active, cls=positive
When: Wells are analysed through systemic inhibition rule
Then: Well A1 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A2 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A3 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A4 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A5 shall receive INHN (has positive observation)
Test: Case 10 - Mixed observations (positive and negative)
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 has observations: obs 1 target=non-ic active cls=positive, obs 2 target=non-ic active cls=negative
When: Wells are analysed through systemic inhibition rule
Then: Well A1 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A2 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A3 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A4 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A5 shall receive INHN (has at least one positive observation)
Test: Case 11 - All negative observations
Given: LIMS A with is_inhibited: true
And: Well A1 with Mix A, Extraction A, Date A, Batch A
And: Well A2 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A3 with Mix A, Extraction A, Date A, Batch A, LIMS A
And: Well A4 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 with Mix B, Extraction A, Date A, Batch B, LIMS A
And: Well A5 has observations: obs 1 target=non-ic active cls=negative, obs 2 target=non-ic active cls=negative
When: Wells are analysed through systemic inhibition rule
Then: Well A1 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A2 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A3 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A4 shall receive SYSTEMIC_INHIBITON_DETECTED
And: Well A5 shall receive SYSTEMIC_INHIBITON_DETECTED (all negative = positive well)
Test: REQ-RULES-SYSINH-002
Test: Patient wells with controls excluded
Given: Well A1 type=Patient with LIMS affecting systemic inhibition
And: Well A2 type=Patient with LIMS affecting systemic inhibition
And: Well A3 type=Control with error affecting systemic inhibition
And: Threshold limit is 3
When: Well A1 is executed through systemic inhibition rule
Then: Error shall not be triggered (only 2 patient wells counted)
Test: REQ-RULES-SYSINH-003
Test: Case 1 - Detected well excluded from error
Given: Wells A1, A2, A3, A4 in same association
And: A2, A3, A4 outcome is inhibited
And: A1 has LIMS considered as detected (e.g., DETECTED_LOQ)
When: Execute through systemic inhibition rule
Then: A1 shall retain detected LIMS (no systemic inhibition error)
And: A2 shall receive systemic inhibition error
And: A3 shall receive systemic inhibition error
And: A4 shall receive systemic inhibition error
Test: Case 2 - Non-detected well receives error
Given: Wells A1, A2, A3, A4 in same association
And: A2, A3, A4 outcome is inhibited
And: A1 has LIMS NOT considered as detected
When: Execute through systemic inhibition rule
Then: A1 shall receive systemic inhibition error
And: A2 shall receive systemic inhibition error
And: A3 shall receive systemic inhibition error
And: A4 shall receive systemic inhibition error
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A: 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 - N/A: analytics rule
- 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 Applied
The three requirements in this domain represent distinct capabilities:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-SYSINH-001 | Core systemic inhibition detection logic | Primary rule with threshold and error assignment |
| REQ-RULES-SYSINH-002 | Control well exclusion scope | Distinct exclusion behavior for well type |
| REQ-RULES-SYSINH-003 | Detected-type well exclusion from error assignment | Distinct exclusion behavior for LIMS type |
Rationale: Per RULES domain guidance, conservative consolidation is required for analytics rules. These requirements have distinct responsibilities and test scenarios. They are not variants of a single capability but separate, independently testable behaviors.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-systemic-inhibition/rule-systemic-inhibition-restructured.md