Skip to main content
Version: Next

Minimum Fluorescence Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: MINIMUM_FL rule for validating well fluorescence readings against minimum thresholds Domain: RULES-MINFL Precedence: Standard rule pipeline position Also Known As: ROX Check (for Merck)

Statement​

The system shall validate well fluorescence readings against configured minimum thresholds for each target and apply appropriate error codes when readings fall below the threshold.

Control well failures propagate to target level for Assay Summary reporting. Users with appropriate permissions can skip this rule via resolution code application.

Quick Reference​

IDCore BehaviorPriorityStatus
REQ-RULES-MINFL-001Validates well fluorescence against configured minimum thresholdsHIGHDraft
REQ-RULES-MINFL-002Propagates control well failures to target level and Assay SummaryHIGHDraft
REQ-RULES-MINFL-003Allows users to skip rule via resolution code MIN_FLUORESCENCEMEDIUMDraft

Key Integration Points: Kit Configuration (thresholds), Rule Engine, Error Handling Framework, Assay Summary, Error Resolution Page

Rule Summary​

PropertyValue
NameMINIMUM_FL
TriggersWhen minimum_fluorescence threshold is configured for target
OutputSets LOW_FLUORESCENCE_WELL on well, LOW_FLUORESCENCE_TARGET on run target

Rule Flowchart (Illustrative)​

This diagram illustrates the core validation and propagation logic. It does not specify UI layout, styling, or interaction details.

Definitions​

TermDefinition
Minimum FluorescenceThe lowest acceptable fluorescence reading for a target, configured per target
Control WellA well with observation role type of Positive Control (PC), Negative Control (NC), or Quantification
Sample WellA well with observation role type of Sample, excluded from target-level error propagation
Resolution CodeA code applied to a well to skip specific rule evaluations
Assay SummaryA display showing aggregated results and errors for a run, including target-level errors

Assumptions​

  • Minimum fluorescence thresholds are configured at the target level prior to rule execution
  • Users applying resolution codes have appropriate permissions via the Error Resolution Page
  • The rule engine executes this rule as part of the standard analysis pipeline
  • Error codes are configured in the system and mapped to display messages

Requirements​

Fluorescence Validation (REQ-RULES-MINFL-001)​

FR-MINFL-001: Validate Well Fluorescence Against Minimum Thresholds​

The system shall validate well fluorescence readings against configured minimum thresholds for each target and apply appropriate error codes when readings fall below the threshold.

Acceptance Criteria

Threshold Comparison:

  • Compare the obtained minimum fluorescence for each observation against the configured minimum_fluorescence threshold for that target
  • When a reading is below the threshold (reading < threshold), set error code LOW_FLUORESCENCE_WELL on the well
  • When a reading equals the threshold (reading = threshold), do not apply an error
  • When a reading exceeds the threshold (reading > threshold), do not apply an error
  • Comparison shall be based on the minimum fluorescence reading from all observations for that target

Configuration Handling:

  • When minimum_fluorescence is not configured (null), the rule shall not apply and no error shall be generated
  • When the rule cannot execute due to missing configuration (minimum_fluorescence = null in observation config), set error code MINIMUM_FLUORESCENCE_MISSED on the well

Error Handling

  • Reading below threshold: Set error code LOW_FLUORESCENCE_WELL on the well
  • Configuration missing when rule executes: Set error code MINIMUM_FLUORESCENCE_MISSED on the well

Trace: Source: 3.0.0-Minimum Fluorescence Rule (Row 1), 3.0.0-MINIMUM_FL rule - add MINIMUM_FLUORESCENCE_MISSED error (Row 1) | Jira: BT-3551, BT-4154 | Tests: BT-4167, See scenarios

Error Propagation (REQ-RULES-MINFL-002)​

FR-MINFL-002: Propagate Control Well Fluorescence Failures to Target Level​

The system shall propagate fluorescence failures from control-type wells to the target level and indicate the failure in the Assay Summary.

