Downward Sigmoid Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: SIGMOID rule for validating amplification curve shapes against observation classifications Domain: RULES-DSIGMOID Precedence: Analytics rule (runs during well validation)
Statement
The system shall validate amplification curve shapes against observation classifications to detect discrepancies that may indicate classification errors or instrument issues.
The rule compares the direction of sigmoid curves (upward or downward) with the polarity of observation classifications (positive or negative). Positive observations should exhibit upward sigmoids; negative observations should exhibit downward sigmoids. Mismatches generate an INCORRECT_SIGMOID error and set a classification discrepancy flag for user review.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-DSIGMOID-001 | Flags positive observations with downward sigmoid curves | HIGH | Draft |
| REQ-RULES-DSIGMOID-002 | Flags negative observations with upward sigmoid curves | HIGH | Draft |
| REQ-RULES-DSIGMOID-003 | Excludes ambiguous/null observations from validation | HIGH | Draft |
| REQ-RULES-DSIGMOID-004 | Excludes wells with SIGMOID resolution or manual classification | HIGH | Draft |
| REQ-RULES-DSIGMOID-005 | Sets classification discrepancy flag on failed observations | HIGH | Draft |
Key Integration Points: Analytics Engine (curve analysis), Well Data Management (observation storage), Run View (flag display), Resolution System
Rule Summary
| Property | Value |
|---|---|
| Name | SIGMOID |
| Triggers | Well validation during analytics processing |
| Output | INCORRECT_SIGMOID error code, classification discrepancy flag |
Rule Flowchart (Illustrative)
This diagram illustrates the sigmoid validation decision logic. Middle index = floor(n/2), Penultimate index = n-2.
Definitions
| Term | Definition |
|---|---|
| Upward Sigmoid | A curve pattern where the middle value is less than the penultimate value, indicating signal increase |
| Downward Sigmoid | A curve pattern where the middle value is greater than the penultimate value, indicating signal decrease |
| Middle Index | For a readings array of length n: floor(n / 2) |
| Penultimate Index | For a readings array of length n: n - 2 |
| Classification Discrepancy Flag | A visual indicator in the run view that signals potential classification problems requiring user review |
Assumptions
- Wells contain observations with reading arrays of sufficient length (minimum 4 readings for sigmoid detection)
- Observations have a final classification value (Pos, Neg, Amb, or null)
- The run view supports display of classification discrepancy flags
- Resolution codes can be applied at the well level
- Manual classification indicates user has reviewed and confirmed the classification
- SIGMOID resolution code indicates the sigmoid issue has been previously acknowledged
- Ambiguous observations lack sufficient confidence for sigmoid pattern expectations
Requirements
Positive Observation Validation (REQ-RULES-DSIGMOID-001)
FR-DSIGMOID-001: Positive Observation Sigmoid Validation
The system shall flag wells with positive observations that do not exhibit upward sigmoid curves by generating an INCORRECT_SIGMOID error.
Acceptance Criteria
Scope:
- The rule shall apply to observations with final classification = Positive
Sigmoid Calculation:
- The system shall compare the middle reading value to the penultimate reading value
- The system shall calculate middle index as floor(n / 2) where n is the readings array length
- The system shall calculate penultimate index as n - 2 where n is the readings array length
Classification Logic:
- When middle value > penultimate value, the curve shall be classified as downward sigmoid (invalid for positive)
- When middle value <= penultimate value, the curve shall be classified as upward sigmoid (valid for positive)
- The system shall classify readings as "Not a Sigmoid" when middle and penultimate values are equal
Minimum Data:
- The system shall require a minimum of 4 readings for sigmoid detection; fewer readings shall result in "Not a Sigmoid" classification
Error Assignment:
- Wells with positive observations exhibiting downward sigmoid shall receive error code INCORRECT_SIGMOID
- Wells with positive observations exhibiting upward sigmoid shall not receive an error
Error Handling
- Positive observation with downward sigmoid: The system shall generate error code INCORRECT_SIGMOID
Trace: Source: 3.0.0-Downward Sigmoid Rule (Row 1) | Jira: BT-3995 | Tests: See scenarios | Related: REQ-RULES-DSIGMOID-005 (flag setting)
Negative Observation Validation (REQ-RULES-DSIGMOID-002)
FR-DSIGMOID-002: Negative Observation Sigmoid Validation
The system shall flag wells with negative observations that do not exhibit downward sigmoid curves by generating an INCORRECT_SIGMOID error.
Acceptance Criteria
Scope:
- The rule shall apply to observations with final classification = Negative
Sigmoid Calculation:
- The system shall compare the middle reading value to the penultimate reading value
- The system shall calculate middle index as floor(n / 2) where n is the readings array length
- The system shall calculate penultimate index as n - 2 where n is the readings array length
Classification Logic:
- When middle value < penultimate value, the curve shall be classified as upward sigmoid (invalid for negative)
- When middle value >= penultimate value, the curve shall be classified as downward sigmoid (valid for negative)
- The system shall classify readings as "Not a Sigmoid" when middle and penultimate values are equal
Minimum Data:
- The system shall require a minimum of 4 readings for sigmoid detection; fewer readings shall result in "Not a Sigmoid" classification
Error Assignment:
- Wells with negative observations exhibiting upward sigmoid shall receive error code INCORRECT_SIGMOID
- Wells with negative observations exhibiting downward sigmoid shall not receive an error
Error Handling
- Negative observation with upward sigmoid: The system shall generate error code INCORRECT_SIGMOID
Trace: Source: 3.0.0-Downward Sigmoid Rule (Row 2) | Jira: BT-3995 | Tests: See scenarios | Related: REQ-RULES-DSIGMOID-005 (flag setting)
Exclusion Conditions (REQ-RULES-DSIGMOID-003 & 004)
FR-DSIGMOID-003: Ambiguous Observation Exclusion
The system shall not apply sigmoid validation to observations that do not have a definitive positive or negative classification.
Acceptance Criteria
Excluded Classifications:
- The rule shall not be applied to observations with classification = null
- The rule shall not be applied to observations with classification = Amb (Ambiguous)
Behavior:
- Wells containing only ambiguous observations shall not receive sigmoid-related errors
- The exclusion shall occur before sigmoid curve analysis
Trace: Source: 3.0.0-Downward Sigmoid Rule (Row 3) | Jira: BT-3995 | Tests: See scenarios
FR-DSIGMOID-004: Resolution and Manual Override Exclusion
The system shall not apply sigmoid validation when a well has an existing sigmoid resolution or when an observation has a manual classification assigned.
Acceptance Criteria
Exclusion Conditions:
- The rule shall not be applied when well has resolution code = SIGMOID
- The rule shall not be applied when observation has manual classification assigned (any non-null value)
Independence:
- Both conditions shall independently prevent sigmoid rule execution
- Wells meeting either exclusion condition shall not receive sigmoid-related errors
Trace: Source: 3.0.0-Downward Sigmoid Rule (Row 4) | Jira: BT-3995 | Tests: See scenarios
Result Flagging (REQ-RULES-DSIGMOID-005)
FR-DSIGMOID-005: Classification Discrepancy Flag
The system shall set a classification discrepancy flag on observations that fail sigmoid validation.
Acceptance Criteria
Flag Setting:
- When sigmoid rule fails for an observation, the classification discrepancy flag shall be set
- The flag shall be visible on the target observation in the run view
User Interaction:
- The flag shall indicate potential classification problem requiring user attention
- Individual curve resolution shall be available for flagged observations
Trace: Source: 3.0.0-Sigmoid Rule - Add Discrepancy Flag (Row 1) | Jira: BT-4914 | Tests: BT-4916, See scenarios | Related: REQ-RULES-DSIGMOID-001, REQ-RULES-DSIGMOID-002
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| - | - | No configurable parameters identified in source material | - |
[REVIEW REQUIRED: Verify if thresholds or toggle options exist for this rule.]
UI Notes (Illustrative)
REQ-RULES-DSIGMOID-005 UI Specifications
- Classification discrepancy flag is displayed in the run view next to the affected observation
- Flag provides visual indication that user attention is required
- Individual curve resolution option is accessible from flagged observations
Implementation (Illustrative)
| Component | Location | Purpose |
|---|---|---|
| SigmoidRule | Analyzer/Rules/SigmoidRule.php | Primary sigmoid validation - positive/negative classification matching |
| NegativeSigmoidRule | Analyzer/Rules/NegativeSigmoidRule.php | Negative observation variant - upward sigmoid detection |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-DSIGMOID-001 | Positive Observation Sigmoid Validation | Test | SigmoidRule.php | [Pending] | Draft |
| REQ-RULES-DSIGMOID-002 | Negative Observation Sigmoid Validation | Test | SigmoidRule.php, NegativeSigmoidRule.php | [Pending] | Draft |
| REQ-RULES-DSIGMOID-003 | Ambiguous Observation Exclusion | Test | SigmoidRule.php | [Pending] | Draft |
| REQ-RULES-DSIGMOID-004 | Resolution and Manual Override Exclusion | Test | SigmoidRule.php | [Pending] | Draft |
| REQ-RULES-DSIGMOID-005 | Classification Discrepancy Flag | Test | SigmoidRule.php | BT-4916 | Draft |
Notes
- Jira Epic: BT-3990 - Downward sigmoid detector
- Regression test: BT-4916 - Verify the individual curve resolution for curves that fail invalid SIGMOID rule
- The programmatic rule name is
SIGMOID
Sigmoid Identifier Reference Data
The following table defines how reading patterns are classified. This is reference data used by the sigmoid detection algorithm:
| Readings | Compared Indexes (Middle, Penultimate) | Compared Values (Middle, Penultimate) | Result | Note |
|---|---|---|---|---|
| 1 | - | - | Not a Sigmoid | Not enough readings |
| 1,2 | - | - | Not a Sigmoid | Not enough readings |
| 1,2,3 | - | - | Not a Sigmoid | Not enough readings |
| 1,2,3,4 | 2,3 | 2,3 | Upward Sigmoid | |
| 1,2,2,4 | 2,3 | 2,2 | Not a Sigmoid | Middle and penultimate same value |
| 1,2,3,4,5 | 3,4 | 3,4 | Upward Sigmoid | |
| 1,2,3,4,5,6 | 3,5 | 3,5 | Upward Sigmoid | |
| 6,5,4,4,5,6 | 3,5 | 4,5 | Upward Sigmoid | Exceptional case |
| 5,4,3,4,5 | 3,4 | 3,4 | Upward Sigmoid | Exceptional case |
| 4,3,2,1 | 2,3 | 3,2 | Downward Sigmoid | |
| 5,4,3,2,1 | 3,4 | 3,2 | Downward Sigmoid | |
| 6,5,4,3,2,1 | 3,5 | 4,2 | Downward Sigmoid | |
| 1,2,3,3,2,1 | 3,5 | 3,2 | Downward Sigmoid | Exceptional case |
| 1,2,3,2,1 | 2,4 | 3,2 | Downward Sigmoid | Exceptional case |
Key observations:
- Some edge cases are marked "exceptional for now" and may require future refinement
Acceptance Tests
Test: REQ-RULES-DSIGMOID-001
Test: Positive observation with downward sigmoid generates error
Given: A well with observation final_cls=Pos
And: The observation readings form a downward sigmoid pattern
When: The downward sigmoid rule executes for the well
Then: The well shall receive error code INCORRECT_SIGMOID
Test: Positive observation with upward sigmoid passes validation
Given: A well with observation final_cls=Pos
And: The observation readings form an upward sigmoid pattern
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: REQ-RULES-DSIGMOID-002
Test: Negative observation with downward sigmoid passes validation
Given: A well with observation final_cls=Neg
And: The observation readings form a downward sigmoid pattern
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: Negative observation with upward sigmoid generates error
Given: A well with observation final_cls=Neg
And: The observation readings form an upward sigmoid pattern
When: The downward sigmoid rule executes for the well
Then: The well shall receive error code INCORRECT_SIGMOID
Test: REQ-RULES-DSIGMOID-003
Test: Null classification skips validation
Given: A well with observation cls=null
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: Ambiguous classification skips validation
Given: A well with observation cls=Amb
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: REQ-RULES-DSIGMOID-004
Test: Manual classification present skips validation
Given: A well with observation final_cls=Pos and manual_cls=Pos
And: The observation readings form a downward sigmoid pattern
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: Sigmoid resolution present skips validation
Given: A well with resolution_code=SIGMOID
And: An observation with cls=Pos and downward sigmoid readings
When: The downward sigmoid rule executes for the well
Then: The well shall not receive an error
Test: REQ-RULES-DSIGMOID-005
Test: Flag observation on sigmoid rule failure
Given: Well A1 with observation Target A
And: The sigmoid rule fails for observation Target A
When: The rule execution completes
Then: Target A observation classification shall be flagged in the run view
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Sigmoid Detection Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A, distinct behaviors preserved
- 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 validation requirements
- Open questions documented with owners assigned - No open questions identified
- 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
No Consolidation Applied
All five requirements in this domain represent genuinely distinct system capabilities:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-DSIGMOID-001 | Positive observation validation | Distinct validation logic for positive observations |
| REQ-RULES-DSIGMOID-002 | Negative observation validation | Distinct validation logic with opposite pass/fail conditions |
| REQ-RULES-DSIGMOID-003 | Ambiguous observation exclusion | Distinct exclusion condition (ambiguous/null) |
| REQ-RULES-DSIGMOID-004 | Resolution/manual override exclusion | Distinct exclusion condition (resolution/manual) |
| REQ-RULES-DSIGMOID-005 | Classification discrepancy flagging | Distinct flagging behavior |
Rationale: These requirements represent distinct validation rules with different trigger conditions and expected behaviors. REQ-001 and REQ-002 have opposite pass/fail logic based on classification polarity. Consolidating them would obscure the precise validation criteria required for analytics rules.
Test Scenarios: The source Given/When/Then test scenarios have been preserved as detailed acceptance criteria and moved to Acceptance Tests section with back-links.
Reversibility: Source file: output/pilot/rules/rule-downward-sigmoid/rule-downward-sigmoid-restructured.md