Metadata-Version: 2.5
Name: petab-temporal-uncertainty
Version: 0.0.1
Summary: PEtab extension and AMICI/pyPESTO tooling for marginalized measurement-time uncertainty
Author-email: Paul Jonas Jost <jost.pauljonas@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: amici>=1.0.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: petab>=0.8.2
Requires-Dist: pypesto>=0.6.0
Requires-Dist: python-libsbml>=5.20.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# petab-temporal-uncertainty

A [PEtab](https://petab.readthedocs.io/) extension and tooling for
**marginalized measurement-time uncertainty**: when a measurement's reported
timepoint is itself uncertain (drawn from a known distribution around the
reported time), this package augments your model's SBML with one latent
"marginal-likelihood" ODE state per uncertain group, imports it via
[AMICI](https://amici.readthedocs.io/), and builds a
[pyPESTO](https://pypesto.readthedocs.io/) `Objective` with an analytic
gradient for the resulting marginal log-likelihood — no numerical
integration over the time-uncertainty distribution at each optimizer step.

## Method

Implements the marginalized-likelihood approach described in a manuscript
currently in preparation; this section will be updated with the citation
once it is available. This package targets the *marginalized* approach
only — see the manuscript's own comparison for why (marginalized matches
the joint/optimize-over-tau approach statistically while being far
faster).

## Installation

```bash
pip install petab-temporal-uncertainty
```

## Extension format

Add a `timeDistributionId` column to your measurement table (empty for
ordinary exact-time rows), and a `timeUncertainties.tsv` table (registered
via a `time_uncertainty_files` key in your `problem.yaml`, alongside
`measurement_files`/`observable_files`) indexed by `timeDistributionId`,
with columns `timeDistribution` (`normal` or `uniform`) and `timeParameters`.
The reference time for a `timeDistributionId` group is read from the
measurement table's own existing `time` column, not from
`timeUncertainties.tsv` — every measurement row sharing a `timeDistributionId`
must agree on `time`. Rows sharing a `timeDistributionId` share one latent
time-shift (the "shared-tau" case); a `timeDistributionId` referenced by
exactly one row is the independent ("multi-tau") case.

## Usage

```python
import petab
from petab_temporal_uncertainty import augment_petab_problem, build_objective
from petab_temporal_uncertainty.validation.lint import load_time_uncertainty_df

problem = petab.Problem.from_yaml("problem.yaml")
time_uncertainty_df = load_time_uncertainty_df("problem.yaml")

augmented = augment_petab_problem(problem, time_uncertainty_df)
objective = build_objective(augmented)

# objective is a standard pypesto.Objective -- use it exactly as any other
import pypesto
result = pypesto.optimize.minimize(pypesto.Problem(objective=objective, ...))
```

## License

BSD-3-Clause. See `LICENSE`.
