Metadata-Version: 2.5
Name: fdatools
Version: 1.1.0
Summary: Functional data analysis for Python: a clean-room rewrite of R's fda package.
Project-URL: Homepage, https://github.com/hameddavodi/fdatools
Project-URL: Documentation, https://hameddavodi.github.io/fdatools
Project-URL: Source, https://github.com/hameddavodi/fdatools
Project-URL: Issues, https://github.com/hameddavodi/fdatools/issues
Project-URL: Changelog, https://github.com/hameddavodi/fdatools/blob/main/CHANGELOG.md
Author-email: Hamed Davodi <hamed.davodi94@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: fda,fpca,functional data analysis,smoothing,splines
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: array-api-compat>=1.11
Requires-Dist: numpy>=2.1
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.14
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: jupyter>=1.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: nbmake>=1.5; extra == 'dev'
Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pyright>=1.1.403; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: scipy-stubs>=1.14; (python_version >= '3.10') and extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: golden
Requires-Dist: rpy2>=3.5; extra == 'golden'
Provides-Extra: io
Requires-Dist: rdata>=0.11; extra == 'io'
Provides-Extra: pandas
Requires-Dist: pandas>=2.2; extra == 'pandas'
Requires-Dist: xarray>=2024.1; extra == 'pandas'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == 'torch'
Description-Content-Type: text/markdown

# fdatools

[![CI](https://github.com/hameddavodi/fdatools/actions/workflows/ci.yml/badge.svg)](https://github.com/hameddavodi/fdatools/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fdatools.svg)](https://pypi.org/project/fdatools/)
[![Python versions](https://img.shields.io/pypi/pyversions/fdatools.svg)](https://pypi.org/project/fdatools/)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/hameddavodi/fdatools/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-hameddavodi.github.io%2Ffdatools-blue.svg)](https://hameddavodi.github.io/fdatools)

**Functional data analysis for Python.** fdatools is a clean-room Python rewrite of
R's [`fda`](https://cran.r-project.org/package=fda) package (Ramsay, Hooker &
Graves): basis expansions, penalised smoothing, functional PCA and CCA,
functional regression, curve registration and principal differential analysis.

- **Same numbers as R.** Every public function is tested against golden output
  from R `fda` 6.3.0 at `rtol = 1e-8` (`1e-5` for iterative fits). See the
  [parity report](https://github.com/hameddavodi/fdatools/blob/main/PARITY_REPORT.md).
- **About 40 symbols instead of 515 functions.** Curves are callable (`fd(t)`),
  arithmetic is plain Python (`fd1 + fd2`, `fd1 @ fd2`), and there is one
  `smooth()`, one `register()`, one `.plot()`.
- **Fits the Python stack.** scikit-learn estimators, NumPy or PyTorch arrays
  through the Array API (gradients flow), pandas and xarray I/O.

## Install

```bash
pip install fdatools
```

Optional extras: `fdatools[plot]` (matplotlib), `fdatools[pandas]` (pandas + xarray),
`fdatools[io]` (read R `.rds` files), `fdatools[torch]` (PyTorch). Python 3.10 to 3.13.

## Quickstart

```python
import numpy as np
import fdatools as fdt

growth = fdt.datasets.load_growth()                   # Berkeley growth study, ships with fdatools
basis = fdt.BSpline(domain=(1.0, 18.0), n_basis=12)   # cubic B-splines on ages 1-18
coefs, *_ = np.linalg.lstsq(basis(growth.age), growth.hgtf, rcond=None)
girls = fdt.FData(coefs, basis)                       # 54 height curves in one object
speed = girls.derivative()                           # growth speed in cm/year, exact
print(speed.mean()(np.array([5.0, 12.0])))           # curves are callable: evaluate anywhere
print(fdt.inprod(girls[0], girls[0]))                 # L2 inner product of one curve
```

Next steps: penalised smoothing with automatic λ (`smooth`), functional PCA
(`FPCA`) and more in the [quickstart guide](https://hameddavodi.github.io/fdatools/quickstart/).
Coming from R? The [migration table](https://hameddavodi.github.io/fdatools/r-migration/)
maps every `fda` function to its fdatools equivalent.

## Documentation

Full documentation, API reference and tutorials: <https://hameddavodi.github.io/fdatools>.

## Citing

If you use fdatools in published work, please cite it together with Ramsay &
Silverman (2005); see [`CITATION.cff`](https://github.com/hameddavodi/fdatools/blob/main/CITATION.cff).

## License

BSD 3-Clause. fdatools is a clean-room implementation written from the published
mathematics (Ramsay & Silverman 2005; Ramsay, Hooker & Graves 2009) and the
public behaviour of R `fda`; it contains no R source code.
