functional_time_series 0.0.1__py3-none-any.whl

functional_time_series/__init__.py

@@ -0,0 +1 @@
+"""Functional Time Series package."""

functional_time_series/fts_spatial_entrypoint.py

@@ -0,0 +1,58 @@
+"""Entrypoint for FTS module."""
+
+import logging
+from pathlib import Path
+
+import cyclopts
+import xarray as xr
+
+from functional_time_series.fts_spatial_module.fts_spatial_module import FtsSpatialModule
+from functional_time_series.helpers import ZarrType, save_geo_zarr
+from functional_time_series.monitoring import setup_logging
+
+logger = logging.getLogger(__name__)
+
+app = cyclopts.App()
+
+
+@app.default
+def main(
+    data_path: ZarrType,
+    output_path: Path,
+    curve_time_points: int = 5,
+    num_pca: int = 2,
+    num_factors: int = 3,
+) -> None:
+    """Run the Functional Time Series module.
+
+    Parameters
+    ----------
+    data_path : ZarrType
+        Path of the input GeoZarr file.
+    output_path : Path
+        Path of the output GeoZarr file.
+    curve_time_points : int, optional
+        Number of time points to be considered as a single curve
+    num_pca : int, optional
+        Number of principal components to retain. Only the first feeds the second step, so this does not
+        change the result.
+    num_factors: int, optional
+        Number of factors to retain in the second step dimension reduction
+    """
+    setup_logging()
+
+    fts_module = FtsSpatialModule()
+    ds = xr.load_dataset(data_path, engine="zarr", chunks={})
+
+    output = fts_module.run_spatial_analysis(
+        ds,
+        curve_time_points=curve_time_points,
+        num_pca=num_pca,
+        num_factors=num_factors,
+    )
+
+    save_geo_zarr(output, output_path)
+
+
+if __name__ == "__main__":
+    app()

functional_time_series/fts_spatial_module/__init__.py

@@ -0,0 +1 @@
+"""Functional Time Series modules."""

functional_time_series/fts_spatial_module/fts_spatial_module.py

