init

enriched-qwen3-coder-next/Common/DTS.Common.SerializationPlus/Control/Event/Module/Channel.md

@@ -0,0 +1,130 @@
+---
+source_files:
+  - Common/DTS.Common.SerializationPlus/Control/Event/Module/Channel/ReviewableAttribute.NotApplicableException.cs
+  - Common/DTS.Common.SerializationPlus/Control/Event/Module/Channel/DataValues.cs
+  - Common/DTS.Common.SerializationPlus/Control/Event/Module/Channel/CalculatedChannel.cs
+generated_at: "2026-04-16T03:31:25.911180+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "680d00c25a548384"
+---
+
+# Channel
+
+## Documentation: `DTS.Slice.Control` Channel Subsystem — Calculated Channels and Related Types
+
+---
+
+### 1. Purpose
+
+This module provides core infrastructure for modeling *calculated* channels within the DTS control/event data model. It defines abstract and concrete channel types that represent derived time-series data (e.g., integrals, derivatives, FFTs, scaled/offset signals), along with supporting infrastructure such as `DataValues` (for internal data storage, optionally using memory-mapped files) and `NotApplicableException` (for enforcing attribute-applicability constraints). The calculated channel hierarchy supports engineering unit (EU) reporting, configurable X-axis units, and integration with review workflows via extensible `ReviewableAttribute` mechanisms—though the latter is partially commented out in the current source.
+
+---
+
+### 2. Public Interface
+
+#### `Event.Module.Channel.DataValues`
+- **`DataValues()`**  
+  Initializes an instance using in-memory storage (i.e., `UseMemoryMappedFile = false`).
+- **`DataValues(bool useMemoryMappedFile)`**  
+  Initializes an instance, optionally enabling memory-mapped file storage for large datasets.
+- **`UseMemoryMappedFile` (property, `bool`)**  
+  Gets/sets whether the instance uses memory-mapped files instead of in-memory lists. Defaults to `false`.
+
+#### `Event.Module.Channel.CalculatedChannel` *(abstract)*
+- **`Operation` enum**  
+  Defines supported calculation types: `Integral`, `Derivative`, `HeadInjuryCriteria`, `FFT`, `ImportedCSV`, `Resultant`, `TSR`, `Scale`, `Offset`, `Sine`, `Cosine`.
+- **`CalculationType` (property, `Operation`)**  
+  Immutable operation performed by this channel.
+- **`X`, `Y` (properties, `double[]`)**  
+  Read-only arrays of X and Y data points.
+- **`XAxis` (property, `XUnits`)**  
+  X-axis unit type (`Hz`, `msec`, `sec`, `samples`).
+- **`XUnitsString` (property, `string`)**  
+  Human-readable unit string for the X-axis (e.g., `"Hz"`, `"ms"`).
+- **`EngineeringUnits` (property, `string`)**  
+  Gets/sets the Y-axis engineering unit label.
+- **`SupportsADC`, `SupportsEU`, `SupportsmV` (override properties, `bool`)**  
+  Indicate that this channel *does not* support raw ADC/mV values (`false`), but *does* support engineering units (`true`).
+- **`ActualMaxRangeEu`, `ActualMinRangeEu`, `DataHalfRangeValueEu`, `DataMaxEu`, `DataMinEu`, `DataRangeEu` (override properties, `double`)**  
+  Derived from the `Y` data array (e.g., min/max, range, half-range).
+- **`IsConfigured` (override property, `bool`)**  
+  Always returns `true`; setting throws `NotSupportedException`.
+- **`GetUnfilteredDataEu()` (override method, `List<double>`)**  
+  Returns a copy of the internal `_y` list (unfiltered EU data).
+- **`ToString()` (override method, `string`)**  
+  Returns `ChannelDescriptionString` if non-null/empty; otherwise `"N/A"`.
+- **Constructors**  
+  `CalculatedChannel(string name, XUnits xAxis, string yAxis, double[] xValues, double[] yValues, Operation calcType, int number, Module parentModule)`  
+  Initializes the channel with data, units, and metadata.
+
+#### `Event.Module.Channel.FFTCalculatedChannel`
+- **`PeakFrequency` (property, `double`)**  
+  Peak frequency value (computed during FFT processing).
+- **Constructor**  
+  `FFTCalculatedChannel(..., double peakFrequency)`  
+  Extends `CalculatedChannel` with peak frequency.
+
+#### `Event.Module.Channel.IntegralCalculatedChannel`, `DerivativeCalculatedChannel`, `ScaleCalculatedChannel`, `OffsetCalculatedChannel`, `ResultantCalculatedChannel`, `AdditiveVectorCalculatedChannel`, `SineCalculatedChannel`, `CosineCalculatedChannel`
+- **Constructors**  
+  All follow the same signature as `CalculatedChannel`, passing `calcType` to the base class.
+
+#### `Event.Module.Channel.ReviewableAttribute.NotApplicableException`
+- **`NotApplicableException()`**  
+  Default constructor.
+- **`NotApplicableException(string msg)`**  
+  Constructor with message.
+- **`NotApplicableException(string msg, Exception innerEx)`**  
+  Constructor with message and inner exception.
+
+> **Note**: Several methods in `CalculatedChannel` (e.g., `ToDtsSerializationTestModuleChannel`, `FromDtsSerializationTestModuleChannel`, `SetPropertyValuesFrom(DASChannel)`, `SetPropertyValuesFrom(IDiagnosticResult)`) throw `NotSupportedException` or `NotImplementedException`. Similarly, `ActualMaxRangeMv`, `ActualMinRangeMv`, `DataZeroLevelAdc`, `SensorCapacityEU`, `DesiredRangeEU`, and `GetUnfilteredDataMV()` are unimplemented.
+
+---
+
+### 3. Invariants
+
+- **`IsConfigured` is immutable**: Setting `IsConfigured` to any value throws `NotSupportedException`.
+- **`EngineeringUnits` is mutable but not validated**: No constraints on the `EngineeringUnits` string value.
+- **`X`/`Y` arrays are immutable after construction**: The underlying `_x`/`_y` lists are copied into the constructor; `X`/`Y` properties return arrays (not lists), preventing external mutation.
+- **`SupportsADC`/`SupportsmV` are fixed to `false`**: Calculated channels do not represent raw sensor data.
+- **`ActualMinRangeEu`/`ActualMaxRangeEu` assume non-empty `Y`**: If `Y` is empty, `.Min()`/`.Max()` will throw `InvalidOperationException` (not handled in source).
+- **`DataValues.UseMemoryMappedFile` is immutable after construction**: Though the property setter exists, the backing `Property<bool>` is initialized with `false` for `isReadOnly`, but the constructor does not enforce immutability post-initialization.
+
+---
+
+### 4. Dependencies
+
+- **Imports/Usings**:
+  - `DTS.Common.Utilities` and `DTS.Common.Utilities.DotNetProgrammingConstructs` (`DataValues` uses `Property<T>`).
+  - `DTS.Common.Interface.DASFactory.Diagnostics` (`CalculatedChannel` references `IDiagnosticResult`).
+  - `DTS.Common.SerializationPlus` (`CalculatedChannel` references serialization types like `Serialization.Test.Module.Channel`).
+  - `DTS.Slice.Control` (self-referential partial classes).
+- **External Types Referenced** (but not defined here):
+  - `DASLib.Service.DASChannel`
+  - `IDiagnosticResult`
+  - `Common.DAS.Concepts.DAS.Channel.IEngineeringUnitAware` (implemented interface)
+  - `Serialization.Test.Module.Channel`
+  - `ChannelFilter`, `DefaultSaeJ211Filter` (used in constructor)
+  - `Module`, `Event`, `ReviewableAttribute` (via partial class nesting)
+
+- **Depended upon by**:  
+  The `CalculatedChannel` hierarchy is part of the `Event.Module.Channel` namespace and likely consumed by higher-level event processing, serialization, or UI review components (e.g., `ReviewableAttribute` subclasses, though commented out).
+
+---
+
+### 5. Gotchas
+
+- **`DataValues` constructor silently swallows exceptions**: Any exception during construction (e.g., memory-mapped file initialization) is rethrown as a generic `Exception` with a fixed message, losing original exception details beyond the inner exception.
+- **`DataValues` does not expose data accessors**: The class inherits from `Exceptional` (not shown), but no public methods/properties to read/write data are visible here—suggesting data access is handled elsewhere (e.g., via `Channel` base class).
+- **`CalculatedChannel` methods throw `NotImplementedException`/`NotSupportedException`**: Many methods (e.g., `ToDtsSerializationTestModuleChannel`, `SetPropertyValuesFrom`, `GetUnfilteredDataMV`) are unimplemented. Calling them will cause runtime failures.
+- **`DataHalfRangeValueEu` uses arithmetic mean, not half-range**: Despite the name, it computes `0.5 * (min + max)` (i.e., midpoint), not half the range (`0.5 * (max - min)`).
+- **`XUnitsString` returns `"N/A"` for unknown `XUnits`**: This may cause UI/display issues if `"N/A"` is not handled gracefully.
+- **`DataValues` constructor parameter `useMemoryMappedFile` is unused in the body**: The `if (UseMemoryMappedFile)` block is empty—no actual initialization logic is present.
+- **`CalculatedChannel` constructors copy arrays**: `new List<double>(xValues)` and `new List<double>(yValues)` are used, but `X`/`Y` return arrays—ensuring immutability but potentially causing confusion if callers expect reference equality.
+- **`OffsetCalculatedChannel` has typo in constructor parameter**: `yVAlues` (capital `A`) instead of `yValues`.
+- **`HICCalculatedChannel` is commented out**: Though referenced in the source, the full implementation is commented out, making `HeadInjuryCriteria` support incomplete.
+- **`ReviewableAttribute` subclasses are commented out**: The `InitializeReviewableAttributes` override and associated attribute classes (e.g., `ReviewablePeakFrequencyAttribute`, `ReviewableHICAttribute`) are commented out—review functionality is not active in this build.
+
+--- 
+
+*Documentation generated from source files dated 2009. No runtime behavior beyond what is statically visible in the provided code is assumed.*