Version: 3.0.0

RQUANT Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: RQUANT rule for evaluating sample quantities and determining tiered reporting format Domain: RULES-RQUANT Precedence: Analytics Engine trigger

Statement

The system shall evaluate sample quantities using the RQUANT rule and determine the appropriate reporting format based on configured quantity group thresholds.

The rule implements a tiered decision tree algorithm with nine quantity groups (Groups 2-9), each specifying different formatting rules including rounding precision, scientific notation, and detection thresholds. When specimen-type functionality is enabled, the rule selects reporting configurations based on the sample's specimen type; otherwise, it uses the most recently modified configuration.

Quick Reference

ID	Core Behavior	Priority	Status
REQ-RULES-RQUANT-001	Evaluates quantities and applies tiered formatting (Groups 2-9)	HIGH	Draft
REQ-RULES-RQUANT-002	Sets RQUANT_LIMITS_MISSED error when configuration is missing	HIGH	Draft
REQ-RULES-RQUANT-003	Selects reporting configuration by specimen type	MEDIUM	Draft

Key Integration Points: Analytics Engine, Kit Configuration, LIMS Export, Reporting Configuration

Rule Summary

Property	Value
Name	`RQUANT`
Triggers	Analytics Engine quantity evaluation
Output	Formatted quantity value for LIMS export

Rule Flowchart (Illustrative)

This diagram illustrates the tiered quantity evaluation logic. It does not specify UI layout, styling, or interaction details.

Definitions

Term	Definition
Quantity Group	A configurable threshold tier (Groups 2-9) that determines formatting rules for quantity values
LOQ	Limit of Quantification - the lowest quantity that can be reliably measured and reported
LoD	Limit of Detection - the lowest quantity that can be detected (below LOQ)
Significant Figure	The number of meaningful digits used when rounding a quantity value
Specimen Type	The sample material type (e.g., Plasma, Serum) that may have different reporting configurations
Placeholder	A dynamic content marker (e.g., {QUANT}, {LOQ}) in LIMS export templates

Assumptions

Quantity groups are configured in the system before RQUANT rule execution
Reporting configurations are associated with target/mix combinations
LIMS export templates may contain placeholder syntax for dynamic value substitution
The system has access to specimen type information when sample type functionality is enabled

Requirements

Quantity Formatting (REQ-RULES-RQUANT-001)

FR-RQUANT-001: Evaluate and Format Sample Quantities

The system shall evaluate sample quantities using the RQUANT rule and determine the appropriate reporting format based on configured quantity group thresholds.

Inputs/Outputs

Direction	Data	Source/Target
Input	Sample quantity value	PCR analysis
Input	Quantity group thresholds	Kit configuration
Input	Reporting configuration	Target/Mix settings
Output	Formatted quantity string	LIMS export

Acceptance Criteria

Placeholder Processing:

The system shall support placeholder-based reporting configuration where users can define dynamic content using placeholders (e.g., "Report {QUANT}")
The {LOQ} placeholder shall be filled with the applicable group limit (LOQ value from database/config sheet)
The {QUANT} placeholder shall be filled with the well's reported quantity after applying rounding rules

Tiered Formatting Rules:

When quantity is less than or equal to Group 2 threshold, the result shall be reported as "Detected: <(Group 2 value)"
When quantity is less than or equal to Group 3 threshold (and above Group 2), the quantity shall be reported without rounding
When quantity is less than or equal to Group 4 threshold (and above Group 3), the quantity shall be reported as the Group 4 boundary value
When quantity is less than or equal to Group 5 threshold (and above Group 4), the quantity shall be reported with rounding to 1 significant figure
When quantity is less than or equal to Group 6 threshold (and above Group 5), the quantity shall be reported with rounding to 2 significant figures
When quantity is less than or equal to Group 7 threshold (and above Group 6), the quantity shall be reported with rounding to 3 significant figures
When quantity is less than or equal to Group 8 threshold (and above Group 7), the quantity shall be reported with rounding to 2 significant figures
When quantity is less than or equal to Group 9 threshold (and above Group 8), the quantity shall be reported in scientific notation with 2 significant figures
When quantity exceeds Group 9 threshold, the result shall be reported as ">{Group9 value}" in scientific notation format

Rounding Examples:

Group 5 rounding shall report 1040 as 1,000 (1 significant figure)
Group 6 rounding shall report 2123 as 2,100 (2 significant figures)
Group 7 rounding shall report 12927 as 12,900 (3 significant figures)
Group 8 rounding shall report 1565323 as 1,600,000 (2 significant figures)
Group 9 scientific notation shall report 9,982,000 as 1.00E+07 (2 significant figures)

