Metadata-Version: 2.4
Name: eulerpi
Version: 0.11.0
Summary: The eulerian parameter inference (eulerpi) returns a parameter distribution, which is consistent with the observed data by solving the inverse problem directly. In the case of a one-to-one mapping, this is the true underlying distribution.
Project-URL: Homepage, https://github.com/Systems-Theory-in-Systems-Biology/EPI
Project-URL: Bug Tracker, https://github.com/Systems-Theory-in-Systems-Biology/EPI/issues
Project-URL: Documentation, https://Systems-Theory-in-Systems-Biology.github.io/EPI/
Project-URL: Changelog, https://Systems-Theory-in-Systems-Biology.github.io/EPI/MarkdownLinks/changelog.html
Author-email: Lars Kaiser <lars.g.kaiser@gmx.de>, Sebastian Hoepfl <sebastian.hoepfl@ist.uni-stuttgart.de>, Vincent Wagner <vincent.wagner@ist.uni-stuttgart.de>
License-File: LICENSE.md
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: diffrax>=0.4.1
Requires-Dist: emcee>=3.1.4
Requires-Dist: jax>=0.4.19
Requires-Dist: jaxlib>=0.4.19
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy>=1.26.1
Requires-Dist: scikit-learn>=1.3.1
Requires-Dist: seedir>=0.4.2
Requires-Dist: tqdm>=4.66.1
Provides-Extra: sbml
Requires-Dist: amici>=0.32.0; extra == 'sbml'
Description-Content-Type: text/markdown

<!-- # Euler Parameter Inference -->
<h1></h1>

![EPI](https://github.com/Systems-Theory-in-Systems-Biology/EPI/blob/main/epi.png?raw=True "logo")

<!-- The badges we want to display -->
[![pages-build-deployment](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/pages/pages-build-deployment)
[![Build & Publish Documentation](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/sphinx.yml/badge.svg)](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/sphinx.yml)
[![Publish to PyPI](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/publish.yml/badge.svg)](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/publish.yml)
[![pytest](https://img.shields.io/github/actions/workflow/status/Systems-Theory-in-Systems-Biology/EPI/ci.yml?label=pytest&logo=pytest)](https://github.com/Systems-Theory-in-Systems-Biology/EPI/actions/workflows/ci.yml)

[![flake8](https://img.shields.io/badge/flake8-checked-blue.svg)](https://flake8.pycqa.org/)
[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE.md)
[![Python](https://img.shields.io/badge/python-3.13-purple.svg)](https://www.python.org/)
![PyPI](https://img.shields.io/pypi/v/eulerpi)

Eulerian Parameter Inference (EPI) is a powerful and novel method for inverse model parameter inference. The eulerpi package provides an implementation of the EPI algorithm, which takes observed data and a model as input and returns a parameter distribution consistent with the observed data by solving the inverse problem directly. In case the model describes a one-to-one mapping between parameters and simulation results, the inferred parameter distribution is the true underlying distribution.

## Documentation

The full documentation of this software, including a detailed tutorial on how to use EPI and the api documentation, can be found under [Documentation](https://Systems-Theory-in-Systems-Biology.github.io/EPI/).

## Features

EPI supports

- SBML ode models
- User provided models
- Models with automatic differentiation using jax

## Installation

The package is available on pypi and can be installed with:

```bash
pip install eulerpi
```

or

```bash
pip install eulerpi[sbml]
```

for the support of sbml models.

Make sure that you have the following C++ libraries installed

```bash
sudo apt install -y swig libblas-dev libatlas-base-dev libhdf5-dev
```

You can also build the library from the latest source code by following the [Development Quickstart Guide](./DEVELOPMENT.md#quickstart).

## Using the library

To use EPI, derive your model from the `BaseModel` class and implement the abstract functions. Here's an example code snippet:

```python
# my_model.py

import jax.numpy as jnp

from eulerpi.core.models import BaseModel

class MyModel(BaseModel):

    param_dim = N # The dimension of a parameter point
    data_dim = M # The dimension of a data point

    def forward(self, param):
        return jnp.array(...)

    def jacobian(self, param):
        return jnp.array(...)
```

To evaluate the model and infer the parameter distribution, call:

```python
from eulerpi.sampling import inference

from my_model import MyModel

# This line is needed for multiprocessing in python
if __name__ == "__main__":
    central_param = np.array([0.5, -1.5, ...])
    param_limits = np.array([[0.0, 1.0], [-3.0, 0.0], ...])

    model = MyModel(central_param, param_limits)
    inference(model=model, data="my_data.csv")
```

The `data` argument can be a numpy-2d-array or a PathLike object that points to a CSV file. In the example shown above, the CSV file `my_data.csv` should contain the data in the following format:

```text
datapoint_dim1, datapoint_dim2, datapoint_dim3, ..., datapoint_dimN
datapoint_dim1, datapoint_dim2, datapoint_dim3, ..., datapoint_dimN
datapoint_dim1, datapoint_dim2, datapoint_dim3, ..., datapoint_dimN
...
datapoint_dim1, datapoint_dim2, datapoint_dim3, ..., datapoint_dimN
```

This corresponds to a matrix with the shape `nSamples x data_dim`. For more available options and parameters for the `inference` method, please refer to the [api documentation](https://systems-theory-in-systems-biology.github.io/EPI/eulerpi.core.html#module-eulerpi.core.inference). Note that the inference can be done with grid-based methods (dense grids, sparse grids) or sampling methods (mcmc).

The results are stored in the following location:

* `./Applications/<ModelName>/.../OverallParams.csv`
* `./Applications/<ModelName>/.../OverallSimResults.csv`
* `./Applications/<ModelName>/.../OverallDensityEvals.csv`

These files contain the sampled parameters, the corresponding data points obtained from the model forward pass, and the corresponding density evaluation.
