petab-temporal-uncertainty

A PEtab 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, and builds a pyPESTO 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

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

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.