Laboratory Configuration:

Basic rounding rules shall be lab-specific and configured separately per laboratory

Trace: Source: 3.0.0-RQUANT (Rows 1-19, Objectives, Context) | Jira: BT-674 | Tests: [Pending]

Error Handling (REQ-RULES-RQUANT-002)

FR-RQUANT-002: Handle Missing Configuration

The system shall set error code RQUANT_LIMITS_MISSED when the RQUANT rule cannot execute due to missing quantity group configuration.

Acceptance Criteria

Error Conditions:

When RQUANT analyzes an observation where target_id is null, the well shall receive the RQUANT_LIMITS_MISSED error code
When quantity groups are not configured for the applicable target, the well shall receive the RQUANT_LIMITS_MISSED error code
The error code shall clearly indicate that rule execution failed due to missing configuration

Error Handling

Condition	Response
target_id is null	The system shall assign RQUANT_LIMITS_MISSED error to the well
Quantity groups not configured	The system shall assign RQUANT_LIMITS_MISSED error to the well

Trace: Source: 3.0.0-RQUANT rule - add RQUANT_LIMITS_MISSED error (Row 1) | Jira: BT-4154 | Tests: BT-4167

Specimen-Based Configuration (REQ-RULES-RQUANT-003)

FR-RQUANT-003: Select Reporting Configuration by Specimen Type

The system shall select the appropriate reporting configuration for the RQUANT rule based on specimen type when sample type functionality is enabled.

Acceptance Criteria

Specimen Type Matching:

When sample type functionality is enabled, the RQUANT rule shall use the reporting configuration that matches the sample's specimen type
When sample type functionality is disabled, the RQUANT rule shall use the last modified reporting configuration regardless of specimen type
The rule mapping shall support specimen-specific rule assignments (e.g., Plasma samples use Plasma-specific RQUANT config, Serum samples use Serum-specific RQUANT config)

Multiple Configuration Handling:

When multiple reporting configurations exist for the same target/mix combination but different specimen types, the system shall select based on the sample's actual specimen type (when enabled)
The system shall support different LOQ values per specimen type (e.g., Plasma LOQ of 430, Serum LOQ of 228 for the same HEV target)
When sample type is disabled, the system shall select reporting configuration based on lastModifiedAt timestamp (most recent wins)

Trace: Source: 3.0.0-RQUANT Rule - Should use unique reporting based on specimen (Row 1) | Jira: BT-4205 | Epic: BT-4204 | Tests: [Pending]

Configuration Options

Option	Default	Description	Affects
`use_sample_type`	false	Enable specimen-type-based reporting configuration selection	REQ-RULES-RQUANT-003

UI Notes (Illustrative)

REQ-RULES-RQUANT-001 UI Specifications

See flow diagram (image167) for visual representation of the decision logic
Thousand separators (commas) should be used in formatted quantity display (e.g., "1,000" not "1000")

Implementation (Illustrative)

Component	Location
Rule Class	`Analyzer/Rules/RquantRule.php`
Error Setter	`Analyzer/Rules/Concerns/SetErrorToWell.php`
LIMS Status Setter	`Analyzer/Rules/Concerns/SetLimsStatusToWell.php`

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-RULES-RQUANT-001	Evaluate and Format Sample Quantities	Test	`RquantRule.handle()`, `RquantRule.roundFromSignificant()`	[Pending]	Draft
REQ-RULES-RQUANT-002	Handle Missing Configuration	Test	`RquantRule.handle()` (RQUANT_LIMITS_MISSED error)	BT-4167	Draft
REQ-RULES-RQUANT-003	Select Reporting Configuration by Specimen Type	Test	`RquantRule.handle()`, `ConfigurationRepository.getAllGroupReportingsForObservation()`	[Pending]	Draft

Notes

The RQUANT rule is specifically designed for quantified assays where traditional "Detected"/"Not Detected" paradigm is insufficient
Example use case: Viracor uses RQUANT - a target with quantity 1040 is reported as 1000, so {QUANT}=1000
The tiered approach allows laboratories to apply appropriate precision based on the magnitude of the quantity value
Epic BT-4148 covers Phase 2A verification that rules have needed well/config info to run

Acceptance Tests

Test: REQ-RULES-RQUANT-002

Back to requirement

Test: Verify RQUANT_LIMITS_MISSED error when target_id is null

Given:
  - Well exists
  - Observation exists
  - target_id = null

When:
  - Analyze observation on RQUANT rule

Then:
  - Well has RQUANT_LIMITS_MISSED error

Test: REQ-RULES-RQUANT-003

Back to requirement

