Metadata-Version: 2.4
Name: acmad-metrics
Version: 0.1.0
Summary: Metrics and Calculations for the ACMAD platform.
Author-email: Britney Kerr <britney.kerr@rch.org.au>, Elyse Passmore <elyse.passmore@mcri.edu.au>, Mary Nemati <m.nemati@griffith.edu.au>, Jan Hettenhausen <j.hettenhausen@griffith.edu.au>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.5.0
Requires-Dist: pandas>=3.0.5
Dynamic: license-file

# acmad-metrics

Metrics and Calculations Package

## Spatiotemporal summaries

The spatiotemporal API calculates unrounded overall, left-side and right-side
statistics from individual gait cycles. It is independent of Django and does
not query or filter database records.

### Example

```python
from acmad_metrics.spatiotemporal import (
    SpatiotemporalCycle,
    summarise_cycles,
)

cycles = [
    SpatiotemporalCycle(
        side="left",
        gait_speed_m_per_s=1.0,
        step_length_m=0.5,
        stride_length_m=1.0,
        stance_phase_percent=60.0,
    ),
    SpatiotemporalCycle(
        side="right",
        gait_speed_m_per_s=1.0,
        step_length_m=0.4,
        stride_length_m=1.5,
        stance_phase_percent=40.0,
    ),
]

summary = summarise_cycles(cycles)

cadence = summary.metrics["cadence"]

print(cadence.overall.mean)         # 135.0
print(cadence.overall.stddev)       # 15.0
print(cadence.overall.sample_count) # 2

print(cadence.left.mean)            # 120.0
print(cadence.right.mean)           # 150.0
```

### Input measurements

Each `SpatiotemporalCycle` represents one gait cycle. The `side` field is
required, while measurements may be `None` when unavailable.

Measurement units are:

- Gait speed: metres per second.
- Step, stride and step-width measurements: metres.
- Gait-phase measurements: percentages.

The caller is responsible for selecting which cycles should be included in
the summary. The package does not apply database or
`included_for_analysis` filtering.

### Derived measurements

Cadence is calculated separately for each cycle:

```text
cadence = (gait speed / step length) * 60
```

The result is expressed in steps per minute.

Stance time is calculated separately for each cycle:

```text
stance time =
    (stride length / gait speed)
    * (stance phase percentage / 100)
```

The result is expressed in seconds.

Derived measurements are calculated per cycle before their statistics are
calculated.

### Summary statistics

Every metric contains three groups:

- `overall`
- `left`
- `right`

Each group contains:

- `mean`
- `stddev`
- `sample_count`

The package uses population standard deviation, dividing by `n`.

A group with one available measurement has a population standard deviation
of `0.0`. A group with no available measurements has `None` for its mean and
standard deviation, and a sample count of zero.

`sample_count` is the number of available observations included in the
calculation. Its name does not indicate that sample standard deviation is
used.

Missing values are ignored, while zero remains a valid stored measurement.

### Available metrics

Stored measurements are available under these keys:

- `gait_speed_m_per_s`
- `normalised_gait_speed`
- `stride_length_m`
- `normalised_stride_length`
- `step_length_m`
- `normalised_step_length`
- `step_width_m`
- `stance_phase_percent`
- `swing_phase_percent`
- `single_support_phase_percent`
- `double_support_phase_percent`

Derived measurements are available under:

- `cadence`
- `stance_time`

### Rounding

Package results are returned without rounding. Applications consuming this
package are responsible for applying presentation or API-specific rounding.
