Metadata-Version: 2.4
Name: GaussianCovariance
Version: 1.1.0
Summary: Python Module to compute the covariance of two-point clustering statistics
Author-email: Alfonso Veropalumbo <alfonso.veropalumbo@inaf.it>, Claudio Guida <claudio.guida@edu.unige.it>, Elena Sarpa <elena.sarpa@inaf.it>
Project-URL: Homepage, https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/
Project-URL: Bug Tracker, https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# GaussianCovariance

Gaussian (disconnected) covariance matrices for two-point clustering statistics:
power spectrum multipoles `P_l(k)`, correlation function multipoles `xi_l(r)`,
and their cross-covariance, following
[Grieb et al. 2016](https://arxiv.org/abs/1509.04293).

Pure Python, with `numpy` and `scipy` as the only dependencies.

Documentation: <https://gaussiancovariance.readthedocs.io>

## Installation

```bash
pip install gaussiancovariance
```

Or from a checkout:

```bash
git clone https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/
cd gaussiancovariance
pip install .
```

Requires Python 3.10 or newer.

## Usage

A covariance object is built from the bin edges and the multipoles wanted. It is
then called with a `p_k_mu(k, mu)` callable giving the polar power spectrum, the
survey volume and the number density:

```python
import numpy as np
from GaussianCovariance import TwoPointGaussianCovariance

# stand-in for a tabulated P(k); in practice interpolate your own
pk = lambda k: 2.0e4 * (k / 0.05) / (1 + (k / 0.05) ** 4)

r_edges = np.linspace(0, 200, 41)
xi_cov = TwoPointGaussianCovariance(r_edges, l_list=[0, 2, 4])

b1, f = 1.37, 0.87
p_k_mu = lambda k, mu: (b1 + f * mu ** 2) ** 2 * pk(k)

cov = xi_cov(p_k_mu, volume=3780.0 ** 3, number_density=2.0e-3)
print(cov.shape)  # (120, 120)
```

`p_k_mu` is called with `k` of shape `(..., 1)` and `mu` of shape `(..., deg)`,
and must return an array broadcasting against `mu`. The form above does so
naturally.

The result is laid out multipole-major: with 40 bins, rows 0-39 are `l = 0`,
40-79 are `l = 2` and 80-119 are `l = 4`.

### The three terms

Expanding `(P + 1/n)^2` gives three contributions, named for the number of
distinct galaxies entering them: `C4` (`P^2`), `C3` (`2P/n`) and `C2` (`1/n^2`).
Every step between the kernel and the final matrix is linear, so a single pass
yields the total and all three terms separately:

```python
components = xi_cov.compute_components(p_k_mu, volume=3780.0 ** 3,
                                       number_density=2.0e-3)

components.C4, components.C3, components.C2  # the individual terms
components.total                             # their sum, the full covariance
components.combine(C2=1, C3=0, C4=1)         # e.g. drop the 2P/n term
```

Prefer this to calling the object several times with different coefficients,
which repeats the whole calculation each time.

### Available classes

| class | covariance of |
| --- | --- |
| `PowerSpectrumGaussianCovariance` | `P_l(k)`, block-diagonal in k |
| `TwoPointGaussianCovariance` | `xi_l(r)`, dense in r |
| `JointTwoPointGaussianCovariance` | both, plus the `P(k)`-`xi(r)` cross block |

Only even multipoles are supported.

Worked examples, including a comparison against a simulated covariance, are in
the [demo notebooks](https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/-/tree/main/demo).

## Contributing

Bug reports and merge requests are welcome. [CONTRIBUTING.md](https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/-/blob/main/CONTRIBUTING.md) covers the development setup,
how the tests are meant to be written and the release process. Release history is in
[CHANGELOG.md](https://gitlab.com/veropalumbo.alfonso/gaussiancovariance/-/blob/main/CHANGELOG.md).

## License

GNU General Public License v3 or later.
