DP44/docs/ai/Common/DTS.Common.Serialization/Control/Event/Module/Channel.md

---
source_files:
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/DataValues.cs
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/ReviewableAttribute.NotApplicableException.cs
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/Filter.cs
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/ChannelDefaultSaeJ211Filter.cs
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/CalculatedChannel.cs
  - Common/DTS.Common.Serialization/Control/Event/Module/Channel/SaeJ211Filter.cs
generated_at: "2026-04-17T15:34:47.007360+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "ba30fc370955c9dd"
---

# DTS.Slice.Control.Event.Module.Channel Documentation

## 1. Purpose

This module provides the channel-level data structures and filtering mechanisms for the DTS Slice Control Event system. It defines classes for storing channel data values (with optional memory-mapped file support for large datasets), implements SAE J211-compliant digital filters for signal processing, and provides a hierarchy of calculated channel types for derived data operations such as integration, differentiation, FFT analysis, and vector mathematics. The module exists to support data acquisition and analysis workflows within the larger DTS Slice framework.

---

## 2. Public Interface

### `Event.Module.Channel.DataValues`

A class representing a channel's data, inheriting from `Exceptional`.

**Constructors:**
- `DataValues()` — Initializes with memory-mapped file support enabled by default.
- `DataValues(bool useMemoryMappedFile)` — Initializes with explicit control over memory-mapped file usage.

**Properties:**
- `bool UseMemoryMappedFile { get; set; }` — Controls whether the class uses memory-mapped files instead of in-memory lists for data storage.

---

### `Event.Module.Channel.ReviewableAttribute.NotApplicableException`

An exception class for attempts to use a channel attribute that is not applicable to the associated channel. Inherits from `ApplicationException`.

**Constructors:**
- `NotApplicableException()`
- `NotApplicableException(string msg)`
- `NotApplicableException(string msg, System.Exception innerEx)`

---

### `Event.Module.Channel.Filter` (Abstract)

Abstract base class for channel filters. Implements `Exceptional` and `IFilter`.

**Abstract Properties:**
- `string Name { get; }` — Descriptive designation for the filter.
- `bool IsCfc { get; }` — Indicates whether the filter corresponds to a CFC (Channel Filter Class) value.
- `ChannelFilter Type { get; }` — The `ChannelFilter` designation for this filter.
- `double CutoffFrequencyHz { get; }` — The cutoff frequency in Hz.

