Skip to main content
Version: 3.0.1

Analyzer

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Data processing and validation of imported run files Domain: ANALYZER

Statement​

The system shall support configurable validation of patient well data during run file import, allowing laboratories to control data quality enforcement rules.

This domain enables administrators to configure which special characters are permitted in accession identifiers during import. When allowed characters are configured, patient wells with accessions containing those characters pass validation; when no special characters are configured, only alphanumeric accessions are accepted. This provides flexibility for laboratories with varying data quality requirements.

Behavior Overview (Illustrative)​

This diagram illustrates the high-level accession validation behavior. It does not specify UI layout, styling, or interaction details.

Definitions​

TermDefinition
AccessionA unique identifier assigned to a patient sample for tracking purposes
Patient WellA well in a PCR plate that contains patient sample data (as opposed to control wells)
Validation ErrorA flagged condition indicating that imported data does not meet configured quality rules
LIMS StatusA status code assigned to a well by the Laboratory Information Management System (e.g., EXCLUDE, RPT, RXT)
EXCLUDE StatusA LIMS status indicating the well shall be removed from all analyzer rule evaluation

Functional Requirements​

Data Validation (REQ-ANALYZER-001)​

FR-ANALYZER-001 Configure Accession Validation Enforcement​

The system shall support configurable accession character validation during patient well import, allowing laboratories to control which special characters are permitted in accession identifiers.

Acceptance Criteria:

Validation Behavior:

  • When allowed characters are configured, the system shall accept accessions containing alphanumeric characters plus the configured special characters, and flag accession errors for characters not in the allowed set
  • When no allowed characters are configured (empty), the system shall accept only alphanumeric accessions and flag accession errors for any special characters

Scope:

  • The allowed characters setting shall apply to all patient wells during a single import operation
  • The allowed characters setting shall apply only to patient wells; control wells shall follow separate validation logic
  • Accession character validation shall not affect other validation rules (e.g., format, required fields)

Configuration:

  • The allowed characters configuration shall be controlled at the client level

Error Handling

  • Configuration setting not found or empty: The system shall default to alphanumeric-only validation (no special characters allowed)

Trace: Source: 3.0.0-Bypass Accession Validation (Row 1) | Epic: BT-5282 | Jira: BT-5290 | Tests: TC-ANALYZER-001, TC-ANALYZER-002

LIMS Status Filtering (REQ-ANALYZER-002)​

Version

REQ-ANALYZER-002 was added in v3.0.1.

FR-ANALYZER-002 Exclude Wells with EXCLUDE LIMS Status from Analysis​

The system shall exclude wells marked with LIMS status EXCLUDE from all analyzer rule evaluation, while allowing wells with RPT and RXT LIMS statuses to participate normally in analysis.

Acceptance Criteria:

Current Run Filtering:

  • Wells with lims_status = 'EXCLUDE' in the current run shall be removed from analysis before any rules execute
  • Wells with lims_status = 'RPT' or lims_status = 'RXT' in the current run shall not be filtered and shall participate in all rule evaluation

Cross-Run (Historical) Filtering:

  • When a rule queries previous-run wells and the matching historical well has lims_status = 'EXCLUDE', the rule shall treat it as "no valid match" and skip the comparison
  • Archive dependency tracking shall still record the EXCLUDE well as a dependency (cache before filter)
  • Wells with RPT or RXT status in previous runs shall participate normally in cross-run comparisons

Affected Rules:

  • The EXCLUDE filtering shall apply to all rules that use previous patient wells: WREP, Picqual, Picquant, Sbcheck, Rbact, AdjZika
  • Combined outcome rules shall continue to use the broader hasExclusiveLimsStatus() filter (EXCLUDE + RPT + RXT) as a pre-existing behavior

Trace: Source: excluding-wells-with-exclusive-lims-status.md (all sections) | Jira: TBD | Tests: TC-ANALYZER-003, TC-ANALYZER-004

Configuration Options​

OptionDefaultDescriptionAffects
allowed_characters_in_accessions[] (empty array)Array of special character patterns permitted in accession identifiers. When empty, only alphanumeric accessions are accepted. When populated, alphanumeric plus the listed characters are accepted.REQ-ANALYZER-001

Assumptions​

  • Users have appropriate role permissions to import run files
  • Client configuration settings are established before import operations
  • The system distinguishes between patient wells and control wells during import

[REVIEW REQUIRED: Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME.]

UI Notes (Illustrative)​

FR-ANALYZER-001 UI Specifications​

  • Configuration setting location: Client Configuration screen
  • Setting label: "Allowed characters in accessions"
  • Setting type: Multi-select (character patterns)

Implementation (Illustrative)​

ComponentTypePathRequirements
PatientValidatorValidatorcode/app/Analyzer/Validators/PatientValidator.phpREQ-ANALYZER-001
HasValidAccessionValidation Rulecode/app/Analyzer/Validators/Rules/HasValidAccession.phpREQ-ANALYZER-001
PatientWellClasscode/app/Analyzer/PatientWell.phpREQ-ANALYZER-001
WellAbstract Classcode/app/Analyzer/Well.phpREQ-ANALYZER-001
EloquentConfigurationRepositoryRepositorycode/app/Analyzer/EloquentConfigurationRepository.phpREQ-ANALYZER-001
AnalyzerClasscode/app/Analyzer/Analyzer.phpREQ-ANALYZER-002
Well (Analyzer)Classcode/app/Analyzer/Well.phpREQ-ANALYZER-002
Well (Eloquent)Modelcode/app/Well.phpREQ-ANALYZER-002
WellCollectionClasscode/app/Analyzer/WellCollection.phpREQ-ANALYZER-002
PecWellCollectionClasscode/app/Analyzer/PecWellCollection.phpREQ-ANALYZER-002
WrepRuleRulecode/app/Analyzer/Rules/WrepRule.phpREQ-ANALYZER-002
PicqualRuleRulecode/app/Analyzer/Rules/PicqualRule.phpREQ-ANALYZER-002
PicquantRuleRulecode/app/Analyzer/Rules/PicquantRule.phpREQ-ANALYZER-002
SbcheckRuleRulecode/app/Analyzer/Rules/SbcheckRule.phpREQ-ANALYZER-002
RbactRuleRulecode/app/Analyzer/Rules/RbactRule.phpREQ-ANALYZER-002
AdjZikaRuleRulecode/app/Analyzer/Rules/AdjZikaRule.phpREQ-ANALYZER-002

