Negative Control Inhibition Rule
Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: BICQUAL rule for detecting inhibition in negative extraction control wells Domain: RULES-NECINH Precedence: During run analysis
Statement
The system shall detect inhibition in Negative Extraction Control (NEC) wells by evaluating Internal Control (IC) amplification results and generate appropriate error codes when inhibition is detected.
When the IC CT value exceeds 35 cycles, or when the IC classification is Negative (with null CT), the rule generates both well-level (BIQUAL_WELL) and run-target-level (BICQUAL_TARGET) errors. This quality control check ensures that PCR inhibitors carried through extraction are identified before results are released.
As of v3.1.0, the rule also detects when a well has an IC mapping but no IC target observation is present, raising the IC_MAPPED_BUT_NO_IC_TARGET error and preventing further analysis (BT-6126).
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-NECINH-001 | Detects inhibition in NEC wells via IC amplification and generates error codes | HIGH | Draft |
| REQ-RULES-NECINH-002 | Detects missing IC target observation when IC mapping exists | HIGH | Draft |
| REQ-RULES-NECINH-003 | Assigns IC_MAPPED_BUT_NO_IC_TARGET error code when missing IC observation detected | HIGH | Draft |
Key Integration Points: Run Analysis Engine, Quality Control System, Extraction Control Processing, Run Validation Workflow, Error Code System (errorcodes.md)
Rule Summary
| Property | Value |
|---|---|
| Name | BICQUAL |
| Triggers | When evaluating NEC wells during run analysis |
| Output | BIQUAL_WELL (well error), BICQUAL_TARGET (run target error), IC_MAPPED_BUT_NO_IC_TARGET (well error, v3.1.0) |
Rule Flowchart (Illustrative)
This diagram illustrates the BICQUAL rule decision process, including the v3.1.0 missing IC observation check, for detecting inhibition in Negative Extraction Controls. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| NEC | Negative Extraction Control - a control well used to verify extraction process purity |
| IC | Internal Control - an amplification target used to verify PCR reaction success |
| CT | Cycle Threshold - the PCR cycle number at which fluorescence exceeds background |
| BICQUAL | Rule identifier for Negative Control Inhibition detection |
| Well Error | An error code assigned to a specific well indicating a quality issue |
| Run Target Error | An error code assigned at the run-target level indicating a batch quality issue |
| IC_MAPPED_BUT_NO_IC_TARGET | Error code raised when a well has an IC control rule mapped but no IC target observation is present (v3.1.0, see errorcodes.md) |
Assumptions
- NEC wells are correctly identified and classified in the run data
- IC channel data is available for evaluation in NEC wells
- CT threshold of 35 cycles is the standard cutoff for acceptable IC amplification
- Error code generation system is available to receive BIQUAL_WELL, BICQUAL_TARGET, and IC_MAPPED_BUT_NO_IC_TARGET codes
Requirements
NEC Inhibition Detection (REQ-RULES-NECINH-001)
FR-NECINH-001: Detect Inhibition in Negative Extraction Control Wells
The system shall detect inhibition in Negative Extraction Control (NEC) wells by evaluating Internal Control (IC) amplification results and generate appropriate error codes when inhibition is detected.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | NEC well IC target CT value | PCR analysis |
| Input | NEC well IC target classification | PCR analysis |
| Output | Well Error code (BIQUAL_WELL) | Well record |
| Output | Run Target Error code (BICQUAL_TARGET) | Run target record |
Acceptance Criteria
Inhibition Detection Triggers:
- When IC CT value exceeds 35 in a NEC well, the system shall generate an error
- When IC target classification is Negative in a NEC well, the system shall apply the same error behavior as when CT > 35
- When IC target Final Classification is Negative and Final CT is null, the system shall treat this condition equivalently to the CT > 35 threshold case
Error Code Generation:
- When inhibition is detected, the system shall generate Well Error code: BIQUAL_WELL
- When inhibition is detected, the system shall generate Run Target Error code: BICQUAL_TARGET
- The system shall use specific error code prefixes: Well Error shall use "BIQUAL" (single I), Run Target Error shall use "BICQUAL" (with IC)
Threshold Behavior:
- When IC CT value is less than or equal to 35 and IC classification is Positive, the system shall not generate inhibition errors
- The system shall use a CT threshold value of 35 as the boundary for acceptable IC amplification; values at exactly 35 shall not trigger errors
Error Handling
- IC CT > 35 in NEC well: Generate BIQUAL_WELL and BICQUAL_TARGET errors
- IC classification is Negative (CT is null): Generate BIQUAL_WELL and BICQUAL_TARGET errors
- IC CT <= 35 with Positive classification: Do not generate inhibition errors (normal condition)
Trace: Source: 3.0.0-Negative Control Inhibition (Objective section, Lines 23-24; Requirements Table 1 Row 1, Lines 39-55; Requirements Table 2 Row 1, Lines 63-66) | Jira: BT-3281, BT-3191 | Epic: BT-674 | Tests: See scenarios
Missing IC Observation Detection (REQ-RULES-NECINH-002)
FR-NECINH-002: Detect Missing IC Target Observation
The system shall detect when a well has an IC control rule mapped but no IC target observation is present, and shall raise an error before performing any IC inhibition checks.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well IC control rule mapping | Rule configuration |
| Input | Well IC target observations | PCR analysis |
| Output | Well Error code (IC_MAPPED_BUT_NO_IC_TARGET) | Well record |
Acceptance Criteria
Missing IC Observation Detection:
- When the BICQUAL rule runs during analysis and the well has an IC mapping but the mix has no IC target observation, the system shall set the IC_MAPPED_BUT_NO_IC_TARGET error on the well
- When the IC_MAPPED_BUT_NO_IC_TARGET error is raised, the system shall not perform any further IC inhibition checks for that well (early exit)
- When the well has an IC target observation present, the system shall proceed with the standard IC inhibition checks (no change from previous behavior)
Error Handling
- IC mapping present but no IC target observation: Set IC_MAPPED_BUT_NO_IC_TARGET error, prevent further analysis
- IC target observation present: Proceed to standard inhibition checks (REQ-RULES-NECINH-001)
Trace: Source: 3.1.0-BICQUAL Rule (Handle No IC Observation Well, Row 1) | Jira: BT-6126 | Tests: See scenarios | Cross-ref: errorcodes.md
IC_MAPPED_BUT_NO_IC_TARGET Error Code (REQ-RULES-NECINH-003)
FR-NECINH-003: IC_MAPPED_BUT_NO_IC_TARGET Error Code Definition
The system shall define the IC_MAPPED_BUT_NO_IC_TARGET error code as a well-level error that prevents analysis when a well has an IC control rule mapped but no IC target observation is found.
Acceptance Criteria
Error Code Properties:
- The error code identifier shall be IC_MAPPED_BUT_NO_IC_TARGET
- The error message shall be "IC is mapped but no IC target observation was found."
- The error level shall be Well
- The error type shall be Error
- The error shall prevent analysis (prevents_analysis = Yes)
- The error shall not indicate inhibition (is_inhibited = No)
- The error shall not cause missing mixes (causes_missing_mixes = No)
Provisioning:
- The error code shall be site-scoped, with one record created per site via database migration
- If a site already has the IC_MAPPED_BUT_NO_IC_TARGET error code, the migration shall not create a duplicate record
Trace: Source: 3.1.0-BICQUAL Rule (Handle No IC Observation Well, Row 2) | Jira: BT-6126 | Tests: See scenarios | Cross-ref: errorcodes.md
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
ic_ct_threshold | 35 (fixed) | CT threshold above which IC amplification is considered inhibited | REQ-RULES-NECINH-001 |
Note: The IC CT threshold of 35 is fixed for this rule. Configurable threshold options are provided by a separate rule.
UI Notes (Illustrative)
This rule has no direct UI components. It operates as backend quality control logic that evaluates Negative Extraction Control wells. The errors generated by this rule are consumed by:
Error Display Integration
- Well Grid: Displays well-level errors (BIQUAL_WELL)
- Run Target Summary: Shows run target errors (BICQUAL_TARGET)
- QC Reports: Quality control indicators in exported reports
- Run Validation Workflow: May prevent result release when NEC inhibition is detected
Flow Diagram Reference
Reference: media/image162.png - Flow diagram showing the BICQUAL rule decision process for detecting inhibition in Negative Extraction Controls.
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/InhRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-NECINH-001 | Detect Inhibition in NEC Wells | Test | InhRule | [Pending] | Draft |
| REQ-RULES-NECINH-002 | Detect Missing IC Target Observation | Test | InhRule | [Pending] | Draft |
| REQ-RULES-NECINH-003 | IC_MAPPED_BUT_NO_IC_TARGET Error Code | Test | Migration + Error Code Registry | [Pending] | Draft |
Notes
- Rule ID: BICQUAL
- Also known as: "Negative extraction control has inhibition"
- The rule triggers specifically on NEC wells (not other control types)
- CT > 35 indicates weak or late amplification of the Internal Control, suggesting inhibition
- This rule is part of the extraction control validation suite
- Related rule: PICQUAL Rule (BT-3281) for Positive Extraction Control validation
- Rule executes during: run analysis completion, re-analysis operations, and manual result review workflows
- v3.1.0: Added early check for missing IC target observation before IC inhibition evaluation (BT-6126)
Acceptance Tests
Test: REQ-RULES-NECINH-001
Test: IC CT exceeds threshold in NEC well
Given: A Negative Extraction Control well
And: The Internal Control (IC) target has CT > 35
When: The BICQUAL rule is evaluated
Then: The system shall generate Well Error = BIQUAL_WELL
And: The system shall generate Run Target Error = BICQUAL_TARGET
Test: IC target is Negative classification in NEC well
Given: A Negative Extraction Control well
And: The IC target Final Classification = Neg
And: The IC target Final Ct = null
When: The BICQUAL rule is evaluated
Then: The system shall generate Well Error = BIQUAL_WELL
And: The system shall generate Run Target Error = BICQUAL_TARGET
Test: Normal IC amplification (no error)
Given: A Negative Extraction Control well
And: The Internal Control (IC) target has CT <= 35
And: The IC target Final Classification = Positive
When: The BICQUAL rule is evaluated
Then: The system shall not generate any inhibition errors
Test: Boundary condition at CT = 35
Given: A Negative Extraction Control well
And: The Internal Control (IC) target has CT = 35 exactly
And: The IC target Final Classification = Positive
When: The BICQUAL rule is evaluated
Then: The system shall not generate any inhibition errors
Test: REQ-RULES-NECINH-002
Test: Missing IC target observation raises error
Given: A well has an IC control rule mapped but the mix has no IC target observation
When: The BICQUAL rule runs during analysis
Then: The IC_MAPPED_BUT_NO_IC_TARGET error is set on the well
And: Analysis is prevented for that well
Test: IC target observation present proceeds normally
Given: A well has an IC target observation present
When: The BICQUAL rule runs during analysis
Then: The standard IC inhibition checks proceed as normal
Test: REQ-RULES-NECINH-003
Test: Error code provisioned per site via migration
Given: The system is upgraded to v3.1.0
When: The database migration runs
Then: The IC_MAPPED_BUT_NO_IC_TARGET error code is created for every site that does not already have it
Test: No duplicate error code on re-migration
Given: A site already has the IC_MAPPED_BUT_NO_IC_TARGET error code
When: The migration runs
Then: No duplicate record is created for that site
Test Data Matrix
| Test Scenario | IC Final CLS | IC Final CT | Expected Well Error | Expected Target Error |
|---|---|---|---|---|
| Normal IC | Positive | 25.0 | None | None |
| Borderline IC | Positive | 35.0 | None | None |
| Inhibited IC | Positive | 36.0 | BIQUAL_WELL | BICQUAL_TARGET |
| Late IC | Positive | 45.0 | BIQUAL_WELL | BICQUAL_TARGET |
| Negative IC | Negative | null | BIQUAL_WELL | BICQUAL_TARGET |
| Missing IC observation | N/A (no observation) | N/A | IC_MAPPED_BUT_NO_IC_TARGET | None |
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 folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
v3.1.0: Added missing IC observation handling (BT-6126)
Two new requirements added to handle the case where a well has an IC control rule mapped but no IC target observation is present:
- REQ-RULES-NECINH-002: Detects missing IC target observation and raises an error before IC inhibition checks
- REQ-RULES-NECINH-003: Defines the IC_MAPPED_BUT_NO_IC_TARGET error code properties and site-scoped provisioning
Previously, the BICQUAL rule silently skipped IC inhibition checks when the IC target observation was missing. The new behavior raises an explicit error. Cross-references errorcodes.md for the new error code definition.
No Consolidation Required (v3.0.0)
This domain originally contained a single requirement (REQ-RULES-NECINH-001) representing a distinct analytical rule capability. No consolidation was performed as:
- The source material contained one primary requirement with supporting acceptance criteria
- All test scenarios describe variants of the same detection behavior
- The rule has a single, focused purpose consistent with analytics rule design
Source Preservation:
- Original requirement ID: REQ-RULES-NECINH-001
- All acceptance criteria preserved (grouped by concern)
- Gherkin test scenarios preserved in Acceptance Tests section
- Refinements (RF-01 through RF-03) folded into acceptance criteria
Reversibility: To reference original structure:
- Source:
output/pilot/rules/rule-negative-control-inhibition/rule-negative-control-inhibition-restructured.md - SDD:
output/pilot/rules/rule-negative-control-inhibition/sdd/rule-negative-control-inhibition-design.md - Confluence: 3.0.0-Negative Control Inhibition