functional_time_series.fts_spatial_module.fts_spatial_module

Functional Time Series (FTS) module.

Classes

FtsSpatialModule()

FTS module: compresses each point's time series into curve coefficients.

class FtsSpatialModule

Bases: object

FTS 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-whole nn = tt/delta rounds 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