functional_time_series.fts_spatial_module.hdfpca

NumPy port of the part of hdfpca from the R package hdftsa that the FTS module uses.

hdfpca (Gao, Shang and Yang, 2019) reduces a panel of functional time series in two steps. First, each point’s series of curves is reduced by dynamic functional principal component analysis (dfpca), which takes the eigenvectors of a long-run covariance rather than of the plain covariance. Second, the scores of the first principal component from every point are stacked side by side and reduced again (hdpca), this time using the eigenvectors of a sum of lagged autocovariance products. The FTS module keeps only the scores from that second step, so this port stops there and leaves out the rest of hdfpca and the forecast that forecast.hdfpca builds on top of it.

The sources ported are hdfpca.R, dfpca.R, hdpca.R and wtflat.R from hdftsa 1.1.

Functions

column_space_factor_directions(centred, order)

Leading eigenvectors of hdpca's f, built directly as R builds it.

descending_eigenvectors(matrix, order)

Eigenvectors of the leading order eigenvalues of one or more symmetric matrices, largest first.

dynamic_fpca_scores(curves, order)

Principal component scores of each point's curves, ported from hdftsa's dfpca.

factor_scores(x, order)

Scores of the leading factors of a panel of series, ported from the coef that hdftsa's hdpca returns.

flat_top_weight(x[, c])

Flat-top kernel weight, ported from hdftsa's wtflat.

hdfpca_factor_scores(data, ...)

Compute the factor scores of the first principal component, as hdfpca(...)$model$model2[[1]]$coef in hdftsa.

row_space_factor_directions(centred, order)

Leading eigenvectors of hdpca's f, found without building f.

column_space_factor_directions(centred: ndarray, order: int) → ndarray

Leading eigenvectors of hdpca’s f, built directly as R builds it.

f is the sum over lags 1 to 5 of C_h C_hᵀ, where C_h is the lag-h autocovariance between columns, so it is n_columns square. That is cheap when there are few columns.

Parameters:
  • centred (np.ndarray) – Array of shape (n_rows, n_columns), with each column’s mean removed.

  • order (int) – Number of eigenvectors to keep.

Returns:

Array of shape (n_columns, order), one eigenvector per column.

Return type:

np.ndarray

descending_eigenvectors(matrix: ndarray, order: int) → ndarray

Eigenvectors of the leading order eigenvalues of one or more symmetric matrices, largest first.

Like R’s eigen(symmetric = TRUE), only the lower triangle is read.

Parameters:
  • matrix (np.ndarray) – Array of shape (…, n, n).

  • order (int) – Number of eigenvectors to keep.

Returns:

Array of shape (…, n, order), one eigenvector per column.

Return type:

np.ndarray

dynamic_fpca_scores(curves: ndarray, order: int) → ndarray

Principal component scores of each point’s curves, ported from hdftsa’s dfpca.

R loops over every lag and multiplies its autocovariance by the kernel weight, so it builds lags whose weight is zero. Those lags are skipped here, which leaves roughly the square root of the number of curves to compute.

Parameters:
  • curves (np.ndarray) – Array of shape (n_points, n_curves, curve_time_points).

  • order (int) – Number of principal components to keep.

Returns:

Array of shape (n_points, n_curves, order).

Return type:

np.ndarray

factor_scores(x: ndarray, order: int) → ndarray

Scores of the leading factors of a panel of series, ported from the coef that hdftsa’s hdpca returns.

R takes the eigenvectors of f, a matrix that is n_columns square. A column here is a spatial point, so for a grid f can have tens of thousands of rows, while a row is a curve, of which there are usually few. The eigenvectors are therefore found from whichever of the columns or the rows is smaller; both give the same result.

An eigenvector’s sign is arbitrary, and R and NumPy may pick differently, so each column of scores is flipped to make its largest-magnitude entry positive. R’s result therefore agrees with this one up to the sign of each column.

Parameters:
  • x (np.ndarray) – Array of shape (n_rows, n_columns): one row per time step, one column per series.

  • order (int) – Number of factors to keep.

Returns:

Array of shape (n_rows, order).

Return type:

np.ndarray

Raises:

ValueError – If there are too few rows for the lags summed, or more factors are asked for than the data can supply. hdftsa stops with “subscript out of bounds” for too few rows, or for more factors than columns. Given more factors than rows but no more than columns, it returns scores along eigenvectors whose eigenvalue is zero, which are arbitrary; this refuses that case too.

flat_top_weight(x: float, c: float = 0.5) → float

Flat-top kernel weight, ported from hdftsa’s wtflat.

The weight is 1 on (-c, c) and falls linearly to 0 at -1 and 1. The R function uses a strict c < x on its rising edge, so x == c falls through to 0 while x == -c gives 1. The quirk is kept so that results match R exactly; it only matters when the number of curves is four times a square.

Parameters:
  • x (float) – Point at which to evaluate the kernel.

  • c (float) – Half-width of the flat top.

Returns:

The kernel weight at x.

Return type:

float

hdfpca_factor_scores(data: ndarray, curve_time_points: int, num_pca: int, num_factors: int) → ndarray

Compute the factor scores of the first principal component, as hdfpca(...)$model$model2[[1]]$coef in hdftsa.

Only the first principal component of each point feeds the second step, so num_pca does not change the result beyond needing to be at least 1. The data is converted to float64 first, as R works in double precision whatever the input.

Parameters:
  • data (np.ndarray) – Array of shape (n_points, n_times), with n_times a whole multiple of curve_time_points.

  • curve_time_points (int) – Number of time points in one curve.

  • num_pca (int) – Number of principal components to keep in the first step.

  • num_factors (int) – Number of factors to keep in the second step.

Returns:

Array of shape (n_curves, num_factors).

Return type:

np.ndarray

row_space_factor_directions(centred: ndarray, order: int) → ndarray

Leading eigenvectors of hdpca’s f, found without building f.

Each C_h C_hᵀ in f equals centredᵀ M_h centred for a matrix M_h that is only n_rows square, so f is Zᵀ Z for a Z with n_rows rows, and its eigenvectors are the right singular vectors of Z. That is cheap when there are few rows, which for a grid of points is the usual case.

Parameters:
  • centred (np.ndarray) – Array of shape (n_rows, n_columns), with each column’s mean removed.

  • order (int) – Number of eigenvectors to keep.

Returns:

Array of shape (n_columns, order), one eigenvector per column.

Return type:

np.ndarray