Test: Verify specimen-based reporting when sample type is enabled

Given:
  Configurations:
    Reportings:
      - Plasma Configuration:
          Mix: HEV
          Target: HEV
          Specimen type: Plasma
          Quant or CT: Quant
          Group: 2 LoQ
          Upper Boundary: 430
          Last modified at: 2023-11-08 00:00:00
      - Serum Configuration:
          Mix: HEV
          Target: HEV
          Specimen type: Serum
          Quant or CT: Quant
          Group: 2 LoQ
          Upper Boundary: 228
          Last modified at: 2023-11-08 00:01:00

    Rule mappings:
      - Plasma Mapping:
          Mix: HEV
          Target: HEV
          Specimen type: Plasma
          Rule: RQUANT
      - Serum Mapping:
          Mix: HEV
          Target: HEV
          Specimen type: Serum
          Rule: RQUANT

    Runfile:
      - Well A1:
          Mix: HEV
          Target: HEV
          Specimen: Plasma
          Quantity: 113
      - Well A2:
          Mix: HEV
          Target: HEV
          Specimen: Serum
          Quantity: 113

When:
  - Use sample type is enabled
  - Import the runfile
  - Open imported run and observe A1 and A2 wells

Then:
  - A1 has "Detected:<430" outcome (uses Plasma config with Upper Boundary 430)
  - A2 has "Detected:<228" outcome (uses Serum config with Upper Boundary 228)

Test: Verify fallback to last modified reporting when sample type is disabled

Given:
  - Same configurations as above (Serum config has later modified timestamp)

When:
  - Use sample type is disabled
  - Import the runfile
  - Open imported run and observe A1 and A2 wells

Then:
  - A1 has "Detected:<228" outcome (uses last modified config - Serum)
  - A2 has "Detected:<228" outcome (uses last modified config - Serum)

Design Document	Relevant Sections
SDD Algorithms	RQUANT Algorithm

Appendix: Process Artifacts

Completion Checklist

Reviewer Notes

No Consolidation Required

The three requirements in this domain represent distinct capabilities:

Requirement	Capability	Rationale for Keeping Separate
REQ-RULES-RQUANT-001	Core quantity formatting algorithm	Primary rule behavior with 9+ threshold tiers
REQ-RULES-RQUANT-002	Error handling for missing configuration	Distinct error handling behavior
REQ-RULES-RQUANT-003	Specimen-type configuration selection	Distinct configuration selection behavior

Rationale: Per RULES domain guidance, conservative consolidation is applied. Each requirement represents a distinct, independently testable capability. The analytics precision requirements necessitate preserving all test criteria as explicit acceptance criteria.

Reversibility: Source file at output/pilot/rules/rule-rquant/rule-rquant-restructured.md

Statement​

Quick Reference​

Rule Summary​

Rule Flowchart (Illustrative)​

Definitions​

Assumptions​

Requirements​

Quantity Formatting (REQ-RULES-RQUANT-001)​

FR-RQUANT-001: Evaluate and Format Sample Quantities​

Error Handling (REQ-RULES-RQUANT-002)​

FR-RQUANT-002: Handle Missing Configuration​

Specimen-Based Configuration (REQ-RULES-RQUANT-003)​

FR-RQUANT-003: Select Reporting Configuration by Specimen Type​

Configuration Options​

UI Notes (Illustrative)​

REQ-RULES-RQUANT-001 UI Specifications​

Implementation (Illustrative)​

Traceability Matrix​

Notes​

Acceptance Tests​

Test: REQ-RULES-RQUANT-002​

Test: REQ-RULES-RQUANT-003​

Related Design Documents​

Appendix: Process Artifacts​

Completion Checklist​

Reviewer Notes​

No Consolidation Required​

Statement

Quick Reference

Rule Summary

Rule Flowchart (Illustrative)

Definitions

Assumptions

Requirements

Quantity Formatting (REQ-RULES-RQUANT-001)

FR-RQUANT-001: Evaluate and Format Sample Quantities

Error Handling (REQ-RULES-RQUANT-002)

FR-RQUANT-002: Handle Missing Configuration

Specimen-Based Configuration (REQ-RULES-RQUANT-003)

FR-RQUANT-003: Select Reporting Configuration by Specimen Type

Configuration Options

UI Notes (Illustrative)

REQ-RULES-RQUANT-001 UI Specifications

Implementation (Illustrative)

Traceability Matrix

Notes

Acceptance Tests

Test: REQ-RULES-RQUANT-002

Test: REQ-RULES-RQUANT-003

Related Design Documents

Appendix: Process Artifacts

Completion Checklist

Reviewer Notes

No Consolidation Required