utils Submodule

torchcast.utils.autocorrelation(series: Tensor, n_lags: int | None = None, adjusted: bool = True, dim: int = -1, batch_dim: int | Iterable[int] | None = None, use_fft: bool | None = None) → Tensor

Calculates the autocorrelation of a series. The autocorrelation is the ratio of the autocovariance to the variance:

\[ \begin{align}\begin{aligned}\mbox{Autocorr}(x)_k = \mbox{Autocov}(x)_k / \mbox{Var}(x)\\\mbox{Autocov}(x)_k = \mathbb{E}(x_tx_{t + k}) - (\mathbb{E}x)^2\end{aligned}\end{align} \]

Where the expectation is taken over time. This function can calculate the autocorrelation using either the brute-force method or the Wiener-Khinchin method.

For a multivariate series, this returns only the autocorrelations of each channel to itself. The autocorrelation is returned as a 2-dimensional torch.Tensor, with the 0th dimension indexing the channel and the 1st dimension indexing the lag.

Parameters:

• series (torch.Tensor) – The series to find the autocorrelation of.

• n_lags (optional, int) – Number of lags. If not set, return all lags.

• adjusted (bool) – If set, use (n - k) in the denominator instead of n. The adjusted estimator has lower bias but typically has worse mean squared error.

• dim (int) – Dimension indexing time in the series.

• batch_dim (optional, int or iterator of int) – Dimensions indexing the batches. If provided, we assume that each row along these dimensions is a different sample from the same underlying distribution.

• use_fft (optional, bool) – Allows user to specify explicitly whether to use the FFT in the calculation. FFT is generally faster for longer time series, and slower for shorter ones. If not set, then we infer from the size of the data.

torchcast.utils.autocovariance(series: Tensor, n_lags: int | None = None, adjusted: bool = True, dim: int = -1, batch_dim: int | Iterable[int] | None = None, use_fft: bool | None = None) → Tensor

Calculates the autocovariance of a series:

\[\mbox{Autocov}(x)_k = \mathbb{E}(x_tx_{t + k}) - (\mathbb{E}x)^2\]

Where the expectation is taken over time. Note that the 0th autocovariance is equal to the variance of the series. This function can calculate the autocorrelation using either the brute-force method or the Wiener-Khinchin method.

For a multivariate series, this returns only the autocovariances of each channel to itself; to get the full matrix use the cross-covariance function. The autocovariance is returned as a 2-dimensional torch.Tensor, with the 0th dimension indexing the channel and the 1st dimension indexing the lag.

Parameters:

• series (torch.Tensor) – The series to find the autocovariance of.

• n_lags (optional, int) – Number of lags. If not set, return all lags.

• adjusted (bool) – If set, use (n - k) in the denominator instead of n. The adjusted estimator has lower bias but typically has worse mean squared error.

• dim (int) – Dimension indexing time in the series.

• batch_dim (optional, int or iterator of int) – Dimensions indexing the batches. If provided, we assume that each row along these dimensions is a different sample from the same underlying distribution.

• use_fft (optional, bool) – Allows user to specify explicitly whether to use the FFT in the calculation. FFT is generally faster for longer time series, and slower for shorter ones. If not set, then we infer from the size of the data.

torchcast.utils.continuous_ranked_probability_score(true_values: Tensor, samples: Tensor, dim: int = -1)

Calculates the continuous ranked probability score given a set of samples:

\[\mbox{CRPS}(F, y) = \int (F(z) - \mathbb{1}(y \leq z))^2 dz\]

Which, provided the distribution is well-behaved, is equivalent to:

\[\mbox{CRPS}(F, y) = \mathbb{E}|X_1 - y| - \frac{1}{2}\mathbb{E}|X_1 - X_2|\]

Where \(X_1, X_2\) are independent samples from the distribution of \(F\).

For further details, see:

https://cran.r-project.org/web/packages/scoringRules/vignettes/article.pdf