Acceptance Criteria

Control Well Detection:

  • When a control well (role type PC, NC, or Quantification) has a low fluorescence reading, set error code LOW_FLUORESCENCE_WELL on the well
  • Propagate errors for wells with role types PC (Positive Control), NC (Negative Control), or Quantification
  • Wells with Sample role type shall not trigger target-level errors
  • Wells with Ignore role type shall not trigger target-level errors

Target-Level Propagation:

  • When a control well fails the minimum fluorescence check, the corresponding run target shall receive error code LOW_FLUORESCENCE_TARGET
  • When a control well fails, the Assay Summary shall display the configured error message for the affected target
  • Derive the Assay Summary message format from the error codes configuration for LOW_FLUORESCENCE_TARGET
  • Error propagation shall occur automatically upon rule evaluation

Trace: Source: 3.0.0-Minimum Fluorescence Rule (Row 2) | Jira: BT-3551 | Tests: See scenarios

Resolution (REQ-RULES-MINFL-003)​

FR-MINFL-003: Allow Users to Skip Minimum Fluorescence Rule via Resolution Code​

The system shall support skipping the minimum fluorescence rule when resolution code MIN_FLUORESCENCE is applied to a well.

Acceptance Criteria

Resolution Behavior:

  • When resolution code MIN_FLUORESCENCE is applied to a well, the well error code shall be null (no LOW_FLUORESCENCE_WELL)
  • When resolution code MIN_FLUORESCENCE is applied, the target error code shall be null (no LOW_FLUORESCENCE_TARGET)
  • Resolution shall apply to individual wells, not globally
  • Previously applied errors shall be cleared when resolution is applied

Trace: Source: 3.0.0-Minimum Fluorescence Rule (Row 3) | Jira: BT-3821 | Tests: See scenarios

Configuration Options​

OptionDefaultDescriptionAffects
minimum_fluorescencenull (per target)Threshold value for minimum acceptable fluorescence; when null, rule is disabled for that targetREQ-RULES-MINFL-001

UI Notes (Illustrative)​

FR-MINFL-002 UI Specifications​

Assay Summary Display:

  • When a control well fails, the Assay Summary shows the error message configured for LOW_FLUORESCENCE_TARGET
  • Format: {target name}: low fluorescence target
  • Example: Target A: low fluorescence target

FR-MINFL-003 UI Specifications​

  • Resolution code MIN_FLUORESCENCE is applied via the Error Resolution Page
  • Resolution applies to individual wells through the Error Resolution interface

Implementation (Illustrative)​

ComponentLocation
MinFluorescenceRuleAnalyzer/Rules/MinFluorescenceRule.php

Traceability Matrix​

RequirementTitleVerificationImplementationTest CasesStatus
REQ-RULES-MINFL-001Validate Well Fluorescence Against Minimum ThresholdsTestMinFluorescenceRuleBT-4167Draft
REQ-RULES-MINFL-002Propagate Control Well Fluorescence Failures to Target LevelTestMinFluorescenceRule[Pending]Draft
REQ-RULES-MINFL-003Allow Users to Skip Minimum Fluorescence Rule via Resolution CodeTestMinFluorescenceRule[Pending]Draft

Notes​

  • Error code LOW_FLUORESCENCE_WELL is set at well level
  • Error code LOW_FLUORESCENCE_TARGET is set at run target level
  • Error code MINIMUM_FLUORESCENCE_MISSED indicates rule cannot execute due to missing configuration
  • Resolution code MIN_FLUORESCENCE clears both well and target errors
  • This rule is also known as "ROX Check" for Merck assays
  • Related Epic: BT-3536 - Minimum fl rule (aka ROX check for Merck)
  • Related Epic: BT-4148 - Phase 2A: Verify Rules have needed well/config info to run

Acceptance Tests​

Test: REQ-RULES-MINFL-001​

Back to requirement

Test: Below Threshold - Error Applied

