fdatools 1.1.0__py3-none-any.whl

fdatools/__init__.py

@@ -0,0 +1,107 @@
+"""fdatools: functional data analysis for Python.
+
+A clean-room, production-grade Python implementation of the functional data
+analysis toolkit described in Ramsay & Silverman, *Functional Data Analysis*.
+
+Examples
+--------
+>>> import numpy as np
+>>> import fdatools as fdt
+>>> basis = fdt.BSpline(domain=(0.0, 1.0), n_basis=5)
+>>> basis(np.array([0.0, 0.5, 1.0])).shape
+(3, 5)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from fdatools import datasets, density, profiling, sparse, stats
+from fdatools.basis import (
+    Basis,
+    BSpline,
+    Constant,
+    Exponential,
+    Fourier,
+    Monomial,
+    Polygonal,
+    Power,
+)
+from fdatools.core import LDO, BiFData, FData, inprod
+from fdatools.decomposition import FCCA, FPCA
+from fdatools.density import DensityResult, IntensityResult, fit_density, fit_intensity
+from fdatools.dynamics import PDA, PDAStability, phase_plane
+from fdatools.io import from_pandas, read_rds, to_pandas, to_xarray
+from fdatools.profiling import ODEModel, ProfiledODE, profile_ode
+from fdatools.registration import Registrator, landmark_register, register
+from fdatools.regression import FRegress, LinmodResult, fregress, linmod
+from fdatools.smoothing import Smoother, SmoothResult, smooth
+from fdatools.sparse import PACE, SparseCov, sparse_cov, sparse_mean
+
+if TYPE_CHECKING:
+    from fdatools import nn as nn
+
+__all__ = [
+    "FCCA",
+    "FPCA",
+    "LDO",
+    "PACE",
+    "PDA",
+    "BSpline",
+    "Basis",
+    "BiFData",
+    "Constant",
+    "DensityResult",
+    "Exponential",
+    "FData",
+    "FRegress",
+    "Fourier",
+    "IntensityResult",
+    "LinmodResult",
+    "Monomial",
+    "ODEModel",
+    "PDAStability",
+    "Polygonal",
+    "Power",
+    "ProfiledODE",
+    "Registrator",
+    "SmoothResult",
+    "Smoother",
+    "SparseCov",
+    "__version__",
+    "datasets",
+    "density",
+    "fit_density",
+    "fit_intensity",
+    "fregress",
+    "from_pandas",
+    "inprod",
+    "landmark_register",
+    "linmod",
+    "phase_plane",
+    "profile_ode",
+    "profiling",
+    "read_rds",
+    "register",
+    "smooth",
+    "sparse",
+    "sparse_cov",
+    "sparse_mean",
+    "stats",
+    "to_pandas",
+    "to_xarray",
+]
+
+__version__ = "1.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    """Import the optional :mod:`fdatools.nn` module on first access.
+
+    ``import fdatools`` never imports PyTorch; ``fdatools.nn`` loads it lazily.
+    """
+    if name == "nn":
+        import importlib
+
+        module = importlib.import_module("fdatools.nn")
+        globals()["nn"] = module
+        return module
+    raise AttributeError(f"module 'fdatools' has no attribute {name!r}")

fdatools/_backend.py

@@ -0,0 +1,219 @@
+"""Array-API dispatch for fdatools.
+
+This is the *only* module (together with :mod:`fdatools._linalg`) that is allowed to
+import NumPy directly.  Every other module obtains its array namespace through
+:func:`array_namespace` and calls ``xp.*`` functions, so that a NumPy input
+produces a NumPy output and a PyTorch input produces a PyTorch output with
+gradients flowing through.
+
+Examples
+--------
+>>> import numpy as np
+>>> from fdatools import _backend as be
+>>> xp = be.array_namespace(np.zeros(3))
+>>> be.asarray([1, 2, 3]).dtype
+dtype('float64')
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Any, cast
+
+import array_api_compat
+import numpy as np
+
+__all__ = [
+    "array_namespace",
+    "asarray",
+    "default_namespace",
+    "is_torch",
+    "result_namespace",
+    "to_numpy",
+]
+
+_DEFAULT_NAMESPACE: ModuleType = array_api_compat.array_namespace(np.empty(0))
+
+
+def default_namespace() -> ModuleType:
+    """Return the fallback array namespace (NumPy).
+
+    Returns
+    -------
+    module
+        The array-API compatible NumPy namespace.
+
+    Examples
+    --------
+    >>> from fdatools._backend import default_namespace
+    >>> default_namespace().__name__.endswith("numpy")
+    True
+    """
+    return _DEFAULT_NAMESPACE
+
+
+def array_namespace(*xs: Any) -> ModuleType:
+    """Return the array-API namespace shared by ``xs``.
+
+    Python scalars, ``None`` and plain sequences are ignored; if no argument is an
+    array the NumPy namespace is returned.  If any argument is a
+    :class:`torch.Tensor` the PyTorch namespace is returned, so tensors in give
+    tensors out.
+
+    Parameters
+    ----------
+    *xs : object
+        Candidate arrays, scalars or ``None``.
+
+    Returns
+    -------
+    module
+        An array-API compatible namespace.
+
+    Raises
+    ------
+    TypeError
+        If ``xs`` mixes arrays from two different array libraries.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from fdatools._backend import array_namespace
+    >>> array_namespace(np.zeros(2), 1.0).__name__.endswith("numpy")
+    True
+    """
+    arrays = [x for x in xs if array_api_compat.is_array_api_obj(x)]
+    if not arrays:
+        return _DEFAULT_NAMESPACE
+    namespace: ModuleType = array_api_compat.array_namespace(*arrays)
+    return namespace
+
+
+def result_namespace(*xs: Any) -> ModuleType:
+    """Return the namespace an operation over ``xs`` should compute in.
+
+    Unlike :func:`array_namespace`, a NumPy operand does not conflict with a
+    third-party one: NumPy data is promotable, so mixing NumPy coefficients with
+    a PyTorch argument gives the PyTorch namespace (and a differentiable
+    result).  Two different non-NumPy libraries still conflict.
+
+    Parameters
+    ----------
+    *xs : object
+        Candidate arrays, scalars or ``None``.
+
+    Returns
+    -------
+    module
+        An array-API compatible namespace.
+
+    Raises
+    ------
+    TypeError
+        If ``xs`` mixes arrays from two different non-NumPy libraries.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from fdatools._backend import result_namespace
+    >>> result_namespace(np.zeros(2), None).__name__.endswith("numpy")
+    True
+    """
+    spaces = [
+        array_api_compat.array_namespace(x) for x in xs if array_api_compat.is_array_api_obj(x)
+    ]
+    foreign = [space for space in spaces if space is not _DEFAULT_NAMESPACE]
+    if not foreign:
+        return _DEFAULT_NAMESPACE
+    if any(space is not foreign[0] for space in foreign[1:]):
+        raise TypeError(f"cannot mix array namespaces {sorted({s.__name__ for s in foreign})}")
+    return cast("ModuleType", foreign[0])
+
+
+def asarray(x: Any, xp: ModuleType | None = None, dtype: Any = float) -> Any:
+    """Convert ``x`` to an array in namespace ``xp``.
+
+    Parameters
+    ----------
+    x : array_like
+        Value to convert.  Arrays are returned unchanged when the namespace and
+        dtype already match, so autograd graphs are preserved.
+    xp : module, optional
+        Target namespace.  Defaults to the namespace of ``x``.
+    dtype : dtype-like, optional
+        Target dtype.  The default, the builtin :class:`float`, maps to the
+        namespace's ``float64``.  Pass ``None`` to keep ``x``'s dtype.
+
+    Returns
+    -------
+    array
+        ``x`` as an array of namespace ``xp``.
+
+    Examples
+    --------
+    >>> from fdatools._backend import asarray
+    >>> asarray([1, 2, 3]).dtype
+    dtype('float64')
+    """
+    if xp is None:
+        xp = array_namespace(x)
+    resolved = xp.float64 if dtype is float else dtype
+    if array_api_compat.is_array_api_obj(x) and array_namespace(x) is xp:
+        if resolved is None or x.dtype == resolved:
+            return x
+        return xp.astype(x, resolved)
+    if isinstance(x, np.ndarray) and not x.flags.writeable:
+        x = np.array(x)
+    if resolved is None:
+        return xp.asarray(x)
+    return xp.asarray(x, dtype=resolved)
+
+
+def to_numpy(x: Any) -> np.ndarray[Any, np.dtype[Any]]:
+    """Convert ``x`` to a NumPy array, detaching autograd tensors if needed.
+
+    Parameters
+    ----------
+    x : array_like
+        Array from any supported backend, or anything :func:`numpy.asarray`
+        accepts.
+
+    Returns
+    -------
+    numpy.ndarray
+        A NumPy view or copy of ``x``.
+
+    Examples
+    --------
+    >>> from fdatools._backend import to_numpy
+    >>> to_numpy([1.0, 2.0]).tolist()
+    [1.0, 2.0]
+    """
+    if array_api_compat.is_torch_array(x):
+        return np.asarray(x.detach().cpu().numpy())
+    return np.asarray(x)
+
+
+def is_torch(x: Any) -> bool:
+    """Return whether ``x`` is a PyTorch tensor.
+
+    Does not import PyTorch if it has not been imported already.
+
+    Parameters
+    ----------
+    x : object
+        Candidate value.
+
+    Returns
+    -------
+    bool
+        ``True`` if ``x`` is a :class:`torch.Tensor`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from fdatools._backend import is_torch
+    >>> is_torch(np.zeros(2))
+    False
+    """
+    return bool(array_api_compat.is_torch_array(x))

fdatools/_data/gait.json

@@ -0,0 +1 @@
+{"subjects": ["boy1", "boy2", "boy3", "boy4", "boy5", "boy6", "boy7", "boy8", "boy9", "boy10", "boy11", "boy12", "boy13", "boy14", "boy15", "boy16", "boy17", "boy18", "boy19", "boy20", "boy21", "boy22", "boy23", "boy24", "boy25", "boy26", "boy27", "boy28", "boy29", "boy30", "boy31", "boy32", "boy33", "boy34", "boy35", "boy36", "boy37", "boy38", "boy39"], "variables": ["Hip Angle", "Knee Angle"]}

fdatools/_data/growth.json

@@ -0,0 +1 @@
+{}

fdatools/_data/pinch.json

@@ -0,0 +1 @@
+{}

fdatools/_internal/__init__.py

@@ -0,0 +1,4 @@
+"""Private helpers of fdatools.
+
+Nothing in this package is public API; modules here may change without notice.
+"""