@@ -0,0 +1,202 @@
+"""Functional Time Series (FTS) module."""
+
+import logging
+
+import numpy as np
+import xarray as xr
+
+from functional_time_series.fts_spatial_module.hdfpca import hdfpca_factor_scores
+
+logger = logging.getLogger(__name__)
+
+
+class FtsSpatialModule:
+    """FTS module: compresses each point's time series into curve coefficients."""
+
+    @staticmethod
+    def spatial_variables(ds: xr.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
+        -------
+        list[str]
+            Names of the variables with dimensions ("time", "point_id"), in dataset order.
+        """
+        return [str(v) for v in ds.data_vars if set(ds[v].dims) == {"time", "point_id"}]
+
+    @staticmethod
+    def as_point_cloud(ds: xr.Dataset) -> xr.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
+        :func:`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
+        -------
+        xr.Dataset
+            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.
+        """
+        if FtsSpatialModule.spatial_variables(ds):
+            return ds
+        if "projection_x_coordinate" in ds.dims:
+            ds = ds.rename({"projection_x_coordinate": "x", "projection_y_coordinate": "y"})
+        if "x" not in ds.dims or "y" not in ds.dims:
+            return ds
+
+        ds = ds.stack({"point_id": ["x", "y"]})
+        names = FtsSpatialModule.spatial_variables(ds)
+        if not names:
+            return ds
+
+        # A variable can be empty at a whole timestep while the others are not. The GRF
+        # module fills a snapshot that has no spatial variation with the constant it
+        # already holds and writes NaN for its uncertainty, since no posterior was
+        # sampled - so the uncertainty field of a lake record arrives empty for the
+        # months when the lakes have drained. There is no curve to fit through a
+        # timestep with no values, and the mask below is shared, so leaving such a
+        # variable in would drop every point in the catchment rather than analysing
+        # what is there.
+        empty = [v for v in names if not np.isfinite(ds[v].values).any(axis=1).all()]
+        if empty:
+            logger.warning("not analysing %s: no values at all in at least one timestep", ", ".join(empty))
+            ds = ds.drop_vars(empty)
+            names = FtsSpatialModule.spatial_variables(ds)
+        if not names:
+            return ds
+
+        finite = np.all([np.isfinite(ds[v].values) for v in names], axis=(0, 1))
+        if not finite.all():
+            logger.warning(
+                "dropping %d of %d points that are not finite throughout the record", int((~finite).sum()), finite.size
+            )
+        return ds.isel(point_id=finite)
+
+    @staticmethod
+    def whole_curves(data: np.ndarray, curve_time_points: int, name: str = "data") -> np.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, optional
+            Variable name, used only in the warning.
+
+        Returns
+        -------
+        np.ndarray
+            The input, truncated to the first whole number of curves along the time axis.
+        """
+        n_times = data.shape[1]
+        n_whole = (n_times // curve_time_points) * curve_time_points
+        if n_whole != n_times:
+            logger.warning(
+                "%s: %d time points is not a multiple of %d; using the first %d",
+                name,
+                n_times,
+                curve_time_points,
+                n_whole,
+            )
+        return data[:, :n_whole]
+
+    def run_spatial_analysis(
+        self,
+        ds: xr.Dataset,
+        curve_time_points: int = 24,
+        num_pca: int = 2,
+        num_factors: int = 3,
+    ) -> xr.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 :func:`as_point_cloud` first.
+        curve_time_points : int, optional
+            Number of time points to be considered as a single curve
+        num_pca : int, optional
+            Number of principal components to retain. Only the first feeds the second step, so this does
+            not change the result.
+        num_factors: int, optional
+            Number of factors to retain in the second step dimension reduction
+
+        Returns
+        -------
+        xr.Dataset
+            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.
+
+        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.
+        """
+        ds = self.as_point_cloud(ds)
+        names = self.spatial_variables(ds)
+        if not names:
+            raise ValueError(
+                "no variable has the dimensions time and point_id, and the dataset is not a grid that can "
+                f"be flattened into them, so there is nothing to analyse: found {list(ds.data_vars)} over "
+                f"dimensions {list(ds.dims)}",
+            )
+
+        data_vars = {}
+        for var in names:
+            data = self.whole_curves(ds[var].transpose("point_id", "time").values, curve_time_points, var)
+            result = hdfpca_factor_scores(data, curve_time_points, num_pca, num_factors)
+            data_vars[var] = (("curve_id", "coef_id"), result)
+
+        output = xr.Dataset(
+            data_vars=data_vars,
+            coords={
+                "curve_id": np.arange(ds.sizes["time"] // curve_time_points),
+                "coef_id": np.arange(num_factors),
+            },
+        )
+        if "spatial_ref" in ds:
+            output = output.assign_coords(spatial_ref=ds["spatial_ref"].copy(deep=True))
+        return output

functional_time_series/fts_spatial_module/hdfpca.py

@@ -0,0 +1,252 @@
+"""
+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.
+"""
+
+import numpy as np
+
+# hdpca's h0: the number of lags summed in the second step.
+LONG_RUN_LAGS = 5
+
+
+def 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, optional
+        Half-width of the flat top.
+
+    Returns
+    -------
+    float
+        The kernel weight at `x`.
+    """
+    if -1 < x <= -c:
+        return (x + 1) / (1 - c)
+    if -c < x < c:
+        return 1.0
+    if c < x < 1:
+        return (x - 1) / (c - 1)
+    return 0.0
+
+
+def descending_eigenvectors(matrix: np.ndarray, order: int) -> np.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
+    -------
+    np.ndarray
+        Array of shape (..., n, order), one eigenvector per column.
+    """
+    _, vectors = np.linalg.eigh(matrix, UPLO="L")
+    return vectors[..., ::-1][..., :order]
+
+
+def dynamic_fpca_scores(curves: np.ndarray, order: int) -> np.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
+    -------
+    np.ndarray
+        Array of shape (n_points, n_curves, order).
+    """
+    n_curves = curves.shape[1]
+    bandwidth = np.sqrt(n_curves)
+    centred = curves - curves.mean(axis=1, keepdims=True)
+
+    long_run = np.einsum("pti,ptj->pij", centred, centred) / n_curves
+    for lag in range(1, n_curves):
+        # R stores lag `lag` at index h = lag + 1 and weights it by h / bandwidth, not lag / bandwidth.
+        h = lag + 1
+        forward = flat_top_weight(h / bandwidth)
+        backward = flat_top_weight(-h / bandwidth)
+        if forward == 0 and backward == 0:
+            continue
+        autocovariance = np.einsum("pti,ptj->pij", centred[:, lag:], centred[:, : n_curves - lag]) / n_curves
+        long_run += forward * autocovariance + backward * np.swapaxes(autocovariance, 1, 2)
+
+    return centred @ descending_eigenvectors(long_run, order)
+
+
+def column_space_factor_directions(centred: np.ndarray, order: int) -> np.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
+    -------
+    np.ndarray
+        Array of shape (n_columns, order), one eigenvector per column.
+    """
+    n_rows = centred.shape[0]
+    f = np.zeros((centred.shape[1], centred.shape[1]))
+    for h in range(1, LONG_RUN_LAGS + 1):
+        lagged = centred[h:].T @ centred[: n_rows - h] / (n_rows - h)
+        f += lagged @ lagged.T
+    return descending_eigenvectors(f, order)
+
+
+def row_space_factor_directions(centred: np.ndarray, order: int) -> np.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
+    -------
+    np.ndarray
+        Array of shape (n_columns, order), one eigenvector per column.
+    """
+    n_rows = centred.shape[0]
+    weight = np.zeros((n_rows, n_rows))
+    for h in range(1, LONG_RUN_LAGS + 1):
+        earlier = centred[: n_rows - h]
+        weight[h:, h:] += earlier @ earlier.T / (n_rows - h) ** 2
+
+    values, vectors = np.linalg.eigh(weight)
+    z = (vectors * np.sqrt(np.clip(values, 0, None))).T @ centred
+    _, _, right = np.linalg.svd(z, full_matrices=False)
+    return right[:order].T
+
+
+def factor_scores(x: np.ndarray, order: int) -> np.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
+    -------
+    np.ndarray
+        Array of shape (n_rows, order).
+
+    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.
+    """
+    n_rows, n_columns = x.shape
+    if n_rows <= LONG_RUN_LAGS:
+        raise ValueError(
+            f"{n_rows} curves is too few: the second step sums autocovariances over lags 1 to {LONG_RUN_LAGS}, so it "
+            f"needs at least {LONG_RUN_LAGS + 1}"
+        )
+    if order > min(n_rows, n_columns):
+        raise ValueError(
+            f"cannot keep {order} factors from {n_rows} curves at {n_columns} points; at most "
+            f"{min(n_rows, n_columns)} are available"
+        )
+
+    centred = x - x.mean(axis=0)
+    if n_columns <= n_rows:
+        scores = centred @ column_space_factor_directions(centred, order)
+    else:
+        scores = centred @ row_space_factor_directions(centred, order)
+
+    largest = scores[np.abs(scores).argmax(axis=0), np.arange(order)]
+    return scores * np.where(largest < 0, -1.0, 1.0)
+
+
+def hdfpca_factor_scores(
+    data: np.ndarray,
+    curve_time_points: int,
+    num_pca: int,
+    num_factors: int,
+) -> np.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
+    -------
+    np.ndarray
+        Array of shape (n_curves, num_factors).
+    """
+    n_points, n_times = data.shape
+    curves = np.asarray(data, dtype=np.float64).reshape(n_points, n_times // curve_time_points, curve_time_points)
+    first_component = dynamic_fpca_scores(curves, num_pca)[:, :, 0]
+    return factor_scores(first_component.T, num_factors)

functional_time_series/helpers.py

@@ -0,0 +1,136 @@
+"""Utility functions for use across functional_time_series modules."""
+
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import numpy as np
+import rioxarray  # ruff:ignore[unused-import]
+import xarray as xr
+from cyclopts import Parameter
+
+logger = logging.getLogger(__name__)
+
+
+def path_or_web_url_validator(type_: object, path_or_url: Path | str) -> str:  # ruff:ignore[unused-function-argument] - needed type_ to match cyclopts validator signature
+    """Validate that the provided path is either a valid local path or a web URL.
+
+    NOTE: Path("") resolves to the current directory (".") - which is considered a valid path.
+
+    Parameters
+    ----------
+    type_ : object
+        The type of the argument being validated - unused, purely required for cyclopts validator compatibility.
+    path_or_url : Path | str
+        The candidate path or URL to validate.
+
+    Returns
+    -------
+    str
+        The validated path or URL as a string.
+
+    Raises
+    ------
+    ValueError
+        If the provided path is neither a valid local path nor a web URL.
+    """
+    if not Path(path_or_url).exists() and not str(path_or_url).startswith(("http://", "https://")):
+        raise ValueError(f"The provided path '{path_or_url}' is neither a valid local path nor a web URL.")
+    return str(path_or_url)
+
+
+# Alias for use in cyclopts Parameter definitions.
+# Override the sphinx documentation entry in the lines below since cyclopts doesn't produce nice results for
+# custom validators:
+#: A local path or web URL, represented as a string.
+#:
+#: Validated by :func:`path_or_web_url_validator`.
+#:
+#: :meta hide-value:
+type ZarrType = Annotated[str, Parameter(validator=path_or_web_url_validator)]
+
+
+def save_geo_zarr(ds: xr.Dataset, zarr_path: Path | str, target_chunk_size: str = "1024MB") -> None:
+    """Save dataset to GeoZarr adhering to CF conventions (https://cfconventions.org/).
+
+    Parameters
+    ----------
+    ds: xr.Dataset
+        The xarray dataset to save. This must follow the GeoZarr format,
+        including having a `spatial_ref` attribute with a valid CRS.
+    zarr_path: Path | str
+        Full path of the output .zarr file to be created.
+    target_chunk_size: str, optional
+        The target chunk size for the GeoZarr dataset, by default "1024MB".
+    """
+    ds = ds.rio.write_crs(ds["spatial_ref"].attrs["crs_wkt"], grid_mapping_name="spatial_ref")
+    ds = ds.reset_coords("spatial_ref")
+    if "time" in ds:
+        ds["time"] = prepare_cf_time_data_array(ds["time"])
+    # Prepare the spatial variables with the required attributes for GeoZarr.
+    for name, axis in (("x", "X"), ("y", "Y")):
+        if name in ds:
+            ds[name] = prepare_cf_spatial_data_array(ds[name], name=name, axis=axis)
+    ds = prepare_cf_data_variable_arrays(ds)
+
+    ds.attrs = {"_ARRAY_DIMENSIONS": ["spatial_ref", *sorted(ds.dims)]}
+    ds = ds.chunk(chunks=target_chunk_size)
+
+    ds.to_zarr(
+        str(zarr_path),
+        mode="w",
+        zarr_format=2,
+        consolidated=True,
+    )
+
+
+def prepare_cf_data_variable_arrays(ds: xr.Dataset) -> xr.Dataset:
+    """Assign CF grid-mapping and fill-value metadata to dataset variables."""
+    for name in ds.variables:
+        variable = ds[name]
+        # Do not reuse source packing, time units, compression, or chunk encodings.
+        variable.encoding = {"coordinates": None}
+        if name != "spatial_ref":
+            variable.attrs["grid_mapping"] = "spatial_ref"
+
+        dtype = variable.dtype
+        fill_value = None
+        if variable.ndim:
+            if np.issubdtype(dtype, np.unsignedinteger):
+                fill_value = np.iinfo(dtype).max
+            else:
+                fill_value = {"f": -9999.0, "i": -9999, "b": 0, "U": ""}.get(dtype.kind)
+        # We want to preserve NaNs so set the _FillValue in .attrs, rather than .encoding.
+        variable.attrs["_FillValue"] = fill_value
+    return ds
+
+
+def prepare_cf_spatial_data_array(
+    spatial_data_array: xr.DataArray,
+    name: str,
+    axis: str,
+) -> xr.DataArray:
+    """Assign the required GeoZarr attributes to a spatial coordinate."""
+    return spatial_data_array.assign_attrs(
+        variable_name_override=name,
+        standard_name=f"projection_{name}_coordinate",
+        long_name=f"projection_{name}_coordinate",
+        units="m",
+        axis=axis,
+    )
+
+
+def prepare_cf_time_data_array(time_data_array: xr.DataArray) -> xr.DataArray:
+    """Convert a time coordinate to numeric epoch seconds with legacy CF metadata."""
+    logger.info("Converting type %s to seconds since epoch", time_data_array.dtype)
+    time_data_array = time_data_array.astype("datetime64[s]").astype("float64")
+    return time_data_array.assign_attrs(
+        {
+            "standard_name": "time",
+            "long_name": "time",
+            "axis": "T",
+            "bounds": "time_bnds",
+            "units": "seconds since 1970-01-01T00:00:00",
+            "calendar": "standard",
+        }
+    )

functional_time_series/monitoring.py

@@ -0,0 +1,25 @@
+"""Monitoring and logging tools."""
+
+import logging
+
+
+def setup_logging() -> None:
+    """
+    Set up root logger.
+
+    This configuration will be inherited by all module-level loggers created within the package.
+    """
+    # Create the root logger
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+    # Create a console handler and set the level to info
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+
+    # Create a formatter and set it for the console handler
+    formatter = logging.Formatter("[%(asctime)s] %(levelname)s in %(name)s: %(message)s")
+    console_handler.setFormatter(formatter)
+
+    # Add the console handler to the root logger
+    logger.addHandler(console_handler)

functional_time_series-0.0.1.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: functional_time_series
+Version: 0.0.1
+Summary: DTC-IS module that fits a Functional Time Series to an input field of a Gaussian Random Field.
+License: MIT
+License-File: LICENSE
+Author: Amber Leeson
+Author-email: a.leeson@lancaster.ac.uk
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: aiohttp (>=3.14.1,<4.0.0)
+Requires-Dist: cyclopts (>=4.8.0,<5.0.0)
+Requires-Dist: dask[array] (>=2026.8.0,<2027.0.0)
+Requires-Dist: numpy (>=2.3,<3.0)
+Requires-Dist: requests (>=2.34.2,<3.0.0)
+Requires-Dist: rioxarray (>=0.19.0,<0.20.0)
+Requires-Dist: shapely (>=2.1.2,<3.0.0)
+Requires-Dist: xarray (>=2025.12.0,<2026.0.0)
+Requires-Dist: zarr (>=3.1.2,<4.0.0)
+Project-URL: Homepage, https://github.com/dtc-ice-sheets/functional_time_series
+Description-Content-Type: text/markdown
+
+![Tests](https://github.com/dtc-ice-sheets/functional_time_series/actions/workflows/functional_time_series_test.yml/badge.svg)
+![Deployment](https://github.com/dtc-ice-sheets/functional_time_series/actions/workflows/functional_time_series_deploy.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DTC-Ice-Sheets/functional_time_series/blob/main/LICENSE)
+
+# DTC-IS _Functional Time Series_
+
+The `functional_time_series` module is a sub-component of the
+[Digital Twin Component for Ice Sheets (DTC-IS)](https://dtc-ice-sheets.org/), an ESA-funded, EO-driven digital twin project.
+
+The `functional_time_series` module enables users to fit a continuous model to an input gaussian random field of 
+values such as surface meltwater runoff or supraglacial lake intensity."
+
+For an in-depth overview of the functional_time_series module please [read the docs](https://dtc-ice-sheets.github.io/functional_time_series/).
+
+The documentation includes sections on:
+
+1. [Getting started](https://dtc-ice-sheets.github.io/functional_time_series/quick-start.html)
+1. [Scientific overview](https://dtc-ice-sheets.github.io/functional_time_series/overview.html)
+1. [API reference](https://dtc-ice-sheets.github.io/functional_time_series/api.html)
+
+For a more interactive way of exploring the system, please visit the digital twin's [dashboard](https://dashboards.dtc-ice-sheets.org/).
+
+## Installation for Use
+
+You can install this package with pip:
+
+``` bash
+pip install functional_time_series
+```
+

functional_time_series-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+functional_time_series/__init__.py,sha256=a2_Tnpiytoo3C3wQAQYWB5YoXNo0jP-acKRy_UTCZPY,38
+functional_time_series/fts_spatial_entrypoint.py,sha256=DM9Q6wQE_jHcnjaGRI950bs8X-ZA6ZneD6KvzgvaQms,1502
+functional_time_series/fts_spatial_module/__init__.py,sha256=6i2M5fdUBP86xopcqgOB51YqBMcQk3CDzCR90S-cN-c,38
+functional_time_series/fts_spatial_module/fts_spatial_module.py,sha256=R_4IUVtifY8OwRxav9QkgCiqwB11uAWFgFN7CwcpuTM,8588
+functional_time_series/fts_spatial_module/hdfpca.py,sha256=t9kL4vG27rZ-CJ_HDUyybFM5JDdgSNIxFUUVM6oNWBE,9618
+functional_time_series/helpers.py,sha256=FEZoyiYVN2LsP8KksQ_N9O5lwCeQFnr72G27gvA3vt8,4968
+functional_time_series/monitoring.py,sha256=03Mm_O6VxZl0Nz-7zgj3hvmh9zPs8jZanoHpLBHDPdo,748
+functional_time_series-0.0.1.dist-info/METADATA,sha256=HVGwfDxmlaOaYaqCvNAhNPJoJHgoAwKz6PCpGP3zgp8,2627
+functional_time_series-0.0.1.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+functional_time_series-0.0.1.dist-info/licenses/LICENSE,sha256=550GeDi9mZblNmslE2iTQPbRBf1O3Nz45lkVyrlS4ho,1081
+functional_time_series-0.0.1.dist-info/RECORD,,

functional_time_series-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any

functional_time_series-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2026 DTC-Ice-Sheets (DTC-IS) consortium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the “Software”), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.