Given:
  target:
    name: Target A
    minimum fluorescence: 100,000
  well:
    observation:
      target: Target A
      readings: [ 99,999 ]
When:
  Rule evaluates well
Then:
  well:
    error code: LOW_FLUORESCENCE_WELL

Test: At Threshold - No Error

Given:
  target:
    name: Target A
    minimum fluorescence: 100,000
  well:
    observation:
      target: Target A
      readings: [ 100,000 ]
When:
  Rule evaluates well
Then:
  well:
    error code: null

Test: Above Threshold - No Error

Given:
  target:
    name: Target A
    minimum fluorescence: 100,000
  well:
    observation:
      target: Target A
      readings: [ 100,001 ]
When:
  Rule evaluates well
Then:
  well:
    error code: null

Test: No Threshold Configured - Rule Disabled

Given:
  target:
    name: Target A
    minimum fluorescence: null
  well:
    observation:
      target: Target A
      readings: [ 100,001 ]
When:
  Rule evaluates well
Then:
  well:
    error code: null

Test: Missing Configuration Error

Given:
  Well
  Observation
    minimum_fluorescence = null
When:
  Analyze observation on MINIMUM_FL
Then:
  Well has MINIMUM_FLUORESCENCE_MISSED error

Test: REQ-RULES-MINFL-002​

Back to requirement

Test: Control Well Failure Propagates to Target and Assay Summary

Given:
  error codes:
    error code:
      code: LOW_FLUORESCENCE_TARGET
      message: low fluorescence target
  target:
    name: Target A
    minimum fluorescence: 100,000
  well:
    observation:
      target: Target A
      role:
        type: < PC / NC / Quantification >
      readings: [ 99,999 ]
When:
  Rule evaluates well
Then:
  well:
    error code: LOW_FLUORESCENCE_WELL
  run target:
    error code: LOW_FLUORESCENCE_TARGET
  assay summary:
    target A: low fluorescence target

Test: REQ-RULES-MINFL-003​

Back to requirement

Test: Resolution Code Clears Errors

Given:
  error codes:
    error code:
      code: LOW_FLUORESCENCE_TARGET
      message: low fluorescence target
  target:
    name: Target A
    minimum fluorescence: 100,000
  well:
    observation:
      target: Target A
      role:
        type: < PC / NC / Quantification >
      readings: [ 99,999 ]
      resolution code: MIN_FLUORESCENCE
When:
  Rule evaluates well
Then:
  well:
    error code: <null>
  run target:
    error code: <null>
Design DocumentRelevant Sections
SDD AlgorithmsMinimum Fluorescence Algorithm

Appendix: Process Artifacts​

Completion Checklist​

  • All requirements are capability-level (describe behavior, not UI)
  • Requirement variants consolidated (no requirement explosion) - N/A, distinct capabilities preserved
  • 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, no open questions
  • 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 Required​

The three requirements in this domain (REQ-RULES-MINFL-001, REQ-RULES-MINFL-002, REQ-RULES-MINFL-003) represent distinct system capabilities:

RequirementCapabilityRationale for Preservation
REQ-RULES-MINFL-001Well-level fluorescence validationCore rule logic - validates readings against thresholds
REQ-RULES-MINFL-002Control failure propagation to targetDistinct propagation behavior affecting target and Assay Summary
REQ-RULES-MINFL-003Resolution code skip mechanismUser override capability with different scope and behavior

Rationale: These requirements cannot be consolidated as they describe different phases of rule execution:

  1. Validation (checking readings)
  2. Propagation (escalating control failures)
  3. Resolution (user override mechanism)

Merging would obscure the distinct behaviors and make testing less precise.

Reversibility: Original structure preserved. Reference:

  • Source: output/pilot/rules/rule-minimum-fluorescence/rule-minimum-fluorescence-restructured.md
  • Confluence: 3.0.0-Minimum Fluorescence Rule (Rows 1-3)