torchcast.utils.cross_spectral_density(x: Tensor, y: Tensor, sampling_frequency: float = 1.0, window_length: int | None = None, overlap: int = 0, dim: int = -1, batch_dim: int | Iterable[int] | None = None) → Tuple[Tensor, Tensor]

Calculates the cross spectral density for two series:

\[P_{xy}(f) = \mathcal{F}(R_{xy})(f)\]

Where \(\mathcal{F}\) denotes the Fourier transform and \(R_{xy}\) is the cross-correlation. The calculation uses the Welch method from:

Welch, 1967. “The use of Fast Fourier Transform for the Estimation of Power Spectra: A Method Based on Time Averaging over Short, Modified Periodograms.” IEEE Transactions on Audio and Electroacoustic, Vol. AU-15, No. 2, pp. 70-73.

Parameters:

• x (torch.Tensor) – First tensor to calculate the cross spectral density of.

• y (torch.Tensor) – Second tensor to calculate the cross spectral density of.

• sampling_frequency (float) – Frequency of samples in the tensor.

• window_length (optional, int) – Length of window to use in Welch method. If not specified, defaults to the minimum of 256 and the length of the tensors.

• overlap (int) – Length of window overlap to use in Welch method.

• dim (int) – Dimension of time axis.

• batch_dim (optional, int or iterable of ints) – Dimension(s) of batch axes.

torchcast.utils.partial_autocorrelation(series: Tensor, n_lags: int | None = None, adjusted: bool = True, dim: int = -1, batch_dim: int | Iterable[int] | None = None, use_fft: bool | None = None) → Tensor

Calculates the partial autocorrelation of a series, using the recursive Yule-Walker method. See:

Box, Jenkins, et al. Time Series Analysis. John Wiley and Sons, 2016. pp. 84-86.

This currently returns only the autocorrelations of each channel to itself, it does not support returning the full matrix. The autocorrelation is returned as a 2-dimensional torch.Tensor, with the 0th dimension indexing the channel and the 1st dimension indexing the lag.

Parameters:

• series (torch.Tensor) – The series to find the partial autocorrelation of.

• n_lags (optional, int) – Number of lags. If not set, return all lags.

• adjusted (bool) – If set, use (n - k) in the denominator instead of n. The adjusted estimator has lower bias but typically has worse mean squared error.

• dim (int) – Dimension indexing time in the series.

• batch_dim (optional, int or iterator of int) – Dimensions indexing the batches. If provided, we assume that each row along these dimensions is a different sample from the same underlying distribution.

• use_fft (optional, bool) – Allows user to specify explicitly whether to use the FFT in the calculation. FFT is generally faster for longer time series, and slower for shorter ones. If not set, then we infer from the size of the data.

torchcast.utils.power_spectral_density(x: Tensor, sampling_frequency: float = 1.0, window_length: int | None = None, overlap: int = 0, dim: int = -1, batch_dim: int | Iterable[int] | None = None) → Tuple[Tensor, Tensor]

Calculates the power spectral density for a series, also called the periodogram:

\[P_{xx}(f) = \left| \mathcal{F}(x)(f) \right|^2\]

Where \(\mathcal{F}\) denotes the Fourier transformer. The calculation uses the Welch method from:

Welch, 1967. “The use of Fast Fourier Transform for the Estimation of Power Spectra: A Method Based on Time Averaging over Short, Modified Periodograms.” IEEE Transactions on Audio and Electroacoustic, Vol. AU-15, No. 2, pp. 70-73.

Parameters:

• x (torch.Tensor) – Tensor to calculate the power spectral density of.

• sampling_frequency (float) – Frequency of samples in the tensor.

• window_length (optional, int) – Length of window to use in Welch method. If not specified, defaults to the minimum of 256 and the length of the tensors.

• overlap (int) – Length of window overlap to use in Welch method.

• dim (int) – Dimension of time axis.

• batch_dim (optional, int or iterable of ints) – Dimension(s) of batch axes.