Inhibition - Qualitative Rule (PICQUAL)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Detect suspected inhibition in qualitative sample wells via IC CT evaluation Domain: RULES-INHQUAL Precedence: Standard rule order
Statement
The system shall evaluate qualitative sample wells for suspected inhibition using the PICQUAL rule, which examines Internal Control (IC) cycle threshold values and assigns appropriate error codes based on sample test history.
The rule provides an early-exit path when the IC CT is acceptable (<=35) or when non-IC observations show amplification (CT < CutOff). A quantity-based bypass (configurable, default 10,000) short-circuits repeat/first-run checks when signal strength is sufficient. When inhibition is confirmed, the system distinguishes between repeat samples (ICQUAL_INHN) and first-run samples (ICQUAL_FIRST_RUN) for appropriate follow-up action.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-INHQUAL-001 | Detect inhibition via IC CT threshold and assign error codes | HIGH | Draft |
| REQ-RULES-INHQUAL-002 | Bypass repeat/first-run check when quantity meets cutoff | HIGH | Draft |
Key Integration Points: Well/Observation data, Sample History tracking, Error Code management, Quantification engine
Rule Summary
| Property | Value |
|---|---|
| Name | PICQUAL |
| Target | IC (Internal Control) |
| IC CT Threshold | 35 |
| Quantity Cutoff | 10,000 (configurable) |
| Error Codes | ICQUAL_INHN, ICQUAL_FIRST_RUN |
Rule Flowchart (Illustrative)
This diagram illustrates the core decision flow. Evaluation order is: IC CT check, non-IC CT check, quantity bypass check, then repeat/first-run determination.
Definitions
| Term | Definition |
|---|---|
| PICQUAL | Rule identifier for qualitative inhibition detection |
| IC | Internal Control - a target used to verify PCR amplification occurred correctly |
| CT | Cycle Threshold - the PCR cycle number at which fluorescence exceeds the threshold |
| Inhibition | A condition where PCR amplification is suppressed, leading to unreliable results |
| Sample/Mix combination | The unique pairing of a sample ID and mix ID used to track repeat testing |
| CutOff | Configured threshold value for CT or quantity comparisons |
Assumptions
- The well being evaluated contains at least one IC observation
- The system has access to sample testing history to determine if Sample/Mix has been tested before
- CT values and quantity values are available for observations in the well
- The cutoff threshold value is configured in the system
- The cutoff check (quantity >= 10,000) is evaluated BEFORE the repeat/first-run check in the rule flow
Requirements
Inhibition Detection (REQ-RULES-INHQUAL-001)
FR-INHQUAL-001: Detect Inhibition in Qualitative Wells
The system shall evaluate qualitative sample wells for suspected inhibition using the PICQUAL rule and assign appropriate error codes based on IC CT values, non-IC observation values, and sample testing history.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well observations (IC target, CT values, classifications) | PCR analysis |
| Input | Sample/Mix testing history | History store |
| Input | CutOff threshold | Kit configuration |
| Output | Error code (ICQUAL_INHN or ICQUAL_FIRST_RUN) | Well record |
| Output | Repeat testing flag | Sample record |
Acceptance Criteria
IC CT Pass Condition:
- The rule shall end without error if the CT value for the IC observation is less than or equal to 35
- The IC CT threshold value shall be 35
- The rule shall be mapped to the IC (Internal Control) target
Non-IC Amplification Check:
- The rule shall end without error if there is at least one non-IC observation with CT less than the CutOff value
Error Assignment:
- When all checks fail and the Sample and Mix combination has been tested before, the rule shall return error code
ICQUAL_INHN - When all checks fail and this is the first run for the Sample and Mix combination, the rule shall return error code
ICQUAL_FIRST_RUN - When a sample is inhibited (CT > threshold), the system shall mark the sample for repeat testing
- When a repeat sample is still inhibited, the system shall generate an error
Evaluation Order:
- The system shall evaluate in the following order: IC CT check, then non-IC CT check, then repeat/first-run determination
Error Handling
| Condition | Response |
|---|---|
| IC CT > 35 AND no non-IC with CT < CutOff AND repeat sample | Return error ICQUAL_INHN |
| IC CT > 35 AND no non-IC with CT < CutOff AND first run | Return error ICQUAL_FIRST_RUN |
Trace: Source: 3.0.0-Inhibition - Qualitative (Requirements Table Rows 1-3, Acceptance Criteria Table) | Jira: BT-674 | Tests: See scenarios
Quantity Bypass (REQ-RULES-INHQUAL-002)
FR-INHQUAL-002: Bypass Repeat Check When Quantity Meets Cutoff
The system shall skip repeat and first-run checks when the observation quantity value meets or exceeds the configured cutoff threshold, preventing unnecessary error flagging for wells with sufficiently high quantity values.
Acceptance Criteria
Quantity Threshold Logic:
- The rule shall not perform repeat or first-run checks if the quantity is greater than or equal to the cutoff value
- The rule shall not perform repeat or first-run checks if the quantity exceeds the cutoff value
- Default cutoff value shall be 10,000 (configurable)
Short-Circuit Behavior:
- The cutoff check shall short-circuit the repeat/first-run evaluation to prevent unnecessary processing
Boundary Behavior:
- Given well A1 with observation A (target: Non-IC) and observation B (target: IC, CT: 36, classification: Neg), when observation A quantity equals 10,000, then the PICQUAL rule shall return no error
- Given well A1 with observation A (target: Non-IC) and observation B (target: IC, CT: 36, classification: Neg), when observation A quantity equals 10,001, then the PICQUAL rule shall return no error
Naming:
- This sub-rule shall also be referred to as PICQUANT Rule in Jira
Trace: Source: 3.0.0-PICQUAL Rule - Cutoff Check Before Repeat Check (Row 1, Test Scenarios) | Jira: BT-4491 | Tests: See scenarios | Related: REQ-RULES-INHQUAL-001 (parent rule)
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
IC_CT_THRESHOLD | 35 | CT threshold for IC pass condition | REQ-RULES-INHQUAL-001 |
QUANTITY_CUTOFF | 10,000 | Cutoff value for bypassing repeat check | REQ-RULES-INHQUAL-002 |
Error Code Reference
| Error Code | Meaning | Trigger Condition |
|---|---|---|
ICQUAL_INHN | Inhibition detected (repeat sample) | Sample/Mix previously tested and failed IC checks |
ICQUAL_FIRST_RUN | Inhibition detected (first run) | Sample/Mix first test and failed IC checks |
UI Notes (Illustrative)
REQ-RULES-INHQUAL-001 UI Specifications
Flow Diagram:
- Rule flow diagram available: image155.png
- Configuration sheet reference: image147.jpeg
Configuration Interface:
- Rule is mapped to IC target in configuration sheet
Implementation (Illustrative)
| Component | Location |
|---|---|
| BicqualRule | Analyzer/Rules/BicqualRule.php |
| PicqualRule | Analyzer/Rules/PicqualRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-INHQUAL-001 | Detect Inhibition in Qualitative Wells | Test | BicqualRule, PicqualRule | [Pending] | Draft |
| REQ-RULES-INHQUAL-002 | Bypass Repeat Check When Quantity Meets Cutoff | Test | PicqualRule | [Pending] | Draft |
Notes
- The PICQUAL rule is part of the broader inhibition detection framework
- Also known as "IC Inhibition for qual samples"
- The sub-rule (REQ-RULES-INHQUAL-002) was added via BT-4491 to optimize rule evaluation by short-circuiting unnecessary repeat checks when quantity is sufficient
Acceptance Tests
Test: REQ-RULES-INHQUAL-001
Test: IC CT passes threshold
Given: A qualitative well with IC observation
And: IC CT value is 35 or less
When: The PICQUAL rule evaluates the well
Then: The rule shall end without error
Test: Non-IC CT below cutoff
Given: A qualitative well with IC CT > 35
And: At least one non-IC observation with CT < CutOff
When: The PICQUAL rule evaluates the well
Then: The rule shall end without error
Test: Inhibition detected on repeat sample
Given: A qualitative well with IC CT > 35
And: No non-IC observation with CT < CutOff
And: The Sample/Mix combination has been tested before
When: The PICQUAL rule evaluates the well
Then: The rule shall return error code ICQUAL_INHN
Test: Inhibition detected on first run
Given: A qualitative well with IC CT > 35
And: No non-IC observation with CT < CutOff
And: This is the first run for the Sample/Mix combination
When: The PICQUAL rule evaluates the well
Then: The rule shall return error code ICQUAL_FIRST_RUN
Test: REQ-RULES-INHQUAL-002
Test: Quantity at cutoff boundary
Given: Well A1 with:
- Observation A: target = Non-IC
- Observation B: target = IC, CT = 36, classification = Neg
When: Observation A quantity = 10,000
And: The PICQUAL rule evaluates observation A
Then: The rule shall return no error
Test: Quantity above cutoff
Given: Well A1 with:
- Observation A: target = Non-IC
- Observation B: target = IC, CT = 36, classification = Neg
When: Observation A quantity = 10,001
And: The PICQUAL rule evaluates observation A
Then: The rule shall return no error
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
Conservative Consolidation Applied
Both requirements are preserved as separate entities per RULES domain guidance:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-RULES-INHQUAL-001 | 3.0.0-Inhibition - Qualitative | Preserved as REQ-RULES-INHQUAL-001 |
| REQ-RULES-INHQUAL-002 | 3.0.0-PICQUAL Rule - Cutoff Check Before Repeat Check | Preserved as REQ-RULES-INHQUAL-002 |
Rationale: The sub-rule has its own Jira ticket (BT-4491) and distinct test scenarios. In the RULES domain, analytics must be precise, so no aggressive merging was applied.
Test Scenarios Preserved: All Given/When/Then scenarios from the source are preserved as acceptance criteria (AC-04, AC-05 in REQ-RULES-INHQUAL-002).
Reversibility: To reference original structure:
- Source:
output/pilot/rules/rule-inhibition-qualitative/rule-inhibition-qualitative-restructured.md - SDD:
output/pilot/rules/rule-inhibition-qualitative/sdd/rule-inhibition-qualitative-design.md