Analytics / Rule Execution

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Executing analysis rules on wells during run processing Domain: ANALYTICS

---

Statement

The system shall execute analysis rules on wells during run processing, applying configured rules in precedence order to determine well outcomes.

Rule execution is controlled by two independent mechanisms: error well handling (whether a rule processes wells with existing errors) and LIMS preventability (whether a LIMS outcome blocks subsequent rules). These mechanisms enable complex analysis pipelines including error recovery workflows where downstream rules can resolve upstream errors.

---

Behavior Overview (Illustrative)

This diagram illustrates the high-level behavior. It does not specify implementation details or processing order nuances.

---

Definitions

Term	Definition
Rule	A configured analysis operation that evaluates well data and may modify well state (error codes, LIMS status)
Precedence	A numeric value that determines rule execution order; lower values execute first
Error Well	A well that has an error status prior to rule execution
LIMS Outcome	A configured status code that represents a well's laboratory result (e.g., DETECTED, NOT_DETECTED)
Analyse Preventable	A LIMS configuration property that, when true, blocks subsequent rules from executing on wells with that LIMS outcome
Inherited Control Failure	An error outcome applied when a control well failure affects related sample wells

---

Functional Requirements

Error Well Processing (REQ-ANALYTICS-001)

FR-ANALYTICS-001 Execute Rules on Error Wells

The system shall execute analysis rules on error wells based on each rule's error well configuration.

Acceptance Criteria:

Rule Execution:

• Rules configured with allow_error_well = true shall execute on wells with existing errors
• Rules configured with allow_error_well = false shall skip wells with existing errors
• Rules shall execute in precedence order (lower precedence number first)

Outcome Handling:

• A rule that executes on an error well may remove the error and set a LIMS status
• The final well state shall reflect the cumulative effect of all applicable rules

Configuration:

• The allow_error_well property shall be a boolean on rule configuration
• Error recovery workflows shall be supported where downstream rules can resolve upstream errors

Trace: Source: 3.0.0-Analytics / Rule Execution (Row 1) | Epic: BT-3539 | Jira: BT-3520 | Tests: See scenarios

---

LIMS Preventability Control (REQ-ANALYTICS-002)

FR-ANALYTICS-002 Control Rule Execution Based on LIMS Preventability

The system shall control rule execution based on the LIMS outcome's preventability configuration.

Acceptance Criteria:

Configuration:

• LIMS configuration shall include a does_prevent_analyse property
• Preventable LIMS outcomes shall represent "final" statuses that are not modified by subsequent rules
• Non-preventable LIMS outcomes shall be subject to control validation and may be overridden

Execution Control:

• When does_prevent_analyse = true, wells with that LIMS outcome shall not be processed by subsequent rules
• When does_prevent_analyse = false, wells with that LIMS outcome shall continue through the rule chain
• Rules shall execute in configured relative order (e.g., WDCLS before COMBINED OUTCOME before WT)

Error Override:

• Subsequent rules may replace a non-preventable LIMS outcome with an error outcome when an inherited error condition is detected

Error Handling:

• Inherited control failure detected: The system shall replace the well's LIMS outcome with an error outcome indicating control failure

Trace: Source: 3.0.0-Running Rules - Analyse Non Preventable LIMS (Row 1) | Epic: BT-4000 | Jira: BT-4027 | Tests: See scenarios

---

Configuration Options

Option	Default	Description	Affects
allow_error_well	false	Whether a rule executes on wells with existing errors	REQ-ANALYTICS-001
does_prevent_analyse	true	Whether a LIMS outcome blocks subsequent rule execution	REQ-ANALYTICS-002

---

Assumptions

• Rules are configured with valid precedence values before run processing
• LIMS outcomes are configured with the does_prevent_analyse property
• Wells have a defined error state (present or absent) before rule execution begins
• At least one rule is configured for the mix/target combination being analyzed

---

UI Notes (Illustrative)

Rule execution is a backend processing capability managed by the RunAnalyseJob and Analyzer classes. Run analysis status is reflected in the run's overall status displayed in the run file list via RunFilesStatusModal.vue. No dedicated rule execution monitoring UI exists; users observe outcomes through well results and run status indicators.

---

Implementation (Illustrative)

Component	Type	Location	Requirements
Analyzer	Core Class	code/app/Analyzer/Analyzer.php	REQ-ANALYTICS-001, REQ-ANALYTICS-002
Well	Abstract Class	code/app/Analyzer/Well.php	REQ-ANALYTICS-001, REQ-ANALYTICS-002
Observation	Class	code/app/Analyzer/Observation.php	REQ-ANALYTICS-002
Rule	Model	code/app/Rule.php	REQ-ANALYTICS-001
LimsStatus	Model	code/app/LimsStatus.php	REQ-ANALYTICS-002
RunAnalyseJob	Job	code/app/Jobs/RunAnalyseJob.php	REQ-ANALYTICS-001, REQ-ANALYTICS-002

