Managing Quantities Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: RQUANTASQUAL rule for placeholder substitution in LIMS export messages Domain: RULES-QUANTITIES Precedence: After standard curve processing, during LIMS export
Statement
The system shall support configurable placeholders for quantity values in LIMS export configuration, enabling dynamic content substitution at export time.
This rule enables laboratories to report actual quantity values and limit-of-quantification (LOQ) thresholds to patients, rather than simple Detected/Not Detected results. Placeholders in message templates are resolved against well data, with lab-specific rounding rules applied before substitution.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-QUANTITIES-001 | Substitutes {LOQ} and {QUANT} placeholders in LIMS export messages | HIGH | Draft |
Key Integration Points: LIMS Export Module, Standard Curve Properties, Group Configuration (LOQ), Lab Configuration (rounding)
Rule Summary
| Property | Value |
|---|---|
| Name | RQUANTASQUAL |
| Triggers | When processing LIMS export message templates |
| Output | Message with placeholders replaced by quantity values |
Rule Flowchart (Illustrative)
This diagram illustrates the placeholder substitution logic. Rounding behavior (e.g., Viracor: nearest 100) is lab-specific configuration.
Definitions
| Term | Definition |
|---|---|
| LOQ | Limit of Quantification - the lowest concentration that can be reliably quantified for a given assay group |
| QUANT | Quantification - the calculated quantity value from PCR analysis after applying rounding rules |
| Placeholder | A token in the format {TOKEN} that is replaced with dynamic content during LIMS export |
| RQUANTASQUAL | Rule identifier for Managing Quantities configuration |
| RQUANT | Rounded Quantity - quantity value after applying lab-specific rounding rules |
Assumptions
- Users have appropriate permissions to configure LIMS export messages
- Quantitative assays produce calculated quantity values through standard curve analysis
- LOQ values are configured for each quantitative assay group
- Lab-specific rounding rules are defined in the lab configuration
Requirements
Placeholder Substitution (REQ-RULES-QUANTITIES-001)
FR-QUANTITIES-001: Support Quantity Placeholders in LIMS Export Configuration
The system shall support configurable placeholders for quantity values in LIMS export configuration, enabling dynamic content substitution at export time.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Message template (may contain placeholders) | LIMS export configuration |
| Input | Well quantity value | Standard curve analysis |
| Input | Group LOQ value | Group configuration |
| Input | Rounding rules | Lab configuration |
| Output | Processed message with substituted values | LIMS export |
Acceptance Criteria
Placeholder Substitution:
- The
{LOQ}placeholder shall be substituted with the applicable group limit (LOQ value from database or configuration) - The
{QUANT}placeholder shall be substituted with the well's reported quantity value - Users shall be able to include placeholder tokens in LIMS export configuration text
- Message templates with multiple placeholders shall have all placeholders substituted
- Placeholder syntax shall match the pattern
{[A-Z]+}
Template Pass-through:
- Message templates without placeholders shall pass through unchanged
Rounding:
- The reported quantity shall reflect any applicable rounding rules defined in lab configuration
- Rounding shall be applied before placeholder substitution (e.g., Viracor: 1040 rounds to 1000)
Data Validation:
- Quantity values shall be non-negative numeric values
- LOQ configuration shall exist for each quantitative assay group
Error Handling
- Unknown placeholder in template: pass the unknown placeholder through unchanged and log a warning
- LOQ not configured for group: use a default value or skip substitution
- Quantity is null or invalid: use placeholder "N/A" or skip substitution
- Rounding rules not configured: use the raw quantity value without rounding
Trace: Source: 3.0.0-Managing quantities (Rows 1, 2, 3) | Jira: BT-752 | Tests: TC-RQUANTASQUAL-001 to 005 | Related: RQUANT (Rounding Rules)
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
rounding_rules | lab-specific | Lab-specific rounding behavior (e.g., nearest 10, nearest 100, significant figures) | REQ-RULES-QUANTITIES-001 |
unknown_placeholder_behavior | pass_through | Behavior for unrecognized placeholders (pass_through or error) | REQ-RULES-QUANTITIES-001 |
null_quantity_display | N/A | Display value when quantity is null or invalid | REQ-RULES-QUANTITIES-001 |
UI Notes (Illustrative)
REQ-RULES-QUANTITIES-001 UI Specifications
Configuration Table Layout:
The message configuration interface displays a table with the following columns:
- Message: The message text (may contain placeholders)
- Code: Internal code for the message type (e.g., DETECTED_QUANT, DETECTED_LOQ)
- Type: Message classification (Information, Warning, Exclude)
Example Configuration Rows:
| Message | Code | Type |
|---|---|---|
| Detected | DETECTED | Information |
| Detected:<{LOQ} | DETECTED_LOQ | Information |
| Detected: {Quant} | DETECTED_QUANT | Information |
| Not detected | NOT DETECTED | Information |
| Inhibited positive | INHP | Warning |
| Inhibited | INHN | Warning |
| Re-extracted | RXT | Warning |
| Re-amplify | RPT | Warning |
| Well excluded | EXCLUDE | Exclude |
Message Type Assignment:
| Condition | Message Template | Code |
|---|---|---|
| Quantity detected, above LOQ | Detected: {Quant} | DETECTED_QUANT |
| Quantity detected, below LOQ | Detected:<{LOQ} | DETECTED_LOQ |
| Quantity not detected | Not detected | NOT DETECTED |
Implementation (Illustrative)
| Component | Location |
|---|---|
| QuantityWeightRule | Analyzer/Rules/QuantityWeightRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-QUANTITIES-001 | Support Quantity Placeholders in LIMS Export Configuration | Test | QuantityWeightRule | TC-RQUANTASQUAL-001 to 005 | Draft |
Notes
- Rounding rules are lab-specific and defined outside the scope of this rule
- Example rounding behaviors:
- Viracor: Round to nearest 100 (1040 becomes 1000, 1050 becomes 1100)
- Generic: No rounding (raw value used)
- This rule enables quantity reporting to meet patient reporting needs beyond simple Detected/Not Detected outcomes
- The placeholder system provides flexibility for different message formats across result types
- Legacy systems may use static messages; this rule enables migration to dynamic content
Open Questions
None identified.
Acceptance Tests
Test: REQ-RULES-QUANTITIES-001
Test TC-RQUANTASQUAL-001: LOQ Placeholder Substitution
Given: A message template containing {LOQ} placeholder
And: The group LOQ is configured as 100
When: The system processes the template "Detected:<{LOQ}"
Then: The system shall produce output "Detected:<100"
Test TC-RQUANTASQUAL-002: QUANT Placeholder Substitution
Given: A message template containing {QUANT} placeholder
And: The well quantity is 5000
And: No rounding rules are configured
When: The system processes the template "Detected: {QUANT}"
Then: The system shall produce output "Detected: 5000"
Test TC-RQUANTASQUAL-003: QUANT with Rounding (Viracor Example)
Given: A message template containing {QUANT} placeholder
And: The raw well quantity is 1040
And: Viracor rounding rules are configured (round to nearest 100)
When: The system processes the template "Report {QUANT}"
Then: The system shall produce output "Report 1000"
Test TC-RQUANTASQUAL-004: Multiple Placeholders
Given: A message template containing both {QUANT} and {LOQ} placeholders
And: The well quantity is 500
And: The group LOQ is 100
When: The system processes the template "Result: {QUANT} (LOQ: {LOQ})"
Then: The system shall produce output "Result: 500 (LOQ: 100)"
Test TC-RQUANTASQUAL-005: No Placeholders
Given: A static message template without placeholders
And: The well quantity is 500
When: The system processes the template "Detected"
Then: The system shall produce output "Detected" unchanged
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Placeholder Substitution |
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 do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
Source Analysis: REQ-RULES-QUANTITIES-001
The source material contained a single well-defined requirement with clear acceptance criteria. No consolidation was necessary as this represents a single cohesive capability.
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-RULES-QUANTITIES-001 | 3.0.0-Managing quantities (Rows 1, 2, 3) | Preserved as REQ-RULES-QUANTITIES-001 |
Rationale: Single requirement covers the complete placeholder substitution capability. Acceptance criteria from source preserved and enhanced with additional test conditions derived from the SDD test scenarios.
SDD Integration: Test scenarios from the SDD (RQUANTASQUAL-001 through RQUANTASQUAL-005) were incorporated as acceptance tests to ensure comprehensive coverage.
Reversibility: To review original structure, reference:
- Source:
output/pilot/rules/rule-managing-quantities/rule-managing-quantities-restructured.md - SDD:
output/pilot/rules/rule-managing-quantities/sdd/rule-managing-quantities-design.md - Confluence: 3.0.0-Managing quantities