spectral_interpolate

hypercoil.functional.interpolate.spectral_interpolate(data: Tensor, mask: Tensor, oversampling_frequency: float = 8, maximum_frequency: float = 1, sampling_period: float = 1, frequency_thresh: float = 0) → Tensor

Spectral interpolation based on basis function projection.

Given a time series with missing or corrupt observations, this operation estimates the time series frequency spectra by proxy of projections onto sine and cosine basis functions, and then uses the frequency spectrum estimates as basis function weights in the reconstruction of missing observations.

Warning

Users of this approach must be advised that the missing observations result in non-orthogonal basis functions, and accordingly the variance captured by different frequency bins might be shared.

Note

This method is inspired by previous work from Anish Mitra and Jonathan Power which in turn is inspired by the Lomb-Scargle periodogram.

This method is used to temporarily interpolate over time points flagged for omission due to high artefact content, so as to reduce disruptions to the autocorrelation structure introduced by either artefactual outliers or zeroing (or arguably linearly interpolating) those outliers. This is useful for operations such as filtering and convolution for which the autocorrelation structure of the data is relevant. It should not be used for operations in which the autocorrelation structure plays no role, such as covariance estimation, for which the weights of missing observations can easily be set to 0.

Warning

spectral_interpolate expects batched input data and tmask arguments. If your inputs are not batched, unsqueeze their first dimension before providing them as inputs.

Warning

If the input time series contains either no or all missing observations, then the output time series will be identical to the input time series.

Parameters:

datatensor

Time series data.

maskboolean tensor

Boolean tensor indicating whether the value in each frame of the input time series is observed. True indicates that the original data are “good” or observed, while False indicates that they are “bad” or missing and flags them for interpolation.

oversampling_frequencyfloat (default 8)

Determines the number of frequency bins to use when estimating the sine and cosine spectra. 1 indicates that the number of bins should be the same as in a Fourier transform, while larger values indicate that frequency bins should be oversampled.

maximum_frequencyfloat (default 1)

Maximum frequency bin to consider in the fit, as a fraction of Nyquist.

sampling_periodfloat (default 1)

Period separating consecutive samples in data.

frequency_threshfloat (default 0.3)

Because of the non-orthogonality of the basis functions, spurious variance will often be captured in the spectral estimates. To control this spurious variance, all frequency bins whose estimates are less than frequency_thresh, as a fraction of the maximum estimate across all bins, are set to 0.

Returns:

Tensor

Input dataset with missing frames imputed.