pyhctsa.sampling.resample_dataset

pyhctsa.sampling.resample_dataset(data, factor, zero_phase=True)

Decimate every series in a dataset by one integer factor, with an anti-aliasing filter.

Applying the same factor to every series keeps differences in timescale between series (which a per-series normalisation would remove) while bringing the sampling interval closer to the dynamics. Choose the factor from domain knowledge of the signal band, or from sampling_report() on representative series.

Each series is filtered and downsampled with scipy.signal.decimate() using its default anti-aliasing filter: an order-8 Chebyshev type I low-pass filter (IIR) with cutoff at 0.8 of the new Nyquist frequency, i.e. 0.8 * fs / (2 * factor). Factors above 13 are applied in stages of at most 13 (as scipy recommends); a stage that cannot be split, a prime factor above 13, uses scipy’s FIR filter instead (a Hamming-window FIR of order 20 * stage). The output keeps samples 0, factor, 2 * factor, ..., so a series of length n becomes ceil(n / factor) long.

Parameters:
data : array-like or list of array-like

A single series (a list, 1-D array or pandas Series), a list of series (which may differ in length), or a 2-D array of shape (n_series, n_samples), as accepted by FeatureCalculator.extract. Series must be finite: a NaN spreads through the filter.

factor : int

The decimation factor, an integer >= 1. With factor == 1 every series is returned unchanged (as a float array).

zero_phase : bool, optional

Filter forwards and backwards (no phase shift; default True), as in scipy.signal.decimate(). With False the filter is causal and delays the signal.

Returns:

The decimated series, in input order (a list even for a single input series).

Return type:

list of numpy.ndarray

Raises:

ValueError – If factor is not an integer >= 1, or a series is too short to filter (the IIR filter needs more than 27 samples per stage).

Examples

>>> import numpy as np
>>> from pyhctsa.sampling import resample_dataset
>>> rng = np.random.default_rng(0)
>>> out = resample_dataset([rng.standard_normal(1000), rng.standard_normal(600)], 4)
>>> [len(x) for x in out]
[250, 150]