Time and frequency grids

This module provides helper classes to handle time and frequency sampling attributes in Mojito L1 files.

class mojito.sampling.UniformTimeSampling(*, t0, dt, size)

Helper class to handle sampling attributes in Mojito L1 files.

dt: float

Time step of the sampling [s].

property duration: float

Duration of the time series [s].

This is defined as size * dt. Note that the last timestamp is not t0 + duration, but t0 + (size - 1) * dt.

classmethod from_h5_group(group)

Create an instance from an HDF5 group.

Parameters:

group (Group) – HDF5 group containing the sampling attributes.

Returns:

Instance populated with the group’s attributes.

Return type:

TimeSampling

property fs: float

Sampling frequency [Hz].

size: int

Number of samples in the time series.

slice_between(tmin, tmax)

Return a slice that contains the interval [tmin, tmax].

We guarantee that any time t such that tmin <= t <= tmax is included in the returned slice.

sampling = UniformTimeSampling(t0=0.0, dt=0.1, size=100)
time_array = sampling.t()

# Pick a random time between 2.3s and 5.7s
tmin = 2.3
tmax = 5.7
random_t = np.random.uniform(tmin, tmax)

# Slice the time array
time_slice = sampling.slice_between(tmin, tmax)
selected_times = time_array[time_slice]

# We guarantee that random_t is in selected_times
assert random_t in selected_times

Warning

Because floating-point arithmetics is not exact, we extend the slice so that it will always contain tmin and tmax. As a result, the returned slice can be larger than (tmax - tmin) / dt. Note that it is at most 2 * self.dt larger.

Parameters:

• tmin (float | None) – Lower bound of the time range [s]. If None, the slice starts at the beginning of the time series.

• tmax (float | None) – Upper bound of the time range [s]. If None, the slice ends at the end of the time series.

Return type:

slice

Returns:

A slice instance such that all times t with tmin <= t <= tmax are included in self.t()[slice].

Raises:

ValueError – If tmin < self.t0, or if tmax > self.tmax().

t(idx=None, *, elapsed=False)

Return the uniform array of times.

The time grid is defined as t0 + i * dt for i in range(size).

Use the slice parameter to return a sliced version of the time grid. This is useful for long datasets, as this will only allocate the selected timestamps in memory. For example:

>>> sampling = UniformTimeSampling(t0=1.5, dt=0.5, size=10)
>>> sampling.t(slice(2, 7, 2))
array([2.5, 3.5, 4.5])

If elapsed is True, the time grid is defined as i * dt for i in range(size). This can be useful to preserve numerical precision.

Parameters:

• idx (slice | None, default: None) – Slice selecting which timestamps to return.

• elapsed (bool, default: False) – If True, return elapsed time grid starting at 0.

Returns:

Array of times [s]. Shape is (size,) if idx is None, otherwise it matches the selected slice length.

Return type:

NDArray

t0: float

Start time of the sampling [s].

tmax(elapsed=False)

Return the last timestamp.

The last timestamp is defined as the last element of the array returned by t(). Note that this is not t0 + duration.

If elapsed is False, it corresponds to t0 + (size - 1) * dt. If elapsed is True, the time origin is ignored and the last timestamp is (size - 1) * dt.

Parameters:

elapsed (bool, default: False) – If True, ignore t0.

Return type:

float

Returns:

Last timestamp [s].

class mojito.sampling.LogUniformFrequencySampling(*, fmin, fmax, size)

Helper class to handle logarithmic frequency sampling in Mojito L1 files.

Frequencies must be positive here.

f(idx=None)

Return the log-uniform array of frequencies.

The frequency grid is defined as \(f_i = 10^{F_i}\) with \(F_i = \log_{10}(f_\mathrm{min}) + i \Delta \log_{10}(f)\), for \(i\) ranging from 0 to size - 1 and \(\Delta \log_{10}(f) = (\log_{10}(f_\mathrm{max}) - \log_{10}(f_\mathrm{min})) / (\text{size} - 1)\).

Use the idx parameter to return a sliced version of the frequency grid. This is useful for long datasets, as this will only allocate the selected frequencies in memory. For example:

>>> sampling = LogUniformFrequencySampling(fmin=1.0, fmax=100.0, size=10)
>>> sampling.f(slice(2, 7, 2))
array([ 2.7825594 ,  7.74263683, 21.5443469 ])

Parameters:

idx (slice | None, default: None) – Slice selecting which frequencies to return.

Returns:

Array of frequencies [Hz]. Shape is (size,) if idx is None, otherwise it matches the selected slice length.

Return type:

NDArray

fmax: float

Maximum frequency [Hz].

fmin: float

Minimum frequency [Hz].

classmethod from_h5_group(group)

Create an instance from an HDF5 group.

Parameters:

group (Group) – HDF5 group containing the frequency sampling attributes.

Returns:

Instance populated with the group’s attributes.

Return type:

LogUniformFrequencySampling

size: int

Number of frequencies.