Quantity Weight Rule (TISSUE_WEIGHT)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Normalizes observation quantities by dividing by tissue weight during run analysis Domain: RULES-QTYWEIGHT
Statement
The system shall normalize observation quantities by dividing by twice the tissue weight value when executing the TISSUE_WEIGHT rule with valid inputs.
This rule adjusts raw quantity measurements to account for tissue mass variation, enabling standardized comparison across samples with different tissue weights. The rule includes guard clauses that skip execution when inputs are missing or zero, and generates an error when tissue weight contains non-numeric data.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-QTYWEIGHT-001 | Normalizes quantity using formula: quantity / (2 x tissue_weight) | HIGH | Draft |
| REQ-RULES-QTYWEIGHT-002 | Generates INVALID_TISSUE_WEIGHT error for non-numeric tissue weight | HIGH | Draft |
Key Integration Points: Well data (tissue weight source), Observation data (quantity values), Analytics Engine (rule execution)
Rule Summary
| Property | Value |
|---|---|
| Name | TISSUE_WEIGHT |
| Formula | final_quantity = initial_quantity / (2 x tissue_weight) |
| Skip Conditions | Tissue weight null/zero, quantity null |
| Error Conditions | Tissue weight contains non-numeric characters |
Rule Flowchart (Illustrative)
This diagram illustrates the guard clause logic and calculation flow. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Tissue Weight | A numeric property associated with a well representing the mass of tissue sample |
| Quantity | A numeric measurement value on an observation that may be normalized |
| Normalization | The process of adjusting quantity values to account for tissue mass variation |
| Guard Clause | A precondition that determines whether rule execution proceeds or is skipped |
Assumptions
- The rule executes within the context of run analysis
- Well and observation data structures are available to the rule
- Tissue weight values are expected to be numeric when present
- The multiplier of 2 in the normalization formula is a fixed domain-specific constant
Requirements
Quantity Calculation (REQ-RULES-QTYWEIGHT-001)
FR-QTYWEIGHT-001: Normalize Quantity Using Tissue Weight
The system shall adjust observation quantities by dividing by twice the tissue weight value when the TISSUE_WEIGHT rule executes with valid inputs.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Tissue weight value | Well record |
| Input | Observation quantity | Observation record |
| Output | Normalized quantity | Observation record |
Acceptance Criteria
Preconditions (Guard Clauses):
- When tissue weight is null, the rule shall be skipped and the observation quantity shall remain unchanged
- When tissue weight is zero, the rule shall be skipped and the observation quantity shall remain unchanged (prevents division by zero)
- When observation quantity is null, the rule shall be skipped and the quantity shall remain null
- The system shall skip rule execution silently if preconditions are not met; original values shall remain unchanged
Calculation:
- When both tissue weight and quantity are valid non-null non-zero values, the final quantity shall equal quantity divided by (2 x tissue_weight)
- The system shall calculate final quantity using the formula:
final_quantity = initial_quantity / (2 x tissue_weight) - The multiplier of 2 in the formula shall be fixed and not configurable
- The calculation shall be applied during rule analysis execution
Error Handling
- Tissue weight is null: skip rule execution and preserve original quantity
- Tissue weight is zero: skip rule execution and preserve original quantity (prevents division by zero)
- Quantity is null: skip rule execution and preserve null quantity
Trace: Source: 3.0.0-Quantity Weight Rule (Rows 1-3) | Jira: BT-3960 | Epic: BT-3950 | Tests: [BT-4008](#test-req-rules-qtyweight-001)
Error Handling (REQ-RULES-QTYWEIGHT-002)
FR-QTYWEIGHT-002: Generate Error for Invalid Tissue Weight
The system shall generate an INVALID_TISSUE_WEIGHT error when the tissue weight property contains a non-numeric value during TISSUE_WEIGHT rule execution.
Acceptance Criteria
Error Detection:
- When tissue weight is a non-numeric string (e.g., "ab"), the well shall receive the INVALID_TISSUE_WEIGHT error
- The system shall trigger the error when tissue_weight property contains non-numeric characters
Error Application:
- The system shall use error code
INVALID_TISSUE_WEIGHT - The system shall apply the error at the Well level (error is applied to the well, not the observation)
- The error shall be applied during rule analysis execution
- The error shall prevent the quantity calculation from proceeding with invalid data
Error Handling
- Tissue weight contains non-numeric characters: set INVALID_TISSUE_WEIGHT error on the well
Assumptions
- This error is distinct from the skip behavior in REQ-RULES-QTYWEIGHT-001; skip occurs for missing/zero values, error occurs for malformed values
Trace: Source: 3.0.0-TISSUE_WEIGHT rule - add INVALID_TISSUE_WEIGHT error (Row 1) | Jira: BT-4154 | Epic: BT-4148 | Tests: [BT-4167](#test-req-rules-qtyweight-002) | Related: REQ-RULES-QTYWEIGHT-001
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| None | - | The multiplier of 2 is fixed and not configurable | REQ-RULES-QTYWEIGHT-001 |
Note: No configurable parameters identified in source material. The multiplier of 2 is explicitly stated as not configurable.
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | No UI specifications identified for this rule. This is a backend calculation rule with no direct user interface. Confirm if any UI feedback or display requirements exist. | UI Detail | @tbd | 2026-01-22 |
Notes
- The factor of 2 in the formula is a domain-specific normalization constant related to the assay protocol
- The distinction between "skip" (silent) and "error" (explicit) handling reflects the difference between expected missing data versus unexpected malformed data:
- Missing tissue weight (null): Data not available; calculation cannot proceed - skip silently
- Zero tissue weight: Would cause division by zero; calculation undefined - skip silently
- Missing quantity (null): No value to transform - skip silently
- Non-numeric tissue weight: Data corruption; requires attention/correction - generate error
- Target Release: Viracor Phase 2A
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/QuantityWeightRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-QTYWEIGHT-001 | Normalize Quantity Using Tissue Weight | Test | QuantityWeightRule.handle() | BT-4008 | Draft |
| REQ-RULES-QTYWEIGHT-002 | Generate Error for Invalid Tissue Weight | Test | QuantityWeightRule.handle() | BT-4167 | Draft |
Acceptance Tests
Test: REQ-RULES-QTYWEIGHT-001
Test: Null tissue weight - skip rule
Given:
Well:
tissue_weight: <null>
observation:
quantity: 100
When:
Execute quantity weight rule
Then:
observation:
quantity: 100 (unchanged)
Test: Zero tissue weight - skip rule
Given:
Well:
tissue_weight: 0
observation:
quantity: 100
When:
Execute quantity weight rule
Then:
observation:
quantity: 100 (unchanged)
Test: Null quantity - skip rule
Given:
Well:
tissue_weight: 0.1
observation:
quantity: <null>
When:
Execute quantity weight rule
Then:
observation:
quantity: <null> (unchanged)
Test: Valid inputs - calculate adjusted quantity
Given:
Well:
tissue_weight: 0.1
observation:
quantity: 100
When:
Execute quantity weight rule
Then:
observation:
quantity: 500
(calculated as: 100 / (2 x 0.1) = 100 / 0.2 = 500)
Test: REQ-RULES-QTYWEIGHT-002
Test: Non-numeric tissue weight - error generated
Given:
Well:
tissueWeight: "ab"
Observation
When:
Analyze observation on TISSUE_WEIGHT
Then:
Well has INVALID_TISSUE_WEIGHT error
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Quantity Weight Normalization |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion - only 2 distinct requirements)
- 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 Required
This domain contains 2 requirements that represent distinct capabilities:
| Requirement | Capability | Disposition |
|---|---|---|
| REQ-RULES-QTYWEIGHT-001 | Core quantity calculation with tissue weight normalization | Preserved as-is |
| REQ-RULES-QTYWEIGHT-002 | Error handling for malformed tissue weight data | Preserved as-is |
Rationale: These requirements represent separate system behaviors - one for successful calculation and one for error detection. They should not be consolidated as they address different aspects of rule execution (happy path vs error path). This is consistent with the RULES domain guidance for conservative consolidation.
Reversibility: Source requirements preserved 1:1.
Source: output/pilot/rules/rule-quantity-weight/rule-quantity-weight-restructured.md