functional_time_series.fts_spatial_module.fts_spatial_module
Functional Time Series (FTS) module.
Classes
FTS module: compresses each point's time series into curve coefficients. |
- class FtsSpatialModule
Bases:
objectFTS module: compresses each point’s time series into curve coefficients.
- static as_point_cloud(ds: Dataset) Dataset
Flatten a gridded dataset into the point cloud form this module analyses.
The GRF module interpolates its fit onto a regular grid before saving, so its published output has the dimensions (“time”, “x”, “y”) rather than (“time”, “point_id”). Without this step
spatial_variables()matches nothing, every variable is dropped, and the result is an empty dataset with no warning. Cells outside the fitted area are NaN and a curve cannot be built across a gap, so a point is kept only where every variable is finite at every timestep.- Parameters:
ds (xr.Dataset) – The input dataset, either already a point cloud carrying a “point_id” dimension, or a grid carrying x and y dimensions under those names or the old “projection_x_coordinate” and “projection_y_coordinate”.
- Returns:
The same data with the two spatial dimensions stacked into “point_id”, any variable that is empty at a whole timestep removed, and the points that are not finite throughout the record removed. A dataset that is already a point cloud, or that is neither form, is returned unchanged.
- Return type:
xr.Dataset
- run_spatial_analysis(ds: Dataset, curve_time_points: int = 24, num_pca: int = 2, num_factors: int = 3) Dataset
Run spatial analysis on the given dataset.
- Parameters:
ds (xr.Dataset) –
The input dataset for analysis. This must have the following dimensions:
time
point_id (flattened spatial coordinates)
Each of the spatial variables with dimensions (“time”, “point_id”) will be analyzed. A gridded dataset with x and y dimensions in place of point_id is accepted too, and is flattened by
as_point_cloud()first.curve_time_points (int) – Number of time points to be considered as a single curve
num_pca (int) – Number of principal components to retain. Only the first feeds the second step, so this does not change the result.
num_factors (int) – Number of factors to retain in the second step dimension reduction
- Returns:
The output dataset containing the model results, with dimensions:
curve_id (length equal to the number of time points divided by curve_time_points, rounded down)
coef_id (length equal to num_factors)
Each of the input spatial variables will have a corresponding variable of the same name, with dimensions (“curve_id”, “coef_id”). The input spatial_ref variable and its CRS metadata are preserved as a coordinate, if present. Any other input variables will be discarded.
- Return type:
xr.Dataset
- Raises:
ValueError – If the dataset holds no variable this module can analyse. Returning an empty dataset instead would record the run as a success and leave the caller with a store holding no data.
- static spatial_variables(ds: Dataset) list[str]
Names of the variables to analyse: those with exactly the dimensions time and point_id.
- Parameters:
ds (xr.Dataset) – The input dataset.
- Returns:
Names of the variables with dimensions (“time”, “point_id”), in dataset order.
- Return type:
list[str]
- static whole_curves(data: ndarray, curve_time_points: int, name: str = 'data') ndarray
Truncate the time axis to a whole number of curves.
Every curve needs exactly curve_time_points values, so any time steps left over after the last whole curve are dropped, with a warning.
This matches hdftsa as called from R. There,
matrix(Coeff[k, ], delta, nn)with a non-wholenn = tt/deltarounds the number of curves down and drops the same trailing values, so the result is identical. The differences are that R does it silently apart from one R warning per point, while this logs a single warning per variable.- Parameters:
data (np.ndarray) – Array of shape (n_points, n_times).
curve_time_points (int) – Number of time points in one curve.
name (str) – Variable name, used only in the warning.
- Returns:
The input, truncated to the first whole number of curves along the time axis.
- Return type:
np.ndarray