pyhctsa.sampling.sampling_report

pyhctsa.sampling.sampling_report(y, fs=None, target_tau=3)

Summarise how finely a time series is sampled relative to its own timescales.

Computes the delays that pyhctsa’s adaptive features use (get_tau()), the lag-1 autocorrelation and Toker et al.’s oversampling statistic (oversampling()), and suggests the integer decimation factor that would leave about target_tau samples per 1/e autocorrelation time. To resample a whole dataset, run the report on a few representative series, choose one factor, and pass it to resample_dataset().

Parameters:
y : array-like

The time series (a list, 1-D array or pandas Series).

fs : float, optional

The sampling rate (e.g. in Hz). If given, the report also expresses the timescale and the suggested rate in these units.

target_tau : float, optional

The number of samples per 1/e autocorrelation time to aim for (default 3). Must be positive.

Returns:

Dictionary containing:

  • ’n’: The length of the series.

  • ’tau_ac1e’: The 1/e autocorrelation time in samples (get_tau(y, 'ac1e')), the default delay of most adaptive features.

  • ’tau_ac’: The first zero crossing of the ACF in samples (get_tau(y, 'ac')).

  • ’tau_mi’: The AMI-based delay in samples (get_tau(y, 'mi'), capped at ‘tau_ac1e’).

  • ’acf1’: The lag-1 autocorrelation.

  • ’eta’: Toker et al.’s oversampling statistic, range(y) / mean(abs(diff(y))); values above 10 indicate oversampling.

  • ’decimation_factor’: max(1, floor(tau_ac1e / target_tau)), the integer factor that would leave about target_tau samples per 1/e time (NaN if ‘tau_ac1e’ is NaN).

  • ’decimated_length’: n // decimation_factor (NaN if the factor is NaN).

  • ’fs’, ‘tau_ac1e_seconds’, ‘fs_suggested’, ‘nyquist_suggested’ (only when fs is given): the sampling rate, ‘tau_ac1e’ in units of 1/fs, the rate after decimation (fs / decimation_factor) and its Nyquist frequency.

  • ’warnings’: A list of short strings describing problems (empty if none).

Return type:

dict

Notes

Warnings are raised when:

  • a delay is NaN (constant or very short series, or an ACF that never falls to 1/e);

  • tau_ac1e <= 2: the series is near-critically sampled, so the adaptive delays sit at 1 or 2 samples (integer flooring) and per-series normalisation has nothing to work with;

  • decimating by the suggested factor would leave fewer than 500 samples;

  • max(tau_ac, tau_ac1e, tau_mi) / min(...) > 10: the delays disagree wildly, as for a nonstationary or trending series, whose timescale is not well defined;

  • tau_ac1e == 1 while acf1 > 0.2: the series is correlated at lag 1 but white measurement noise (a broadband noise floor) pulls the ACF below 1/e at lag 2, so the 1/e rule understates how oversampled the underlying signal is. Low-pass filtering before choosing a factor (see resample_dataset()) helps here.

The ‘mi’ delay uses a Kraskov AMI estimate, which takes a second or so for long, slowly decorrelating series.

Examples

>>> import numpy as np
>>> from pyhctsa.sampling import sampling_report
>>> rng = np.random.default_rng(0)
>>> rep = sampling_report(rng.standard_normal(2000), fs=100.0)
>>> rep['tau_ac1e'], rep['decimation_factor']
(1, 1)