mth5.timeseries.ts_helpers

Time series helper functions.

Provides utilities for time series processing including decimation planning, significant figure counting, and datetime coordinate generation.

Notes

Created on Wed Mar 29 14:27:22 2023

Author: jpeacock

Functions

`get_decimation_sample_rates`(→ list[float])	Compute decimation steps from old to new sample rate.
`make_dt_coordinates`(→ pandas.DatetimeIndex)	Generate datetime coordinates for time series data.

Module Contents

mth5.timeseries.ts_helpers.get_decimation_sample_rates(old_sample_rate: float, new_sample_rate: float, max_decimation: int) → list[float][source]

Compute decimation steps from old to new sample rate.

Generates a list of intermediate sample rates to decimate from old_sample_rate to new_sample_rate without exceeding max_decimation at any single step. Uses geometric series to distribute decimation evenly.

Parameters:

old_sample_rate (float) – Original sample rate in samples per second.
new_sample_rate (float) – Target sample rate in samples per second.
max_decimation (int) – Maximum allowed decimation factor per step.

Returns:

List of intermediate sample rates for multi-stage decimation. If total decimation <= max_decimation, returns [new_sample_rate].

Return type:

list[float]

Examples

Single-step decimation (factor <= max):

>>> get_decimation_sample_rates(100, 10, 13)
[10]

Multi-step decimation (factor > max):

>>> get_decimation_sample_rates(1000, 10, 13)
[77, 10]
>>> # Decimates 1000 -> 77 -> 10

Three-step decimation:

>>> get_decimation_sample_rates(10000, 10, 13)
[770, 60, 10]

Generate datetime coordinates for time series data.

Creates a pandas DatetimeIndex with proper rounding based on sample rate precision. Handles edge cases like invalid sample rates and missing start times with sensible defaults.

Parameters:

start_time (str | MTime | None) – Start time in ISO format or MTime object. If None, defaults to ‘1980-01-01T00:00:00’.
sample_rate (float | None) – Sample rate in samples per second. If None or 0, defaults to 1 and issues a warning.
n_samples (int) – Number of samples in the time series. Must be >= 1.
end_time (str | MTime | None, default None) – End time in ISO format or MTime object. If None, computed from start_time, sample_rate, and n_samples.

Returns:

DatetimeIndex with n_samples timestamps, rounded to appropriate precision (ms, us, or ns) based on significant figures.

Return type:

pandas.DatetimeIndex

Raises:

ValueError – If n_samples < 1.

Warning

UserWarning: If sample_rate is invalid (None or 0) or start_time is None.

Notes

End time is calculated as: start_time + (n_samples - 1) / sample_rate
Rounding precision determined by significant figures in start time and sample period (1 / sample_rate): * < 3 sig figs: millisecond rounding * 3-5 sig figs: microsecond rounding * 6-8 sig figs: nanosecond rounding * >= 9 sig figs: no rounding

Examples

Create 100 Hz time index for 1000 samples:

>>> dt = make_dt_coordinates('2023-01-01T00:00:00', 100.0, 1000)
>>> len(dt)
1000
>>> dt[0]
Timestamp('2023-01-01 00:00:00')
>>> dt[-1]
Timestamp('2023-01-01 00:00:09.990000')

With explicit end time:

>>> dt = make_dt_coordinates(
...     '2023-01-01T00:00:00',
...     10.0,
...     100,
...     end_time='2023-01-01T00:00:09.9'
... )

Handle invalid sample rate (uses default of 1 Hz):

>>> dt = make_dt_coordinates('2023-01-01T00:00:00', None, 10)
# Warning: Need to input a valid sample rate...