init
This commit is contained in:
125
enriched-partialglm/Common/DTS.Common.Calculations.md
Normal file
125
enriched-partialglm/Common/DTS.Common.Calculations.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.Calculations/ChannelData.cs
|
||||
- Common/DTS.Common.Calculations/Integral.cs
|
||||
- Common/DTS.Common.Calculations/Resultant.cs
|
||||
- Common/DTS.Common.Calculations/HeadInjuryCriterion.cs
|
||||
generated_at: "2026-04-16T11:35:26.354514+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "2d2deac012cb62cf"
|
||||
---
|
||||
|
||||
# DTS.Common.Calculations Module Documentation
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides mathematical calculation utilities for signal processing, specifically focused on biomechanical injury analysis. It contains a data container class (`ChannelData`) for holding filtered time-series data with associated engineering units, and implements algorithms for numerical integration (`Integral`), vector resultant calculation (`Resultant`), and Head Injury Criterion computation (`HeadInjuryCriterion`). The module is designed to work with pre-filtered sensor data, particularly acceleration channels used in impact testing.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### `ChannelData` Class
|
||||
|
||||
A data container for holding filtered channel data with associated engineering units.
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| Constructor | `ChannelData(string units)` | Constructs a new `ChannelData` instance with the specified engineering units. |
|
||||
| `Units` | `string Units { get; }` | Read-only property returning the engineering units of the data. |
|
||||
| `FilteredEU` | `double[] FilteredEU { get; set; }` | Gets or sets the pre-filtered engineering unit data array. |
|
||||
|
||||
---
|
||||
|
||||
### `Integral` Static Class
|
||||
|
||||
Provides numerical integration methods.
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `DefiniteIntegral` | `static double DefiniteIntegral(double[] input, int start, int end, double SPS)` | Computes the definite integral of `input` from index `start` to `end` (both inclusive) using trapezoidal summation. `SPS` is samples per second (sample rate). Returns the integrated value. |
|
||||
|
||||
---
|
||||
|
||||
### `Resultant` Static Class
|
||||
|
||||
Provides vector resultant calculation from multiple input channels.
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `GenerateResultantChannel` | `static ChannelData GenerateResultantChannel(List<ChannelData> channels)` | Generates a resultant channel by computing the square root of the sum of squares across all input channels at each sample index. Returns a new `ChannelData` with the resultant values. |
|
||||
|
||||
---
|
||||
|
||||
### `HeadInjuryCriterion` Static Class
|
||||
|
||||
Provides Head Injury Criterion (HIC) calculation for biomechanical analysis.
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `GetHeadInjuryCriterion` | `static HICResult GetHeadInjuryCriterion(ChannelData resultant, double SPS, int clipLengthMS)` | Calculates the maximum Head Injury Criterion over the input `resultant` acceleration channel for the specified `clipLengthMS` duration. `SPS` is the actual sample rate in samples per second. Returns an `HICResult` containing the maximum HIC value and its location. |
|
||||
|
||||
#### `HICResult` Nested Class
|
||||
|
||||
A result container for HIC calculations.
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `StartSample` | `int` | The starting sample index of the maximum HIC window. |
|
||||
| `EndSample` | `int` | The ending sample index of the maximum HIC window. |
|
||||
| `HicLengthMS` | `int` | The HIC clip length in milliseconds. |
|
||||
| `HIC` | `double` | The calculated maximum HIC value. |
|
||||
|
||||
| Constructor | Signature |
|
||||
|-------------|-----------|
|
||||
| `HICResult` | `HICResult(double hic, int hicLength, int startSample, int endSample)` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- **`Integral.DefiniteIntegral`**: The input data must be tightly time-aligned (uniform sampling interval). The method assumes constant spacing between samples, allowing division by `SPS` rather than computing variable time deltas.
|
||||
|
||||
- **`Resultant.GenerateResultantChannel`**: All channels in the input list must have:
|
||||
- Identical `FilteredEU` array lengths
|
||||
- Identical `Units` values
|
||||
|
||||
These constraints are enforced via `Trace.Assert` calls.
|
||||
|
||||
- **`HeadInjuryCriterion.GetHeadInjuryCriterion`**:
|
||||
- `SPS` must be greater than 0
|
||||
- `clipLengthMS` must be greater than 0
|
||||
- The `resultant.FilteredEU` array must contain at least `clipLengthMS` worth of data (specifically, at least `maxclip` samples where `maxclip = Ceiling(clipLengthMS * SPS / 1000)`)
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This module depends on:
|
||||
- `System` (for `Math`, `Convert`, `DateTime`-related types)
|
||||
- `System.Collections.Generic` (for `List<T>`)
|
||||
- `System.Linq` (for `Distinct()`, `Max()`, `First()`, `Count()`, `Select()`)
|
||||
- `System.Diagnostics` (for `Trace.Assert`)
|
||||
|
||||
### What depends on this module:
|
||||
- **Unclear from source alone** — no consumers are shown in the provided files. This appears to be a foundational calculation library intended for use by higher-level analysis modules.
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **Assertion behavior in production**: All validation is performed using `System.Diagnostics.Trace.Assert`. By default, `Trace.Assert` only triggers a dialog in debug builds and may be silently ignored in release configurations depending on trace listener configuration. Invalid inputs may produce incorrect results rather than explicit failures in production.
|
||||
|
||||
2. **Brute-force HIC algorithm**: The `GetHeadInjuryCriterion` method uses an exhaustive brute-force approach, recalculating integrals repeatedly. The source explicitly acknowledges this inefficiency with the comment: *"we are exhaustively recalculating sums, we can do this much better without a doubt."* Performance may be poor for large datasets.
|
||||
|
||||
3. **Documentation typo in `HICResult` constructor**: The XML documentation comments for the constructor parameters have the descriptions for `endSample` and `startSample` swapped:
|
||||
```csharp
|
||||
/// <param name="endSample">start sample of HIC</param>
|
||||
/// <param name="startSample">end sample of HIC</param>
|
||||
```
|
||||
The actual parameter order is `(hic, hicLength, startSample, endSample)`.
|
||||
|
||||
4. **Future unit conversion not implemented**: The `ChannelData` class stores units but provides no unit conversion functionality. The comment indicates this is planned for future implementation.
|
||||
|
||||
5. **Potential parallelization opportunity**: The `Resultant.GenerateResultantChannel` method contains a comment indicating parallelization is planned for a future version, but the current implementation is single-threaded.
|
||||
Reference in New Issue
Block a user