AMB Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: AMB rule for processing ambiguous classification results during PCR run analysis Domain: RULES-AMB Precedence: During run import (observation-level processing)
Statement
The system shall process observations with ambiguous (Amb) classification results by assigning the CLASSIFICATION problem, displaying visual indicators, and enabling resolution through structured resolution codes.
When the classification algorithm cannot determine a definitive Positive or Negative result, observations are flagged as Amb. The AMB rule operates at the observation level (not well level), assigns problem flags, provides UI flagging, and processes three resolution code variants (AMB,SETPOS, AMB,SETNEG, AMB) to clear errors while optionally changing classification. Manual resolution is prohibited; users must use the resolution code mechanism.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-AMB-001 | Assigns CLASSIFICATION problem to AMB observations | HIGH | Draft |
| REQ-RULES-AMB-002 | Displays visual flagging for AMB observations | MEDIUM | Draft |
| REQ-RULES-AMB-003 | Processes resolution codes to update classification | HIGH | Draft |
| REQ-RULES-AMB-004 | Prevents manual resolution of AMB observations | HIGH | Draft |
Key Integration Points: Analytics Engine, Run Import workflow, Resolution Code system, User Interface
Rule Summary
| Property | Value |
|---|---|
| Name | AMB |
| Preferred Provider | dxai |
| Triggers | Run import with observations having final_cls: AMB |
| Output | Sets problem on observation, processes resolutions |
Rule Flowchart (Illustrative)
This diagram illustrates the AMB rule decision logic. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Amb | Ambiguous classification - an observation where the classification algorithm could not determine a definitive Positive or Negative result |
| Observation | A single measurement record within a well, associated with a specific target/analyte |
| Resolution Code | A structured code (e.g., AMB,SETPOS) that specifies how to resolve an error condition |
| Problem | A flag on an observation indicating an issue requiring attention (e.g., CLASSIFICATION) |
| Error Code | A flag on a well indicating an error condition requiring resolution |
Assumptions
- The preferred provider is set to dxai for AMB rule execution
- Users accessing resolution functionality have appropriate role permissions (Client Admin or Junior User minimum)
- Resolution codes are applied through the system's error resolution mechanism, not manual entry
Requirements
Problem Assignment (REQ-RULES-AMB-001)
FR-AMB-001: Assign CLASSIFICATION Problem to AMB Observations
The system shall assign the CLASSIFICATION problem to observations with ambiguous classification when the AMB rule is executed during run import.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Observation with final_cls: AMB | PCR analysis |
| Output | problem = CLASSIFICATION | Observation record |
Acceptance Criteria
Problem Assignment:
- Given a well with an observation having final_cls: AMB, when the user imports the run through the AMB rule, then the observation shall have problem set to CLASSIFICATION
Well-Level Behavior:
- The system shall not set an outcome on the well when processing AMB observations
Processing Scope:
- The rule shall process each observation independently within the well
Error Handling
- Observation not AMB: skip processing (no problem assigned)
Trace: Source: 3.0.0-Rules / AMB Rule (Row 1) | Jira: BT-3850 | Epic: BT-3851 | Tests: BT-3880, See scenarios
Visual Indication (REQ-RULES-AMB-002)
FR-AMB-002: Display Visual Flagging for AMB Observations
The system shall display a visual indicator to flag observations with ambiguous classification when a user views a well.
Acceptance Criteria
Visual Display:
- Given a well with an observation having final_cls: AMB, when the user opens the runfile and views the well, then the observation shall be displayed as flagged
Role Access:
- The AMB classification shall be visible to Client Admin and Junior User roles
Assumptions
- User has Client Admin or Junior User role minimum to view AMB flagging
Trace: Source: 3.0.0-Rules / AMB Rule (Row 2) | Jira: [Pending] | Tests: [Pending], See scenarios
Resolution Processing (REQ-RULES-AMB-003)
FR-AMB-003: Process Resolution Codes for AMB Observations
The system shall process resolution codes to update observation classification and clear error conditions when resolving AMB errors.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well with error_code: AMB, resolution_codes | Resolution system |
| Input | Observation with final_cls: Amb, problems: CLASSIFICATION | Observation record |
| Output | Updated final_cls (Pos/Neg/Amb) | Observation record |
| Output | Cleared error_code, cleared problems | Well/Observation records |
Acceptance Criteria
Resolution Code Scenarios:
- Scenario: AMB,SETPOS resolution - Given a well with error_code: AMB, resolution_codes: AMB,SETPOS, and an observation with final_cls: Amb and problems: CLASSIFICATION, when the well is executed through the AMB Rule, then the well error_code shall be null, the observation final_cls shall be Pos, and the observation problems shall be empty
- Scenario: AMB,SETNEG resolution - Given a well with error_code: AMB, resolution_codes: AMB,SETNEG, and an observation with final_cls: Amb and problems: CLASSIFICATION, when the well is executed through the AMB Rule, then the well error_code shall be null, the observation final_cls shall be Neg, and the observation problems shall be empty
- Scenario: AMB resolution (no classification change) - Given a well with error_code: AMB, resolution_codes: AMB, and an observation with final_cls: Amb and problems: CLASSIFICATION, when the well is executed through the AMB Rule, then the well error_code shall be null, the observation final_cls shall remain Amb, and the observation problems shall be empty
Classification Updates:
- The system shall set observation final_cls to Positive when resolution code AMB,SETPOS is applied
- The system shall set observation final_cls to Negative when resolution code AMB,SETNEG is applied
- The system shall clear the error without changing classification when resolution code AMB is applied (observation shall remain Amb)
Isolation:
- Non-AMB observations in the same well shall not be affected by the resolution (their final_cls shall be preserved)
Resolution Code Mapping:
| Resolution Code | final_cls | error_code | problems |
|---|---|---|---|
| AMB,SETPOS | Pos | null | empty |
| AMB,SETNEG | Neg | null | empty |
| AMB | Amb (unchanged) | null | empty |
Error Handling
- No resolution code present: leave observation flagged with CLASSIFICATION problem
- Invalid resolution code: reject and maintain current state
Trace: Source: 3.0.0-Rules / AMB Rule (Row 3) | Jira: [Pending] | Tests: [Pending], See scenarios
Resolution Constraints (REQ-RULES-AMB-004)
FR-AMB-004: Prevent Manual Resolution of AMB Observations
The system shall not permit manual resolution entry for observations flagged by the AMB rule.
Acceptance Criteria
Manual Entry Prevention:
- The system shall not allow manual resolution entry for AMB-flagged observations
Required Mechanism:
- Resolution of AMB observations shall only be possible through the resolution code mechanism (REQ-RULES-AMB-003)
Error Handling
- Manual resolution attempted: system shall reject the action (UI affordance TBD per OQ-01)
Trace: Source: 3.0.0-Rules / AMB Rule (Row 4) | Jira: [Pending] | Tests: [Pending], See scenarios | Related: REQ-RULES-AMB-003
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
preferred_provider | dxai | Provider for AMB rule execution | REQ-RULES-AMB-001 |
[REVIEW REQUIRED: No additional configuration options identified in source material. Verify if any AMB rule parameters are configurable per deployment.]
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-01 | What UI affordance prevents manual entry (disabled control, hidden option, validation error)? | REQ-RULES-AMB-004 | @tbd | [Original] |
Notes
- Epic BT-3851: AMB Rule - Change Logic
- Task BT-3850: Change AMB Rule Logic not to Set Well Outcome
- Test BT-3880: Verify the new AMB Logic
- The AMB rule logic was changed to operate at observation level rather than setting well-level outcomes
- This requirement interacts with the Resolution Level feature
- Related rule: ICCT rule has similar resolution constraints (see separate ICCT rule documentation)
UI Notes (Illustrative)
FR-AMB-002 UI Specifications
Visual Flagging:
- AMB observations are flagged in red
- Applies to: Observation rows with final classification of AMB
- Visibility: Displayed when opening the runfile and checking well
Screenshots:
- Flow Diagram:
media/image145.png- Process flow diagram showing AMB rule logic and decision points - AMB Flagging Example:
media/image76.png- Screenshot showing how AMB observations appear flagged in red
FR-AMB-004 UI Specifications
Cross-Reference Notes:
- Resolution Level feature controls at what level resolutions can be applied
- ICCT rule has similar resolution constraints
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/AmbRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-AMB-001 | Assign CLASSIFICATION Problem | Test | AmbRule | BT-3880 | Draft |
| REQ-RULES-AMB-002 | Display Visual Flagging | Test | AmbRule (Frontend) | [Pending] | Draft |
| REQ-RULES-AMB-003 | Process Resolution Codes | Test | AmbRule | [Pending] | Draft |
| REQ-RULES-AMB-004 | Prevent Manual Resolution | Test | AmbRule | [Pending] | Draft |
Acceptance Tests
Test: REQ-RULES-AMB-001
Test: AMB observation gets CLASSIFICATION problem
Given: A well with an observation having final_cls: AMB
And: The preferred provider is dxai
When: The user imports the run through the AMB rule
Then: The observation shall have problem set to CLASSIFICATION
And: The well shall not have an outcome set
Test: REQ-RULES-AMB-002
Test: AMB observation displays visual flag
Given: A well with an observation having final_cls: AMB
And: User has Client Admin or Junior User role
When: The user opens the runfile and views the well
Then: The observation shall be displayed as flagged
Test: REQ-RULES-AMB-003
Test: AMB,SETPOS resolution changes classification to Positive
Given: A well with error_code: AMB
And: Resolution_codes: AMB,SETPOS
And: An observation with final_cls: Amb and problems: CLASSIFICATION
When: The well is executed through the AMB Rule
Then: The well error_code shall be null
And: The observation final_cls shall be Pos
And: The observation problems shall be empty
Test: AMB,SETNEG resolution changes classification to Negative
Given: A well with error_code: AMB
And: Resolution_codes: AMB,SETNEG
And: An observation with final_cls: Amb and problems: CLASSIFICATION
When: The well is executed through the AMB Rule
Then: The well error_code shall be null
And: The observation final_cls shall be Neg
And: The observation problems shall be empty
Test: AMB resolution clears error without changing classification
Given: A well with error_code: AMB
And: Resolution_codes: AMB
And: An observation with final_cls: Amb and problems: CLASSIFICATION
When: The well is executed through the AMB Rule
Then: The well error_code shall be null
And: The observation final_cls shall remain Amb
And: The observation problems shall be empty
Test: Non-AMB observations are not affected by resolution
Given: A well with error_code: AMB
And: An observation with final_cls: Amb (Observation A)
And: An observation with final_cls: Pos (Observation B)
When: The well is executed through the AMB Rule with resolution code AMB,SETNEG
Then: Observation A final_cls shall be Neg
And: Observation B final_cls shall remain Pos
Test: REQ-RULES-AMB-004
Test: Manual resolution is prevented for AMB observations
Given: An observation flagged by the AMB rule with problems: CLASSIFICATION
When: A user attempts manual resolution entry
Then: The system shall not allow the manual resolution
And: The user shall be required to use resolution codes
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Rule Processing |
| ICCT Rule | Similar resolution constraints |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A: no consolidation needed for RULES domain
- 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
- Mermaid diagram present and renders without errors
- Diagram marked as (Illustrative)
- No "non-normative" text anywhere
- All original REQ-* IDs preserved
- All ACs preserved with blank lines before bullet lists
- Tests at end with back-links
Reviewer Notes
No Consolidation Applied
All 4 requirements from the source were preserved as distinct capabilities:
| Original Item | Disposition | Rationale |
|---|---|---|
| REQ-RULES-AMB-001 (Problem assignment) | Preserved | Distinct analytics behavior for problem flagging |
| REQ-RULES-AMB-002 (Visual flagging) | Preserved | Distinct UI behavior for user awareness |
| REQ-RULES-AMB-003 (Resolution processing) | Preserved | Critical analytics behavior with multiple distinct scenarios |
| REQ-RULES-AMB-004 (Manual resolution constraint) | Preserved | Distinct constraint behavior |
Rationale: Per RULES domain guidelines, conservative consolidation was applied. Each requirement represents a distinct system responsibility:
- Setting the CLASSIFICATION problem on observations
- Providing visual indication to users
- Processing resolution codes with specific outcomes
- Enforcing resolution mechanism constraints
The resolution code scenarios (SETPOS, SETNEG, AMB-only) in REQ-RULES-AMB-003 were preserved as detailed acceptance criteria rather than consolidated, as each produces a distinct testable outcome critical for analytics correctness.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-amb/rule-amb-restructured.md - Original SRS:
output/srs/rules/rule-amb.md
Conversion Notes
This file was converted to the new SRS readable format on 2026-01-23:
- Added Statement section summarizing core behavior
- Added Rule Flowchart (Illustrative) with mermaid decision diagram
- Grouped acceptance criteria by concern with blank lines before bullets
- Moved tests to end with back-links to requirements
- Changed "Non-normative" to "Illustrative" per terminology guidelines
- Added Resolution Code Mapping table for clarity
- Added Inputs/Outputs tables for complex requirements
- Added Error Handling sections