Metadata-Version: 2.4
Name: datide
Version: 0.0.4
Summary: Data assimilation routines for Gaussian process regression that connect with gptide and gpvecchia
Author-email: Matt Rayson <Matt.Rayson@uwa.edu.au>, William Edge <william.edge@uwa.edu.au>, Lachlan Astfalck <Lachlan.Astfalck@uwa.edu.au>, Aurelian Ponte <aurelien.ponte@ifremer.fr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/TIDE-ITRH/datide
Project-URL: Bug Tracker, https://github.com/TIDE-ITRH/datide/issues
Project-URL: Changelog, https://github.com/TIDE-ITRH/datide/releases
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: xarray
Requires-Dist: matplotlib
Requires-Dist: dask
Requires-Dist: sparse
Dynamic: license-file

[![Documentation status](https://readthedocs.org/projects/datide/badge/?version=latest)](https://datide.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://badge.fury.io/py/datide.svg)](https://badge.fury.io/py/datide)
[![Downloads](https://static.pepy.tech/personalized-badge/datide?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/datide)


# datide

Data assimilation routines for Gaussian process regression, built to connect with [gptide](https://github.com/TIDE-ITRH/gptide) and [gpvecchia](https://github.com/TIDE-ITRH/gpvecchia).

Please see the [examples](https://datide.readthedocs.io/en/latest/examples.html) for particular use cases.

## Documentation

Documentation is available on [read the docs](https://datide.readthedocs.io/en/latest/).

## Installation

### pip

`pip install datide`

### To install a local development version

`pip install -e ./`

### To install latest from github

`pip install git+https://github.com/tide-itrh/datide.git`

## Features

- Gaussian process regression posterior mean, marginal likelihood, posterior covariance and conditional sampling, given an observation operator `H`, prior covariance `B` and observation error covariance `R`.
- Three solvers sharing the same interface: `DAdense` (dense linear algebra), `DAsparse` (dask + sparse, for much larger problems) and `DAblock` (batches many independent problems, e.g. one per harmonic constituent).
- `MultiscaleGP`, for combining multiple additive latent-process scales (e.g. a large-scale and a small-scale field) into one Gaussian process posterior, with an optional Woodbury-identity fast path for low-rank scales.
- Pluggable prior covariance representations in `datide.scales` (dense, sparse, low-rank, or delegated to an external Vecchia-approximation evaluator) consumed by both `DAdense` and `MultiscaleGP`.
- `datide.synthetic`, for generating synthetic Gaussian random fields to test against a known truth.

## Quick Usage

```python
import numpy as np
from datide import DAdense

rng = np.random.default_rng(0)

n_obs, n_state = 20, 5
H = rng.normal(size=(n_obs, n_state))          # observation operator
B = np.eye(n_state)                             # prior state covariance
R = 0.1 * np.eye(n_obs)                         # observation error covariance

x_true = rng.normal(size=n_state)
y = H @ x_true + rng.normal(scale=0.1, size=n_obs)  # noisy observations

model = DAdense(H, B, R)
x_est = model(y)  # posterior mean estimate of x_true
```

See the [examples](https://datide.readthedocs.io/en/latest/examples.html) for a worked multiscale interpolation use case.

## Citing

If you use datide in your research, please cite it -- see [CITATION.cff](CITATION.cff) for citation metadata (also available via GitHub's "Cite this repository" button).