Key Implementation Details:

  • PatientValidator.php line 19: Accession validation rule applied to patient wells
  • HasValidAccession.php lines 24-41: Validates accession format against allowed characters
  • Validation controlled via client configuration allowed_characters_in_accessions setting
  • EloquentConfigurationRepository.php: Provides access to client configuration settings

Traceability Matrix​

RequirementTitleVerificationImplementationTest CasesStatus
REQ-ANALYZER-001Configure Accession Validation EnforcementTestPatientValidator.php, HasValidAccession.phpTC-ANALYZER-001, TC-ANALYZER-002Draft
REQ-ANALYZER-002Exclude Wells with EXCLUDE LIMS Status from AnalysisTestAnalyzer.php, Well.php, WellCollection.phpTC-ANALYZER-003, TC-ANALYZER-004Draft (v3.0.1)

Notes​

  • This requirement is related to the wildcard targets epic (BT-5282)
  • Configurable accession character validation provides flexibility for laboratories with varying data quality requirements
  • Wells imported with validation errors flagged can be reviewed and corrected through the normal error resolution workflow

Open Questions​

IDQuestionResolutionOwnerDate Raised
OQ-01What constitutes an "invalid accession"? Is this based on format, uniqueness, or external system lookup?Depends on file import setting. Label-based import: missing required tags. Metadata-based import: invalid characters.-Resolved
OQ-02When validation errors are flagged, can they be resolved post-import or must the well be re-imported?Via well edit options (post-import resolution supported)-Resolved

Acceptance Tests​

Test: TC-ANALYZER-001​

Back to requirement

Test: Allowed characters configured permits matching accessions

Given: A well with an accession containing special characters (e.g., "-", "_")
And: Client configuration "allowed_characters_in_accessions" includes those characters
When: The well is imported
Then: The well shall be imported without an accession error

Test: TC-ANALYZER-002​

Back to requirement

Test: Empty allowed characters rejects special character accessions

Given: A well with an accession containing special characters
And: Client configuration "allowed_characters_in_accessions" is empty
When: The well is imported
Then: The well shall be imported with an accession error flagged

Test: TC-ANALYZER-003​

Back to requirement

Test: EXCLUDE wells removed from current run analysis

Given: A run contains patient wells W1 (lims_status = 'EXCLUDE') and W2 (lims_status = null)
When: The run is analyzed
Then: W1 shall not participate in any rule evaluation
And: W2 shall participate normally in all rule evaluation

Test: RPT and RXT wells participate in analysis

Given: A run contains patient wells W1 (lims_status = 'RPT') and W2 (lims_status = 'RXT')
When: The run is analyzed
Then: W1 and W2 shall participate normally in all rule evaluation

Test: TC-ANALYZER-004​

Back to requirement

Test: EXCLUDE historical wells skipped in cross-run comparison

Given: Run A contains well W1 with lims_status = 'EXCLUDE'
And: Run B is analyzed with a rule that queries previous-run wells
And: W1 is the matching historical well for a well in Run B
When: The rule evaluates the cross-run comparison
Then: The rule shall treat W1 as "no valid match" and skip the comparison

Test: Archive dependency still records EXCLUDE well

Given: Run A contains well W1 with lims_status = 'EXCLUDE'
And: Run B is analyzed and W1 is encountered during dependency tracking
When: Run B analysis completes
Then: W1's ID shall appear in the relevant well's archive_dependent_well_ids
And: W1 shall still be excluded from rule evaluation (cache before filter)
Design DocumentRelevant Sections
SDD AlgorithmsRun Analysis, Data Validation and Analysis

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
  • All constraints folded into acceptance criteria
  • Traceability matrix is complete

Reviewer Notes​

Conversion Summary:

The source document contains a single requirement (REQ-ANALYZER-001). This conversion applies the new SRS readability format without consolidation.

Source RequirementCapabilityDisposition
REQ-ANALYZER-001Configurable accession character validationPreserved as FR-ANALYZER-001
REQ-ANALYZER-002Exclude EXCLUDE-status wells from analysisAdded in v3.0.1 as FR-ANALYZER-002

Enhancements Made:

  • Added Statement section for quick understanding
  • Added Mermaid flowchart illustrating validation decision logic
  • Grouped acceptance criteria by concern (Validation Behavior, Scope, Configuration)
  • Added blank lines before bullet lists for PDF rendering
  • Moved tests to end with back-links to requirement
  • Marked UI Notes and Implementation as (Illustrative)

v3.0.1 Changes​

REQ-ANALYZER-002​

Change: Added new requirement for EXCLUDE LIMS status well filtering Reason: v3.0.1 introduced the EXCLUDE status concept, requiring wells with this status to be removed from analysis while RPT/RXT wells continue to participate Version: v3.0.1 Date: 2026-03-05

Reversibility: Original file preserved at output/srs/analyzer.md