Key Implementation Details

REQ-ANALYTICS-001 (Error Well Execution):

• Rule.php line 149: is_allow_error_wells flag controls well filtering
• Rule.execute() method rejects wells with hasErrorWhichPreventAnalyse() unless flag is true
• Well.php lines 1085-1106: hasErrorWhichPreventAnalyse() and hasErrorWhichDoesNotPreventAnalyse() methods

REQ-ANALYTICS-002 (LIMS Preventability):

• LimsStatus.php line 40: does_prevent_analyse attribute
• Well.php lines 1280-1298: hasAnalysePreventableLimsStatus() method
• Observation.php lines 802-810: shouldSkipRule() checks LIMS preventability

---

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-ANALYTICS-001	Execute Rules on Error Wells	Test	Rule.php, Analyzer.php, Well.php	BT-3595	Draft
REQ-ANALYTICS-002	Control Rule Execution Based on LIMS Preventability	Test	LimsStatus.php, Observation.php, Well.php	BT-4043	Draft

---

Notes

• Error recovery workflows enable downstream rules to resolve upstream errors, supporting complex analysis pipelines
• Example of preventability: A "DETECTED" LIMS that is non-preventable can be overridden to "INHERITED_CONTROL_FAILURE" if a related control well fails
• Rule execution order is critical for deterministic outcomes; precedence values must be unique within a rule set

---

Open Questions

ID	Question	Source	Owner	Date Raised
-	No open questions at this time	-	-	-

---

Acceptance Tests

Test: REQ-ANALYTICS-001

↑ Back to requirement

Test: Error well processed by allow_error_well rule

Given:
  - Rule A configured with:
    - name: Rule A
    - precedence: 1
    - effect: set Error A to well
  - Rule B configured with:
    - name: Rule B
    - precedence: 2
    - is_allow_error_wells: true
    - effect: remove error from well and set LIMS A to well
  - Well configured with rule mapping: Rule A, Rule B

When: Well A is analyzed

Then:
  - well.lims_status = LIMS A
  - well.error_code = null

---

Test: REQ-ANALYTICS-002

↑ Back to requirement

Test: Preventable LIMS blocks subsequent rules

Given:
  - LIMS configured with:
    - code: DETECTED
    - does_prevent_analyse: true
  - Rules configured:
    - WDCLS (relative order: 1)
    - COMBINED OUTCOME (relative order: 2)
    - WT (relative order: 3)
  - Run with wells:
    - well A1: configured to have DETECTED lims
    - well A2: configured to have CLS_DISC_WELL error

When: Run is analyzed through rules

Then:
  - A1 well outcome = DETECTED
  - (LIMS outcome preserved, subsequent rules did not execute)

Test: Non-preventable LIMS allows subsequent rules

Given:
  - LIMS configured with:
    - code: DETECTED
    - does_prevent_analyse: false
  - Rules configured:
    - WDCLS (relative order: 1)
    - COMBINED OUTCOME (relative order: 2)
    - WT (relative order: 3)
  - Run with wells:
    - well A1: configured to have DETECTED lims
    - well A2: configured to have CLS_DISC_WELL error

When: Run is analyzed through rules

Then:
  - A1 well outcome = INHERITED_CONTROL_FAILURE
  - (LIMS outcome overridden by subsequent rule detecting control failure)

---

Related Design Documents

Design Document	Relevant Sections
SDD Algorithms	Running Rules Architecture, Rule Mapping Architecture
SDD Architecture	Amazon RDS with Amazon Aurora Serverless v2

---

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

No consolidation was performed for this domain. Both requirements represent distinct system capabilities:

Requirement	Capability	Disposition
REQ-ANALYTICS-001	Error well processing control	Preserved as FR-ANALYTICS-001
REQ-ANALYTICS-002	LIMS preventability control	Preserved as FR-ANALYTICS-002

Rationale: These are two independent control mechanisms in the rule engine. REQ-ANALYTICS-001 controls whether a rule executes based on well error state, while REQ-ANALYTICS-002 controls whether subsequent rules execute based on LIMS outcome configuration. Neither is a variant of the other.

Refinement Integration: Former refinements (RF-01, RF-02) for each requirement have been folded into acceptance criteria (AC-06, AC-07) with language transformed to "shall" statements.

Reversibility: Source file preserved at output/srs/analytics.md

Format Conversion Notes

This document was converted to the new SRS readability format on 2026-01-24:

• Added Statement section summarizing core behavior
• Added Mermaid flowchart illustrating rule execution pipeline
• Grouped acceptance criteria by concern (Rule Execution, Outcome Handling, Configuration, etc.)
• Moved tests to end with back-links to requirements
• Replaced "Non-normative" with "Illustrative" throughout
• Added blank lines after AC headers for PDF rendering
• Preserved all normative data (REQ-*, ACs, traceability, tests, error handling, config options)