Time and frequency grids

Contain classes for uniform time and log-uniform frequency grids.

The UniformTimeGrid represents a uniform time grid, while the LogUniformFrequencyGrid represents a log-uniform frequency grid. They contain the minimal attributes required to define the respective grids, and provide convenient methods to generate the corresponding arrays of time or frequency values and derived quantities.

class mojito.grids.UniformTimeGrid(*, t0, dt, size)

Uniform time grid.

dt: float

Time step [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.

Return type:

Self

Returns:

Instance populated with the group’s attributes.

property fs: float

Sampling frequency [Hz].

size: int

Number of samples.

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 idx 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 [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.grids.LogUniformFrequencyGrid(*, fmin, fmax, size)

Log-uniform frequency grid.

Note that all 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.

Return type:

Self

Returns:

Instance populated with the group’s attributes.

size: int

Number of frequencies.