functional_time_series 0.0.1__tar.gz

functional_time_series-0.0.1/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.

functional_time_series-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,29 @@
+![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/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["poetry>=1.5"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "functional_time_series"
+version = "0.0.1"
+description = "DTC-IS module that fits a Functional Time Series to an input field of a Gaussian Random Field."
+authors = [
+    "Amber Leeson <a.leeson@lancaster.ac.uk>",
+    "DTC-IS consortium <support@dtc-ice-sheets.org>",
+]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/dtc-ice-sheets/functional_time_series"
+packages = [{ include = "functional_time_series", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.12,<4.0"
+numpy = "^2.3"
+# rpy2 = "^3.6.4"
+# pandas = "^2.3.3"
+xarray = "^2025.12.0"
+zarr = "^3.1.2"
+dask = { extras = ["array"], version = "^2026.8.0" }
+shapely = "^2.1.2"
+cyclopts = "^4.8.0"
+requests = "^2.34.2"
+aiohttp = "^3.14.1"
+rioxarray = "^0.19.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.2"
+typeguard = "^4.5.1"
+pre-commit = "^4.5"
+ruff = "^0.17.4"
+bandit = "^1.9.3"
+pytest-cov = "^7.0.0"
+sphinx = "^9.1.0"
+sphinx-rtd-theme = "^3.1.0"
+sphinx-copybutton = "^0.5.2"
+commitizen = "^4.12.1"
+pydoclint = "^0.8.3"
+pyproj = "^3.8.0"
+
+[tool.poetry.group.deployment.dependencies]
+dtc-wrapper = { git = "https://github.com/DTC-Ice-Sheets/dtc_wrapper.git", branch = "main" }
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+preview = true
+select = [
+    "T20", # Disallow print statements
+    "A",   # Ambiguity
+    "ANN", # Annotations
+    "B",   # Bad practices
+    "C90", # Complexity
+    "D",   # Documentation
+    "E",   # Errors
+    "F",   # Pyflakes (e.g. unused imports and vars)
+    "G",   # logging formatting
+    "I",   # Imports
+    "N",   # Naming
+    "Q",   # Quoting
+    "W",   # Warnings
+    "PT",  # pytest-style
+    "SIM", # flake8-simplify
+    "C4",  # flake8-comprehensions
+    "ARG", # flake8-unused-arguments
+    "PIE", # flake8-pie
+    "RUF", # Ruff-specific rules
+    "BLE", # Blind except
+    "RET", # Return statements
+    "PTH", # Use pathlib
+    "PD",  # Pandas
+]
+
+[tool.pydoclint]
+style = 'numpy'
+check_style_mismatch = "true"
+
+mccabe = { max-complexity = 10 }
+
+ignore = [
+    "D203", # One blank line required before class docstring (conflicts with D211)
+    "D204", # One blank line required after class docstring
+    "D205", # Docstring with no content
+    "D212", # Multi-line docstring summary should start at the second line
+    "D213", # Multi-line docstring summary should start at the first line
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "print",                            # Allow print statements in test files, as they are commonly used for debugging
+    "module-import-not-at-top-of-file", # Allow 'import' statements not being at the top of the file (common in test files for clarity)
+    "assert",                           # Allow the use of 'assert' statements in test files (common practice in pytest)
+    "undocumented-public-function",     # Ignore missing docstring warnings for functions in test files (commonly not required for small test functions)
+    "ANN",                              # Ignore missing type annotations for functions in test files (commonly not required for small test functions)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy" # Accepts: "google", "numpy", or "pep257"
+[tool.bandit.assert_used]
+skips = ['*_test.py', '*/test_*.py']
+
+[tool.pytest.ini_options]
+addopts = "--disable-warnings --cov functional_time_series --cov-fail-under=80"
+typeguard-packages = """functional_time_series"""
+typeguard-debug-instrumentation = true
+typeguard-forward-ref-policy = "ERROR"
+typeguard-collection-check-strategy = "ALL_ITEMS"
+markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]

functional_time_series-0.0.1/src/functional_time_series/__init__.py

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

functional_time_series-0.0.1/src/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-0.0.1/src/functional_time_series/fts_spatial_module/__init__.py

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

functional_time_series-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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)