inertialsim.time

Time utilities.

The time module provides:

• methods to create, validate, and analyze standardized time arrays.

Classes:

Name	Description
SampleRateTolerances	Sample rate tolerances for time validation.

Functions:

Name	Description
merge	Merge two compatible time arrays.
sample_period_statistics	Calculate sample period statistics.
sample_rate_statistics	Calculate sample rate statistics.
span	Create a time array with evenly spaced values.
validate	Validate time array.

Attributes:

Name	Type	Description
SAMPLE_RATE_TOLERANCES		Default sample rate tolerances.

SAMPLE_RATE_TOLERANCES module-attribute

SAMPLE_RATE_TOLERANCES = SampleRateTolerances()

Default sample rate tolerances.

SampleRateTolerances dataclass

SampleRateTolerances(
    *,
    minimum: float = 0.6,
    maximum: float = 1.4,
    median: float = 0.01,
    standard_deviation: float = 0.1,
)

Sample rate tolerances for time validation.

Default tolerances

With an expected sample rate of 100 Hz the default values will raise an error if any sample rate is <60Hz, or >140Hz. An error will also be raised if the median sample rate is <99Hz or >101Hz or if the standard deviation of the sample rates is >10Hz.

Attributes:

Name	Type	Description
minimum	float	Minimum allowable sample rate.
maximum	float	Maximum allowable sample rate.
median	float	Median allowable sample rate error.
standard_deviation	float	Maximum allowable sample rate standard deviation.

minimum class-attribute instance-attribute

minimum: float = 0.6

Minimum allowable sample rate.

Minimum allowable sample rate as a fraction of the expected value. Sample rates <(minimum * expected) raise an error.

maximum class-attribute instance-attribute

maximum: float = 1.4

Maximum allowable sample rate.

Maximum allowable sample rate as a fraction greater than the expected value. Sample rates >(maximum * expected) raise an error.

median class-attribute instance-attribute

median: float = 0.01

Median allowable sample rate error.

Median allowable sample rate error as a fraction of the expected value. Sample rate medians <(1 - median) * expected or >(1 + median) * expected raise an error.

standard_deviation class-attribute instance-attribute

standard_deviation: float = 0.1

Maximum allowable sample rate standard deviation.

Maximum allowable sample rate standard deviation as a fraction of the expected value. Sample rate deviations >(standard_deviation * expected) raise an error.

merge

merge(
    time1: NDArray | None,
    time2: NDArray | None,
    tolerance: float = 1e-09,
) -> NDArray | None

Merge two compatible time arrays.

If both inputs are None, returns None. If only one of the inputs is None, returns the other input. If both inputs are not None, checks they are close to each other element-wise and return the first input if they are. Otherwise raises a ValueError.

Parameters:

Name	Type	Description	Default
time1	NDArray | None	The first time array.	required
time2	NDArray | None	The second time array.	required
tolerance	float	Tolerance for comparing time1 and time2 for equality (seconds).	1e-09

Returns:

Name	Type	Description
merged_time	NDArray | None	Merged time array.

sample_period_statistics

sample_period_statistics(
    time: NDArray,
) -> tuple[float, float, float, float]

Calculate sample period statistics.

Calculate the minimum, maximum, median, and sample deviation of sampling periods from the time array input. The sampled period is the difference between consecutive times. A robust estimate of the standard deviation is calculated to reduce the effect of outliers.

Inputs should be pre-validated with validate.

Parameters:

Name	Type	Description	Default
time	NDArray	An array of timestamps.	required

Returns:

Name	Type	Description
minimum	float	Minimum sample period (s).
maximum	float	Maximum sample period (s).
median	float	Median sample period (s).
standard_deviation	float	Standard deviation of sample periods (s).

sample_rate_statistics

sample_rate_statistics(
    time: NDArray,
) -> tuple[float, float, float, float]

Calculate sample rate statistics.

Calculate the minimum, maximum, median, and sample deviation of sampling rates from the time array input. The sample rate is the inverse of the difference between consecutive times. A robust estimate of the standard deviation is calculated to reduce the effect of outliers.

Inputs should be pre-validated with validate.

Parameters:

Name	Type	Description	Default
time	NDArray	An array of timestamps.	required

Returns:

Name	Type	Description
minimum	float	Minimum sample rate (Hz).
maximum	float	Maximum sample rate (Hz).
median	float	Median sample rate (Hz).
standard_deviation	float	Standard deviation of sample rates (Hz).

span

span(start: float, end: float, dt: float) -> NDArray

Create a time array with evenly spaced values.

Following InertialSim and numpy convention, time extends along the first axis of an array, so an array of shape (Nx1x1) is returned. The end time is included in the time array dependent on dt being a near integer multiple of (start - end) in the presence of floating point round-off. See numpy.arange for further details.

The end point must be larger than the start point, and dt must be greater than 0.

Parameters:

Name	Type	Description	Default
start	float	Start time in seconds.	required
end	float	End time in seconds.	required
dt	float	Time delta in seconds.	required

Returns:

Name	Type	Description
time	NDArray	Time array, shape=(N,1,1).

validate

validate(
    time: ArrayLike,
    *,
    expected_sample_rate: float | None = None,
    tolerance: SampleRateTolerances = SAMPLE_RATE_TOLERANCES,
) -> NDArray

Validate time array.

Several classes take optional time inputs (see geodesy.Coordinates, geometry.Rotation, sensors.Measurement, etc.). This function provides common validation across classes. Time inputs must be unique, monotonically increasing, and (optional) match the expected sample rate.

If time contains non-finite values (inf, nan), a ValueError is raised. If time is a numeric input, it is converted to a numpy array type which is checked for uniqueness and strict sorting. If either test fails, a ValueError is raised. If both tests succeed, the input (possibly modified in shape) is returned.

If expected_sample_rate is input and time has more than one value, optional sample rate checks are performed using the tolerance input. Outliers, like duplicated timestamps or missing data, are common. They are particularly problematic in inertial algorithms that require numerical differentiation, integration, or interpolation. A ValueError is raised if any of the tolerances are exceeded.

The input is copied to prevent unexpected side effects.

Minimum sample rate error

The fourth timestamp is sampled at 50Hz, exceeding 40% (min_tolerance=0.4) less than the expected rate of 100Hz.

t = [0.0, 0.01, 0.02, 0.04]
validate(t, expected_sample_rate = 100.0)
raises(ValueError)

Maximum sample rate error

The fourth timestamp is sampled at 250Hz, exceeding 40% (max_tolerance=0.4) greater than the expected rate of 100Hz.

t = [0.0, 0.01, 0.02, 0.024]
validate(t, expected_sample_rate = 100.0)
raises(ValueError)

Median sample rate error

The median sample rate is 80Hz, differing by more than 1% (median_tolerance=0.01) compared to the expected rate of 100Hz.

t = [0.0, 0.0125, 0.025, 0.0375, 0.04]
validate(t, expected_sample_rate = 100.0)
raises(ValueError)

Standard deviation sample rate error

The median sample rate is 100Hz, but the standard deviation differs from it by more than 10% (std_tolerance=0.1).

t = [0.0, 0.011, 0.019, 0.032, 0.041]
validate(t, expected_sample_rate = 100.0)
raises(ValueError)

Parameters:

Name	Type	Description	Default
time	ArrayLike	Array of timestamps.	required
expected_sample_rate	float | None	Expected sample rate. Must be a positive value (Hz).	None
tolerance	SampleRateTolerances	Sample rate tolerances.	SAMPLE_RATE_TOLERANCES

Returns:

Name	Type	Description
time	NDArray	Array of validated timestamps.