**Abstract Methods:**
- `double[] Apply(Channel input, DataDisplayUnits displayUnits, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to a channel.
- `double[] Apply(double[] data, double sampleRate, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to raw data.
- `string ToBaseString()` — Returns the base name without decoration (contrast with `ToString()`).

---

### `Event.Module.Channel.SaeJ211Filter`

Concrete implementation of SAE J211-based filters. Inherits from `Filter`.

**Constructors:**
- `SaeJ211Filter(SaeJ211Filter originalFilter)` — Copy constructor.
- `SaeJ211Filter(ChannelFilter originalType)` — Initializes from a `ChannelFilter` enum value. Throws `Exception` if `ChannelFilter.AdHoc` is passed.
- `SaeJ211Filter(double cutoffFrequencyHz)` — Initializes an ad hoc filter with a specific cutoff frequency.

**Properties:**
- `override bool IsCfc { get; }` — Returns `true` if the filter is CFC-compliant (not `Unfiltered` and not `AdHoc`).
- `override ChannelFilter Type { get; }` — Returns the best-fitting `ChannelFilter` value.
- `char IsoDescription { get; }` — Returns the ISO description character.
- `override double CutoffFrequencyHz { get; }` — The cutoff frequency.
- `ChannelFilter OriginalType { get; }` — The original filter type specified at construction.
- `override string Name { get; }` — The filter name (e.g., "1000Hz" for ad hoc, or the CFC description).

**Methods:**
- `override double[] Apply(Channel channel, DataDisplayUnits displayUnits, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to channel data.
- `override double[] Apply(double[] data, double sampleRate, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to raw data.
- `override string ToString()` — Returns `Name`.
- `override string ToBaseString()` — Returns `Name`.
- `override bool Equals(object obj)` — Compares filters by name (case-insensitive).
- `override int GetHashCode()` — Returns hash based on lowercase name.
- `static Filter Parse(string serialization)` — Creates a filter from a string representation.

---

### `Event.Module.Channel.DefaultSaeJ211Filter`

A default wrapper for SAE J211 filters. Inherits from `SaeJ211Filter`.

**Constructors:**
- `DefaultSaeJ211Filter(SaeJ211Filter filter)` — Wraps an existing filter.
- `DefaultSaeJ211Filter(ChannelFilter filterType)` — Creates a filter from a `ChannelFilter` type.
- `DefaultSaeJ211Filter(double adHocFrequency)` — Creates an ad hoc filter with specified frequency.

**Properties:**
- `override string Name { get; }` — Returns `"Default (" + base.Name + ")"`.

**Methods:**
- `override string ToBaseString()` — Returns `base.Name`.
- `override string ToString()` — Returns `Name`.

---

### `Event.Module.Channel.CalculatedChannel` (Abstract)

Abstract base class for calculated/derived channels. Inherits from `Channel` and implements `IEngineeringUnitAware`.

**Nested Enum:**
- `Operation` — Values: `Integral`, `Derivative`, `HeadInjuryCriteria`, `FFT`, `ImportedCSV`, `Resultant`, `TSR`, `Scale`, `Offset`, `Sine`, `Cosine`.

**Nested Enum:**
- `XUnits` — Values: `msec`, `sec`, `Hz`, `samples`.

**Properties:**
- `Operation CalculationType { get; }` — The calculation type.
- `double[] X { get; }` — X-axis values.
- `double[] Y { get; }` — Y-axis values.
- `XUnits XAxis { get; }` — X-axis unit type.
- `string XUnitsString { get; }` — String representation of X units.
- `string EngineeringUnits { get; set; }` — Y-axis engineering units.
- `override bool SupportsADC { get; }` — Returns `false`.
- `override bool SupportsEU { get; }` — Returns `true`.
- `override bool SupportsmV { get; }` — Returns `false`.
- `override double ActualMaxRangeEu { get; }` — Returns `Y.Max()`.
- `override double ActualMinRangeEu { get; }` — Returns `Y.Min()`.
- `override double DataHalfRangeValueEu { get; }`, `DataMaxEu { get; }`, `DataMinEu { get; }`, `DataRangeEu { get; }` — Statistical properties of Y data.
- `override bool IsConfigured { get; set; }` — Always `true`; setter throws `NotSupportedException`.

**Constructor:**
- `CalculatedChannel(string name, XUnits xAxis, string yAxis, double[] xValues, double[] yValues, Operation calcType, int number, Module parentModule)`

**Methods that throw `NotSupportedException` or `NotImplementedException`:**
- `override void FromDtsSerializationTestModuleChannel(Serialization.Test.Module.Channel that)`
- `override void SetPropertyValuesFrom(DASLib.Service.DASChannel dasChannel)`
- `override void SetPropertyValuesFrom(DASLib.Service.DiagnosticsResult diagResults)`
- `override Serialization.Test.Module.Channel ToDtsSerializationTestModuleChannel(Serialization.Test.Module parentModule)`
- `override double ActualMaxRangeMv { get; }`
- `override double ActualMinRangeMv { get; }`
- `override double SensorCapacityEU { get; }`
- `override double DesiredRangeEU { get; }`
- `override List<double> GetUnfilteredDataMV()`

**Methods:**
- `override List<double> GetUnfilteredDataEu()` — Returns a copy of Y values.
- `override string ToString()` — Returns `ChannelDescriptionString` or `"N/A"`.

---

### Concrete Calculated Channel Types

All inherit from `CalculatedChannel` and have identical constructor signatures:

- `FFTCalculatedChannel` — Additional property: `double PeakFrequency { get; }`. Constructor includes extra `double peakFrequency` parameter.
- `IntegralCalculatedChannel`
- `DerivativeCalculatedChannel`
- `ScaleCalculatedChannel`
- `OffsetCalculatedChannel`
- `ResultantCalculatedChannel`
- `AdditiveVectorCalculatedChannel`
- `SineCalculatedChannel`
- `CosineCalculatedChannel`

---

## 3. Invariants

1. **Filter Type Consistency**: `SaeJ211Filter.Type` will never return `ChannelFilter.AdHoc` if the cutoff frequency exactly matches a CFC value; it will return the matching CFC type instead.

2. **CFC Compliance**: `SaeJ211Filter.IsCfc` returns `true` only when `Type` is neither `Unfiltered` nor `AdHoc`.

3. **Filter Equality**: Two `SaeJ211Filter` instances are considered equal if their `Name` properties match case-insensitively. Consequently, `GetHashCode()` is based on the lowercase name.

4. **Calculated Channel Data Immutability**: X and Y data arrays in `CalculatedChannel` are stored in `readonly List<double>` fields and exposed as copies via `ToArray()`.

5. **Calculated Channel Capabilities**: All `CalculatedChannel` derivatives have `SupportsADC = false`, `SupportsEU = true`, and `SupportsmV = false`.

6. **Parse Round-Trip**: `SaeJ211Filter.Parse()` can parse filter names produced by `ToString()`; unrecognized strings return an `Unfiltered` filter.

---

## 4. Dependencies

### This module depends on:
- `DTS.Common.Utilities` — Provides `Exceptional` base class, `Exception`, `Property<T>`, `APILogger`.
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — Provides `Property<T>`.
- `DTS.Common.Utilities.SaeJ211` — Provides `FilterUtility`, `CfcValueAttributeCoder`, `DescriptionAttributeCoder<T>`, `IsoDescriptionAttributeCoder`.
- `DTS.Common.Utilities.Logging` — Provides `APILogger`.
- `DTS.Common.DAS.Concepts.DAS.Channel` — Provides `ChannelFilter`, `IFilter`, `IEngineeringUnitAware`.
- `DTS.Slice.Control.DAS.Channel` — Referenced in `Filter.cs`.
- `DASLib.Service` — Provides `DASChannel`, `DiagnosticsResult` (used in `CalculatedChannel`).
- `System` namespaces — Standard .NET types.

### What depends on this module:
- Cannot be fully determined from source alone, but the partial class structure (`Event.Module.Channel`) indicates this is part of a larger `DTS.Slice.Control` namespace hierarchy.

---

## 5. Gotchas

1. **Empty Memory-Mapped File Implementation**: In `DataValues.DataValues(bool useMemoryMappedFile)`, the `if (UseMemoryMappedFile)` block is empty. The feature appears to be a stub or incomplete implementation.

2. **Legacy TDC Filter Adjustment**: The `Apply` methods on filters accept a `bool bUseLegacyTDCSoftwareFilterAdjustment` parameter (referenced as "8747" in comments) that adjusts filtered data by one sample to match legacy TDC behavior. This may produce unexpected results if not understood.

3. **NotSupportedException on CalculatedChannel**: Many methods on `CalculatedChannel` throw `NotSupportedException` or `NotImplementedException`. These include serialization methods, mV-related properties, and some range properties. Callers must handle these exceptions.

4. **AdHoc Filter Construction Restriction**: `SaeJ211Filter(ChannelFilter originalType)` throws an `Exception` if passed `ChannelFilter.AdHoc`. Use the `SaeJ211Filter(double cutoffFrequencyHz)` constructor instead.

5. **Large Data Handling in Filter.Apply**: When filtering ADC data, the method checks for `ILargeDataAware.IsDataArraySized` and throws `DataTooBigForArrayException` if data is too large. This is a runtime consideration for large datasets.

6. **Commented-Out Code**: Significant blocks of code are commented out in `CalculatedChannel.cs`, including the entire `HICCalculatedChannel` class and `InitializeReviewableAttributes` implementations. This suggests incomplete features or tech debt.

7. **Filter Name Ambiguity**: `DefaultSaeJ211Filter.Name` returns `"Default (" + base.Name + ")"`, while `ToBaseString()` returns just `base.Name`. The `ToString()` returns the decorated name. Use `ToBaseString()` when the undecorated name is needed.