Unexpected Fluorescence Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: UNEXPECTED_FL rule for validating well fluorescence readings against maximum thresholds Domain: RULES-UNEXPFL Precedence: Standard rule order (no explicit dependency)
Statement
The system shall validate well fluorescence readings against configured maximum thresholds and assign appropriate error codes when readings exceed thresholds or when configuration is missing.
The Unexpected FL rule identifies wells with abnormally high noise levels that could cause false signal detection, ensuring data quality in PCR analysis. When Rox normalization is enabled, the system calculates max FL after applying Rox divide to the readings.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-UNEXPFL-001 | Validates fluorescence against maximum thresholds | HIGH | Draft |
Key Integration Points: Well observations, Kit configuration (Maximum Fl thresholds), Rox normalization, Rules Engine
Rule Summary
| Property | Value |
|---|---|
| Name | UNEXPECTED_FL |
| Triggers | When evaluating observation fluorescence readings |
| Output | Sets UNEXPECTED_FL or MAXIMUM_FLUORESCENCE_MISSED error codes |
Rule Flowchart (Illustrative)
This diagram illustrates the decision logic for unexpected fluorescence validation. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| FL / Fl | Fluorescence - the emission of light by a substance that has absorbed light |
| Max Fl | Maximum Fluorescence - the highest fluorescence reading value for an observation |
| Maximum Fl Threshold | Configured upper limit for acceptable fluorescence readings per target |
| Rox | Reference dye used for normalization of fluorescence readings |
| Rox Divide | Normalization calculation that divides raw readings by Rox reference values |
Assumptions
- Kit configuration includes Maximum Fl threshold settings in the Mix Setup sheet
- Observations include fluorescence readings that can be evaluated for maximum values
- When Rox normalization is enabled for a target, Rox divide calculations are available
Requirements
Fluorescence Validation (REQ-RULES-UNEXPFL-001)
FR-UNEXPFL-001: Validate Well Fluorescence Against Maximum Thresholds
The system shall validate well fluorescence readings against configured maximum thresholds and assign appropriate error codes when readings exceed thresholds or when configuration is missing.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well observation fluorescence readings | PCR analysis |
| Input | Maximum Fl threshold per target | Kit configuration |
| Input | Rox normalization setting | Kit configuration |
| Output | Error code (UNEXPECTED_FL or MAXIMUM_FLUORESCENCE_MISSED) | Well record |
Acceptance Criteria
Configuration Check:
- When maximum_fl is configured for a target, the rule shall evaluate observations for that target
- When maximum_fl is not configured (null) in the observation, the well shall receive error code MAXIMUM_FLUORESCENCE_MISSED
- When the UNEXPECTED_FL rule is invoked but maximum_fl is null in the observation configuration, the system shall set error code MAXIMUM_FLUORESCENCE_MISSED on the well instead of skipping the rule (per BT-4154, supersedes original skip behavior)
Max Fl Calculation:
- The system shall calculate max Fl from the observation readings
- When Rox normalization is used, max Fl shall be calculated AFTER Rox divide is applied
Threshold Comparison:
- When calculated max Fl exceeds the configured Maximum Fl threshold, the well shall receive error code UNEXPECTED_FL
- When calculated max Fl does not exceed the configured Maximum Fl threshold, the rule shall return success (no error)
Error Handling
- Calculated max Fl exceeds threshold: Assign error code UNEXPECTED_FL to the well
- Maximum Fl threshold not configured: Assign error code MAXIMUM_FLUORESCENCE_MISSED to the well
Trace: Source: 3.0.0-Unexpected_fl Rule (Rows 1-4), 3.0.0-UNEXPECTED_FL rule - add MAXIMUM_FLUORESCENCE_MISSED error (Row 1) | Jira: BT-2486, BT-4154 | Tests: BT-2554, BT-4167 | Related: Kit Config brief (Reqs 2, 4, 10), Mixes and Targets - Set targets priority order
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
maximum_fl | Per-target | Maximum Fl threshold value configured in Mix Setup sheet per target | REQ-RULES-UNEXPFL-001 |
rox_normalization | Per-target | Whether Rox normalization is enabled for the target | REQ-RULES-UNEXPFL-001 |
UI Notes (Illustrative)
REQ-RULES-UNEXPFL-001 UI Specifications
Configuration Location:
- Maximum Fl threshold is configured in the Mix Setup sheet, Maximum Fl column
- Configuration file: "Mix and Targets" section in Configuration Excel File
Visualization:
- The in-app calibration window shows fluorescence data visualization
- Wells with unexpectedly high fluorescence appear as outliers above the expected maximum threshold
- Future enhancement: Users will be able to use the calibration view to set maximum fluorescence thresholds by identifying outlier data points
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/UnexpectedFlRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-UNEXPFL-001 | Validate Well Fluorescence Against Maximum Thresholds | Test | UnexpectedFlRule | BT-2554, BT-4167 | Draft |
Notes
- Rule code: UNEXPECTED_FL
- Error codes produced:
- UNEXPECTED_FL (well-level, for exceeded threshold)
- MAXIMUM_FLUORESCENCE_MISSED (configuration missing)
- Rox divide must be applied before max Fl calculation when Rox normalization is active
- The behavior change per BT-4154 (reporting error instead of skipping) aligns with Phase 2A initiative to verify rules have needed config info
- This rule helps identify wells with very high levels of noise that could cause false signal detection
Acceptance Tests
Test: REQ-RULES-UNEXPFL-001
Test: Maximum Fluorescence Exceeded
Given:
target:
name: Target A
maximum_fl: [configured threshold]
well:
observation:
target: Target A
max_fl: [value exceeding threshold]
When:
Rule evaluates observation on UNEXPECTED_FL
Then:
well:
error code: UNEXPECTED_FL
Test: Maximum Fluorescence Not Exceeded (Success)
Given:
target:
name: Target A
maximum_fl: [configured threshold]
well:
observation:
target: Target A
max_fl: [value not exceeding threshold]
When:
Rule evaluates observation on UNEXPECTED_FL
Then:
well:
error code: null (success)
Test: Missing Configuration Error (MAXIMUM_FLUORESCENCE_MISSED)
Given:
Well
Observation
maximum_fl = null
When:
Analyze observation on UNEXPECTED_FL
Then:
Well has MAXIMUM_FLUORESCENCE_MISSED error
Note: This test supersedes the original behavior where the rule would be skipped when maximum_fl was not configured. Per BT-4154, the system now reports an error instead of silently skipping.
Test: Rox Divide Applied Before Max Fl Calculation
Given:
target:
name: Target A
maximum_fl: [configured threshold]
rox_normalization: enabled
well:
observation:
target: Target A
raw_readings: [values]
When:
Rule evaluates observation on UNEXPECTED_FL
Then:
Max Fl is calculated AFTER Rox divide
Comparison uses normalized max Fl value
Validation Run Test:
- Using Viracor config sheet (for 2.13.0)
- Run from CST-33 should get an unexpected_fl error in well F3
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Rules Engine, Fluorescence Analysis |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion - N/A, single requirement)
- 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 (N/A - none)
- 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
This domain contains a single, focused requirement (REQ-RULES-UNEXPFL-001) that represents one distinct capability: validating fluorescence readings against thresholds. No requirement explosion pattern was detected.
Source Preservation:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-RULES-UNEXPFL-001 | 3.0.0-Unexpected_fl Rule (Rows 1-4) | Preserved as REQ-RULES-UNEXPFL-001 |
| Missing config handling | BT-4154 | Incorporated as AC in FR-UNEXPFL-001 |
Rationale: The source already represented a well-structured single capability. All acceptance criteria from the source were preserved to maintain test precision for analytics rules.
Reversibility: Source file: output/pilot/rules/rule-unexpected-fl/rule-unexpected-fl-restructured.md