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
|
Leading eigenvectors of hdpca's |
|
Eigenvectors of the leading order eigenvalues of one or more symmetric matrices, largest first. |
|
Principal component scores of each point's curves, ported from hdftsa's |
|
Scores of the leading factors of a panel of series, ported from the |
|
Flat-top kernel weight, ported from hdftsa's |
|
Compute the factor scores of the first principal component, as |
|
Leading eigenvectors of hdpca's |
- column_space_factor_directions(centred: ndarray, order: int) ndarray
Leading eigenvectors of hdpca’s
f, built directly as R builds it.fis the sum over lags 1 to 5 ofC_h C_hᵀ, whereC_his 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
coefthat hdftsa’shdpcareturns.R takes the eigenvectors of
f, a matrix that is n_columns square. A column here is a spatial point, so for a gridfcan 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 < xon its rising edge, sox == cfalls through to 0 whilex == -cgives 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]]$coefin 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 buildingf.Each
C_h C_hᵀinfequalscentredᵀ M_h centredfor a matrixM_hthat is only n_rows square, sofisZᵀ Zfor aZwith n_rows rows, and its eigenvectors are the right singular vectors ofZ. 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