init
This commit is contained in:
@@ -0,0 +1,110 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/DasModuleAccessor.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/DasChannelAccessor.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/ChannelAccessor.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/ModuleChannelAccessor.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/DasModuleChannelAccessor.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/TestInformation.cs
|
||||
generated_at: "2026-04-16T03:30:58.722127+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "cdfba6906b172be2"
|
||||
---
|
||||
|
||||
# Event
|
||||
|
||||
## Documentation: DTS.Slice.Control.Event Accessor Types
|
||||
|
||||
---
|
||||
|
||||
### 1. **Purpose**
|
||||
|
||||
This module defines a set of specialized accessor types used to navigate hierarchical channel and module data associated with a DAS (Data Acquisition System) event. These types (`DasModuleAccessor`, `DasChannelAccessor`, `DasModuleChannelAccessor`, `ModuleChannelAccessor`, `ChannelAccessor`) are nested within the `Event` class and provide structured, type-safe access to event data indexed by DAS identifiers (e.g., DAS ID, module number, channel number). They are intended to be instantiated and populated during `Event` construction, enabling consumers to retrieve module and channel information using multi-level keys. The module also includes `TestInformation`, an internal helper class to encapsulate test metadata (ID and description) associated with the event.
|
||||
|
||||
---
|
||||
|
||||
### 2. **Public Interface**
|
||||
|
||||
All classes are nested within `DTS.Slice.Control.Event` and are declared `public`.
|
||||
|
||||
| Type | Inheritance | Constructor(s) | Key Type | Value Type | Description |
|
||||
|------|-------------|----------------|----------|------------|-------------|
|
||||
| `DasModuleAccessor` | `ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module>>` | `DasModuleAccessor()` | `Common.DAS.Concepts.DAS.Id` | `List<Module>` | Maps a DAS ID to a list of modules associated with that DAS in the event. |
|
||||
| `DasChannelAccessor` | `ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module.Channel>>` | `DasChannelAccessor()` | `Common.DAS.Concepts.DAS.Id` | `List<Module.Channel>` | Maps a DAS ID to a list of channels (across all modules) associated with that DAS in the event. |
|
||||
| `ChannelAccessor` | `ExceptionalDictionary<int, Module.Channel>` | `ChannelAccessor()` | `int` | `Module.Channel` | Maps a *module-local* channel number (as `int`) to a `Module.Channel` instance. Used internally by `ModuleChannelAccessor`. |
|
||||
| `ModuleChannelAccessor` | `ExceptionalDictionary<int, ChannelAccessor>` | `ModuleChannelAccessor()` | `int` | `ChannelAccessor` | Maps a *module ID* (as `int`) to a `ChannelAccessor`, which in turn maps channel numbers to channels. Used internally by `DasModuleChannelAccessor`. |
|
||||
| `DasModuleChannelAccessor` | `ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, ModuleChannelAccessor>` | `DasModuleChannelAccessor()` | `Common.DAS.Concepts.DAS.Id` | `ModuleChannelAccessor` | Maps a DAS ID to a `ModuleChannelAccessor`, enabling lookup of channels by DAS ID → module ID → channel number. |
|
||||
| `TestInformation` | `Exceptional` | `TestInformation()`<br>`TestInformation(string id, string description)` | — | — | Internal class holding test ID and description. Not intended for direct external use. |
|
||||
|
||||
> **Note**: All accessor types inherit from `ExceptionalDictionary<TKey, TValue>` (from `DTS.Common.Utilities`), implying they support exception-based error handling for missing keys (e.g., `KeyNotFoundException` or custom behavior defined in `ExceptionalDictionary`).
|
||||
|
||||
---
|
||||
|
||||
### 3. **Invariants**
|
||||
|
||||
- **Hierarchical Key Structure**:
|
||||
- `DasModuleChannelAccessor` → `ModuleChannelAccessor` → `ChannelAccessor` → `Module.Channel`
|
||||
provides a 3-level lookup: `DAS.Id` → `int (module ID)` → `int (channel number)` → `Module.Channel`.
|
||||
- `DasModuleAccessor` and `DasChannelAccessor` provide 2-level lookup: `DAS.Id` → `List<Module>` or `List<Module.Channel>`.
|
||||
|
||||
- **Null Handling**:
|
||||
- All `Property<T>` fields in `TestInformation` are initialized with `null` as the default value and `false` for `allowNull` (per constructor args), but the `Property<T>` wrapper likely enforces nullability semantics (exact behavior depends on `Property<T>` implementation, not visible here).
|
||||
|
||||
- **No Validation Logic Visible**:
|
||||
- No validation rules (e.g., range checks on channel/module IDs) are present in the source. Assumption: validation (if any) is handled upstream or by `ExceptionalDictionary`.
|
||||
|
||||
- **Partial Class**:
|
||||
- All types are declared `partial class Event`, meaning these accessors are part of a larger `Event` class defined elsewhere (likely in `DTS.Slice.Control.Event.cs`, referenced in comments).
|
||||
|
||||
---
|
||||
|
||||
### 4. **Dependencies**
|
||||
|
||||
#### Internal Dependencies (from source):
|
||||
- `DTS.Common.Utilities.ExceptionalDictionary<TKey, TValue>`
|
||||
Base class for all accessor types.
|
||||
- `DTS.Common.Utilities.Property<T>`
|
||||
Used in `TestInformation` for property encapsulation.
|
||||
- `DTS.Common.DASResource`
|
||||
Namespace imported by `TestInformation` (likely contains DAS resource types).
|
||||
- `DTS.Common.Utilities.DotNetProgrammingConstructs`
|
||||
Namespace imported by `TestInformation` (likely contains `Property<T>` or similar constructs).
|
||||
- `DTS.Slice.Control.Event`
|
||||
All types are nested inside `Event` (partial class).
|
||||
- `Common.DAS.Concepts.DAS.Id`
|
||||
Key type for DAS-level accessors (`DasModuleAccessor`, `DasChannelAccessor`, `DasModuleChannelAccessor`).
|
||||
|
||||
#### External Dependencies (inferred):
|
||||
- `DTS.Slice.Control.Module` and `Module.Channel`
|
||||
Referenced as value types in `DasModuleAccessor` and `DasChannelAccessor`. Must be defined elsewhere in the `DTS.Slice.Control` namespace.
|
||||
- `DTS.Common.Utilities`
|
||||
Core utilities library (contains `ExceptionalDictionary`, `Property<T>`, `Strings`).
|
||||
|
||||
#### What Depends on This Module?
|
||||
- Any code that consumes `Event` objects and needs to access channel/module data by DAS identifiers (e.g., event processing, analysis, or reporting modules).
|
||||
- Likely used in serialization/deserialization logic for `Event` (given `SerializationPlus` in namespace path).
|
||||
|
||||
---
|
||||
|
||||
### 5. **Gotchas**
|
||||
|
||||
- **Ambiguous Integer Keys**:
|
||||
- `ChannelAccessor` uses `int` as key for channel number, and `ModuleChannelAccessor` uses `int` as key for module ID. These are *not* strongly typed (e.g., no `DAS.Module.Id` or `DAS.Module.Channel.Id`), despite comments (`xxx change this int to ...`) suggesting future refactoring. This risks confusion or misuse if module/channel IDs overlap or are misinterpreted.
|
||||
|
||||
- **No Public Setters or Initialization Logic Visible**:
|
||||
- All accessor types have only parameterless constructors. It is unclear how they are populated (likely via internal logic in the parent `Event` class). Consumers must assume they are constructed and filled by the `Event` constructor.
|
||||
|
||||
- **`TestInformation` is `private sealed class`**:
|
||||
- Not exposed outside `Event`, so external code cannot instantiate or inspect it directly. Only accessible via `Event`’s public surface (not shown here).
|
||||
|
||||
- **Missing Context on `ExceptionalDictionary` Behavior**:
|
||||
- Since all types inherit from `ExceptionalDictionary`, behavior for missing keys (e.g., exceptions, defaults) depends on that base class. Without its source, exact runtime behavior is unknown.
|
||||
|
||||
- **No Documentation for `Module` or `Module.Channel` Types**:
|
||||
- The types `Module` and `Module.Channel` are used as value types but not defined here. Their structure and relationship to DAS IDs is critical for correct usage but not documented in this module.
|
||||
|
||||
- **Historical Quirk in Comments**:
|
||||
- All files include `// *** see DTS.Slice.Control.Event.cs ***`, indicating these are fragments of a larger file split for maintainability. This may complicate navigation for new developers.
|
||||
|
||||
None identified beyond the above.
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableDasSerialNumberAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableSampleRateAttribute.cs
|
||||
generated_at: "2026-04-16T03:31:05.140610+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "b7f5fb3360deccec"
|
||||
---
|
||||
|
||||
# Module
|
||||
|
||||
## Documentation: `ReviewableDasSerialNumberAttribute` and Related Classes
|
||||
|
||||
---
|
||||
|
||||
### 1. **Purpose**
|
||||
|
||||
This module provides concrete implementations of `ReviewableAttribute` for capturing and exposing read-only metadata about a `DTS.Slice.Control.Event.Module` instance—specifically, attributes that are relevant during event review or audit workflows. These attributes (e.g., DAS serial number, sample rate, hardware anti-aliasing filter rate, test description) are lazily evaluated via delegates and formatted for display in UI or reporting contexts. The classes exist to support structured, consistent, and type-safe access to module-level configuration and identity data during review processes.
|
||||
|
||||
---
|
||||
|
||||
### 2. **Public Interface**
|
||||
|
||||
All classes are `public` nested within `DTS.Slice.Control.Event.Module`.
|
||||
|
||||
#### `ReviewableDasSerialNumberAttribute`
|
||||
- **Signature**:
|
||||
```csharp
|
||||
public class ReviewableDasSerialNumberAttribute : ReviewableAttribute
|
||||
```
|
||||
- **Constructor**:
|
||||
```csharp
|
||||
public ReviewableDasSerialNumberAttribute(Event.Module module)
|
||||
```
|
||||
- **Behavior**:
|
||||
Initializes a reviewable attribute named `"DAS Serial Number"` whose value is lazily retrieved from `module.DasSerialNumber`. Uses the base class’s `DetermineValueString` delegate mechanism.
|
||||
|
||||
#### `ReviewableSampleRateAttribute`
|
||||
- **Signature**:
|
||||
```csharp
|
||||
public class ReviewableSampleRateAttribute : ReviewableAttribute
|
||||
```
|
||||
- **Constructor**:
|
||||
```csharp
|
||||
public ReviewableSampleRateAttribute(Event.Module module)
|
||||
```
|
||||
- **Behavior**:
|
||||
Initializes a reviewable attribute named `"Sample Rate"`. Value is `module.SampleRateHz.ToString("N")` (numeric formatting with thousand separators, no decimal places implied by `"N"` default).
|
||||
|
||||
#### `ReviewableTestDescriptionAttribute`
|
||||
- **Signature**:
|
||||
```csharp
|
||||
public class ReviewableTestDescriptionAttribute : ReviewableAttribute
|
||||
```
|
||||
- **Constructor**:
|
||||
```csharp
|
||||
public ReviewableTestDescriptionAttribute(Event.Module module)
|
||||
```
|
||||
- **Behavior**:
|
||||
Initializes a reviewable attribute named `"Test Description"`. Value is `module.ParentEvent.Description`. *Note: This accesses the parent `Event`, not the `Module` directly.*
|
||||
|
||||
#### `ReviewableHardwareFrequencyAttribute`
|
||||
- **Signature**:
|
||||
```csharp
|
||||
public class ReviewableHardwareFrequencyAttribute : ReviewableAttribute
|
||||
```
|
||||
- **Constructor**:
|
||||
```csharp
|
||||
public ReviewableHardwareFilterAttribute(Event.Module module)
|
||||
```
|
||||
- **Behavior**:
|
||||
Initializes a reviewable attribute named `"HW AAF"` (Hardware Anti-Alias Filter). Value is `module.AaFilterRateHz.ToString("N2")` (2 decimal places).
|
||||
|
||||
---
|
||||
|
||||
### 3. **Invariants**
|
||||
|
||||
- **All attributes are immutable after construction**: The `name` and `DetermineValueString` delegate are set in the base constructor and never modified.
|
||||
- **Value evaluation is deferred**: The delegate passed to `base(...)` is invoked only when the attribute’s value is requested (e.g., for display), not at construction time.
|
||||
- **`ReviewableAttribute` base constructor enforces non-null `name` and `calculateValue`**: The protected constructor expects both parameters; the public constructor in subclasses always supplies them.
|
||||
- **`ReviewableDasSerialNumberAttribute` and other subclasses must be instantiated with a non-null `Event.Module`**: Otherwise, accessing `module.DasSerialNumber`, `module.SampleRateHz`, etc., will throw a `NullReferenceException`.
|
||||
- **`ReviewableAttribute` has two constructors, but only one is usable**:
|
||||
- The single-parameter constructor (`ReviewableAttribute(Event.Module)`) is *intentionally non-functional* and throws `NotImplementedException` via a wrapper `Exception`.
|
||||
- Only the two-parameter protected constructor (`ReviewableAttribute(string, DetermineValueString)`) is used in practice.
|
||||
|
||||
---
|
||||
|
||||
### 4. **Dependencies**
|
||||
|
||||
#### Dependencies *of* this module:
|
||||
- `DTS.Slice.Control.Event.Module` — Required for `module.DasSerialNumber`, `module.SampleRateHz`, `module.AaFilterRateHz`, and `module.ParentEvent`.
|
||||
- `DTS.Slice.Control.ReviewableAttribute` — Base class for `ReviewableAttribute`. (Implied by inheritance; source not provided, but referenced in `ReviewableAttribute.cs`.)
|
||||
- `DTS.Utilities` — Used for formatting (e.g., `.ToString("N")`), though standard .NET formatting would suffice.
|
||||
|
||||
#### Dependencies *on* this module:
|
||||
- Any code that needs to expose module metadata for review (e.g., UI forms, audit logging, export tools) will instantiate these classes and pass them to a review framework built around `ReviewableAttribute`.
|
||||
|
||||
#### Inferred relationships:
|
||||
- `Event.Module` must define the following properties (not visible in source, but required):
|
||||
- `string DasSerialNumber`
|
||||
- `double SampleRateHz`
|
||||
- `double AaFilterRateHz`
|
||||
- `Event ParentEvent` (with `string Description`)
|
||||
- `ReviewableAttribute` inherits from `Slice.Control.ReviewableAttribute`, which must define:
|
||||
- Constructor: `ReviewableAttribute(string name, DetermineValueString calculateValue)`
|
||||
- Property/method to retrieve the formatted value string (via `DetermineValueString` delegate).
|
||||
|
||||
---
|
||||
|
||||
### 5. **Gotchas**
|
||||
|
||||
- **Misleading XML comment for `ReviewableSampleRateAttribute` and `ReviewableHardwareFrequencyAttribute`**:
|
||||
Both are documented as “A reviewable filter frequency attribute attached to a specific channel.” — but they are attached to a `Module`, not a `Channel`. (The `ReviewableDasSerialNumberAttribute` comment is similarly inaccurate.)
|
||||
|
||||
- **`ReviewableTestDescriptionAttribute` accesses `module.ParentEvent.Description`**:
|
||||
This implies a parent-child relationship (`Module` → `Event`). If `module.ParentEvent` is `null`, this will throw `NullReferenceException`.
|
||||
|
||||
- **`ReviewableAttribute` constructor design is fragile**:
|
||||
The single-parameter constructor exists solely to fail at runtime. This is a code smell—ideally, it would be `private` or removed entirely.
|
||||
|
||||
- **String formatting is hardcoded**:
|
||||
`"N"` and `"N2"` are used directly in delegates. Changing formatting (e.g., locale, precision) requires source modification.
|
||||
|
||||
- **No null-safety in value delegates**:
|
||||
None of the delegates check for null (e.g., `module.DasSerialNumber` could be `null`, but `ToString()` is called unconditionally). This may yield `"False"` or `""` depending on type, or throw if `DasSerialNumber` is a non-nullable value type.
|
||||
|
||||
- **Typo in `ReviewableHardwareFrequencyAttribute` constructor name in source**:
|
||||
The XML comment says `channel`, but the parameter is named `module`. This is minor but inconsistent.
|
||||
|
||||
- **No documentation for `DetermineValueString` delegate type**:
|
||||
Its signature and contract are unknown from source alone. Assumed to be `Func<string>` or similar.
|
||||
|
||||
- **No tests or usage examples provided**:
|
||||
Behavior is inferred solely from constructor and inheritance. Actual runtime behavior (e.g., how values are consumed) is not verifiable from source.
|
||||
|
||||
---
|
||||
|
||||
*Note: All inferences assume standard .NET conventions and the structural clues in the provided source. Behavior of `DetermineValueString` and the parent `ReviewableAttribute` class cannot be fully confirmed without their source.*
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableShuntDeflectionAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableFilterFrequencyAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableIsoCodeAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableDescriptionAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableSerialNumberAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableUnitsAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableMinMaxEuAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableCfcAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableTargetShuntDeflectionAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableMeasuredShuntDeflectionAttribute.cs
|
||||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/AnalogInputChannel/ReviewableShuntDeflectionPercentageAttribute.cs
|
||||
generated_at: "2026-04-16T03:31:33.249057+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "248b93b117b62a27"
|
||||
---
|
||||
|
||||
# `DTS.Slice.Control.Event.Module.AnalogInputChannel.ReviewableAttribute` Derivatives
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module defines a set of concrete `ReviewableAttribute` subclasses used to expose specific channel metadata and calibration-related values for review in the DTS Slice control event system. Each attribute encapsulates a human-readable label and a delegate that dynamically computes a formatted string representation of a channel property at runtime—primarily for inclusion in audit trails, calibration reports, or diagnostic UIs. These attributes are attached to `AnalogInputChannel` instances and provide a standardized way to surface configuration, calibration, and measurement data without hardcoding display logic elsewhere in the system.
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
All classes are nested within `DTS.Slice.Control.Event.Module.AnalogInputChannel` and inherit from `Slice.Control.Event.Module.Channel.ReviewableAttribute`. Each constructor takes a single parameter of type `Event.Module.Channel` and passes a label string and a `Func<string>` (via `delegate { ... }`) to the base constructor.
|
||||
|
||||
| Class | Constructor Signature | Label | Behavior |
|
||||
|-------|------------------------|-------|----------|
|
||||
| `ReviewableShuntDeflectionAttribute` | `ReviewableShuntDeflectionAttribute(Event.Module.Channel channel)` | `"Shunt Deflection (mV)"` | Returns `MeasuredShuntDeflectionMv.ToString("F1")`, where `MeasuredShuntDeflectionMv` is accessed via `(channel as IShuntAware).MeasuredShuntDeflectionMv`. |
|
||||
| `ReviewableFilterFrequencyAttribute` | `ReviewableFilterFrequencyAttribute(Event.Module.Channel channel)` | `"Filter Frequency"` | Returns `(int)(channel.CurrentFilter as SaeJ211Filter).CutoffFrequencyHz` formatted with `ToString("N")`. |
|
||||
| `ReviewableIsoCodeAttribute` | `ReviewableIsoCodeAttribute(Event.Module.Channel channel)` | `"ISO Code"` | Returns `(channel as AnalogInputChannel).IsoCode.ToString()`. |
|
||||
| `ReviewableDescriptionAttribute` | `ReviewableDescriptionAttribute(Event.Module.Channel channel)` | `"Description"` | Returns `channel.ChannelDescriptionString`. |
|
||||
| `ReviewableSerialNumberAttribute` | `ReviewableSerialNumberAttribute(Event.Module.Channel channel)` | `"Serial Number"` | Returns `(channel as AnalogInputChannel).SerialNumber.ToString()`. |
|
||||
| `ReviewableUnitsAttribute` | `ReviewableUnitsAttribute(Event.Module.Channel channel)` | `"Units"` | Returns `(channel as IEngineeringUnitAware).EngineeringUnits.ToString()`. |
|
||||
| `ReviewableMinMaxEuAttribute` | `ReviewableMinMaxEuAttribute(Event.Module.Channel channel)` | `"Max/Min (EU)"` | Returns `"${DataMaxFilteredEu:F1}/${DataMinFilteredEu:F1}"`. |
|
||||
| `ReviewableCfcAttribute` | `ReviewableCfcAttribute(Event.Module.Channel channel)` | `"CFC"` | Returns `"N/A"` if `channel.CurrentFilter.Type == ChannelFilter.AdHoc`; otherwise returns `new CfcValueAttributeCoder().DecodeAttributeValue((channel.CurrentFilter as SaeJ211Filter).Type).ToString()`. |
|
||||
| `ReviewableTargetShuntDeflectionAttribute` | `ReviewableTargetShuntDeflectionAttribute(Event.Module.Channel channel)` | `"Target Shunt Deflection (mV)"` | Returns `TargetShuntDeflectionMv.ToString("F1")`, via `(channel as IShuntAware).TargetShuntDeflectionMv`. |
|
||||
| `ReviewableTargetCalSignalAttribute` | `ReviewableTargetCalSignalAttribute(Event.Module.Channel channel)` | `"Target Calibration Signal (mV)"` | Returns `TargetCalSignalMv.ToString("F1")`, via `(channel as ICalSignalAware).TargetCalSignalMv`. |
|
||||
| `ReviewableMeasuredShuntDeflectionAttribute` | `ReviewableMeasuredShuntDeflectionAttribute(Event.Module.Channel channel)` | `"Measured Shunt Deflection (mV)"` | Same as `ReviewableShuntDeflectionAttribute`. |
|
||||
| `ReviewableMeasuredCalSignalAttribute` | `ReviewableMeasuredCalSignalAttribute(Event.Module.Channel channel)` | `"Measured Calibration Signal (mV)"` | Same as `ReviewableTargetCalSignalAttribute` but for measured values: `(channel as ICalSignalAware).MeasuredCalSignalMv.ToString("F1")`. |
|
||||
| `ReviewableShuntDeflectionPercentageAttribute` | `ReviewableShuntDeflectionPercentageAttribute(Event.Module.Channel channel)` | `"Shunt Error (%)"` | Computes `(100.0 * (MeasuredShuntDeflectionMv - TargetShuntDeflectionMv) / TargetShuntDeflectionMv).ToString("F1")`. |
|
||||
| `ReviewableCalSignalPercentageAttribute` | `ReviewableCalSignalPercentageAttribute(Event.Module.Channel channel)` | `"Calibration Signal Error (%)"` | Computes `(100.0 * (MeasuredCalSignalMv - TargetCalSignalMv) / TargetCalSignalMv).ToString("F1")`. |
|
||||
|
||||
> **Note**: `IShuntAware`, `ICalSignalAware`, and `IEngineeringUnitAware` are interfaces defined in `DTS.DAS.Concepts.DAS.Channel`. `SaeJ211Filter`, `CfcValueAttributeCoder`, and `ChannelFilter` are defined in `DTS.Utilities`.
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- **All attributes require the `channel` parameter to be non-null**, and to support the specific interface(s) accessed in their delegate (e.g., `IShuntAware` for shunt-related attributes). Failure to meet this requirement will cause a runtime `InvalidCastException` or `NullReferenceException`.
|
||||
- **Format consistency**: All numeric outputs use `"F1"` (1 decimal place) or `"N"` (thousands separator, no decimals) formatting as shown. No validation or range checking is performed on the underlying values.
|
||||
- **No side effects**: The delegates are pure functions; they do not mutate state.
|
||||
- **No ordering guarantees**: The module does not define or enforce any ordering among these attributes when used collectively (e.g., in a list or collection).
|
||||
- **Type assumptions**: The code assumes `channel.CurrentFilter` is always a `SaeJ211Filter` when accessing `.Type` or `.CutoffFrequencyHz`. If `CurrentFilter` is not a `SaeJ211Filter`, this will throw at runtime.
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### Internal Dependencies (from source):
|
||||
- `DTS.Slice.Control.Event.Module.Channel.ReviewableAttribute` — base class (not shown, but referenced).
|
||||
- `DTS.DAS.Concepts.DAS.Channel.IShuntAware` — for `MeasuredShuntDeflectionMv`, `TargetShuntDeflectionMv`.
|
||||
- `DTS.DAS.Concepts.DAS.Channel.ICalSignalAware` — for `MeasuredCalSignalMv`, `TargetCalSignalMv`.
|
||||
- `DTS.DAS.Concepts.DAS.Channel.IEngineeringUnitAware` — for `EngineeringUnits`.
|
||||
- `DTS.Utilities.SaeJ211Filter` — used in `ReviewableFilterFrequencyAttribute` and `ReviewableCfcAttribute`.
|
||||
- `DTS.Utilities.CfcValueAttributeCoder` — used in `ReviewableCfcAttribute`.
|
||||
- `DTS.Utilities.ChannelFilter` — used in `ReviewableCfcAttribute` (specifically `ChannelFilter.AdHoc` constant).
|
||||
- `DTS.Slice.Control.Event.Module.AnalogInputChannel` — for `IsoCode`, `SerialNumber`, and `ChannelDescriptionString` properties.
|
||||
|
||||
### External Dependencies:
|
||||
- `System` (core namespaces: `System`, `System.Linq`, `System.Text`, `System.Collections.Generic`).
|
||||
- `DTS.Utilities` — assembly reference required.
|
||||
|
||||
### Inferred Consumers:
|
||||
- Likely consumed by UI or reporting layers that enumerate `ReviewableAttribute` instances on channels (e.g., for serialization, audit logging, or calibration review forms).
|
||||
- May be used in conjunction with `DTS.Slice.Control.Event` infrastructure (e.g., event logging, data export).
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
- **Redundant classes**: `ReviewableShuntDeflectionAttribute` and `ReviewableMeasuredShuntDeflectionAttribute` have identical implementation and labels. Same for `ReviewableTargetCalSignalAttribute` and `ReviewableMeasuredCalSignalAttribute`. This duplication may cause confusion or inconsistency if one is updated but not the other.
|
||||
- **Unsafe casts**: Multiple attributes use `as` casts without null checks (e.g., `(channel as IShuntAware)`). If the channel does not implement the interface, the cast yields `null`, leading to `NullReferenceException` when accessing `.MeasuredShuntDeflectionMv`.
|
||||
- **Assumed filter type**: `ReviewableFilterFrequencyAttribute` and `ReviewableCfcAttribute` assume `channel.CurrentFilter` is always a `SaeJ211Filter`. If `CurrentFilter` is another type (e.g., `AdHoc`), a runtime `InvalidCastException` occurs.
|
||||
- **Division by zero risk**: `ReviewableShuntDeflectionPercentageAttribute` and `ReviewableCalSignalPercentageAttribute` divide by `TargetShuntDeflectionMv` or `TargetCalSignalMv` without checking for zero. If the target is `0.0`, this throws `DivideByZeroException`.
|
||||
- **Missing null guard in `ReviewableCfcAttribute`**: The commented-out line suggests prior use of `CfcValueAttributeCoder`, but the current logic only handles `AdHoc` explicitly. If `CurrentFilter.Type` is neither `AdHoc` nor a valid `SaeJ211Filter.Type`, `CfcValueAttributeCoder.DecodeAttributeValue(...)` may throw or return unexpected results.
|
||||
- **Inconsistent casing**: `ReviewableDescriptionAttribute.cs` file header incorrectly labels it as `"ReviewableCfcAttribute.cs"` — likely a copy-paste artifact.
|
||||
- **No documentation of `IsoCode`, `SerialNumber`, `ChannelDescriptionString`**: These properties are used but not defined in the provided source; their existence and type must be inferred from usage.
|
||||
- **No documentation of `CfcValueAttributeCoder` behavior**: The behavior of `DecodeAttributeValue(...)` (e.g., what it returns for invalid inputs) is unknown from this source.
|
||||
|
||||
> **Recommendation**: Add runtime null checks and guard against zero denominators in percentage attributes. Consider consolidating duplicate classes or clarifying their intended distinction.
|
||||
@@ -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.*
|
||||
Reference in New Issue
Block a user