petab-dev/petab

PEtab - an SBML and TSV based data format for parameter estimation problems in systems biology

PEtab -- a data format for specifying parameter estimation problems in systems biology

PEtab is a data format for specifying parameter estimation problems in systems biology. This repository contains the PEtab specifications and additional documentation.

About PEtab

PEtab is built around SBML and based on tab-separated values (TSV) files. It is meant as a standardized way to provide information for parameter estimation, which is out of the current scope of SBML. This includes for example:

• Specifying and linking measurements to models

  • Defining model outputs

  • Specifying noise models

• Specifying parameter bounds for optimization

• Specifying multiple simulation condition with potentially shared parameters

Documentation

Documentation of the PEtab data format is available at https://petab.readthedocs.io/en/latest/.

Contributing to PEtab

To participate in PEtab editor elections, discussions on new PEtab developments, or PEtab-related events, please join our petab-discuss mailing list.

Any contributions and feedback to PEtab are very welcome, see our contribution guide.

Examples

A wide range of PEtab examples can be found in the systems biology parameter estimation benchmark problem collection.

PEtab support in systems biology tools

Where PEtab is supported (in alphabetical order):

• AMICI (Example)

• A PEtab -> COPASI converter

• d2d (HOWTO)

• dMod (HOWTO)

• MEIGO (HOWTO)

• parPE

• PEtab.jl (HOWTO)

• PumasQSP.jl (HOWTO)

• pyABC (Example)

• pyPESTO (Example)

• SBML2Julia (Tutorial)

If your project or tool is using PEtab, and you would like to have it listed here, please let us know.

PEtab features supported in different tools

The following list provides an overview of supported PEtab features in different tools, based on passed test cases of the PEtab test suite:

ID	Test	AMICI >=0.11.19	Copasi	D2D	dMod	MEIGO	parPE develop	PEtab.jl >=1.1.0	PumasQSP	pyABC >=0.10.1	pyPESTO >=0.0.11	SBML2Julia
1	Basic simulation	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
2	Multiple simulation conditions	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
3	Numeric observable parameter overrides in measurement table	+++	+++	+++	+++	+++	--+	+++	---	+++	+++	+++
4	Parametric observable parameter overrides in measurement table	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
5	Parametric overrides in condition table	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
6	Time-point specific overrides in the measurement table	---	---	+++	+++	+++	---	+++	---	---	---	+++
7	Observable transformations to log10 scale	+++	+++	+++	++-	+++	--+	+++	+-+	+++	+++	+++
8	Replicate measurements	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
9	Pre-equilibration	+++	---	+++	+++	+++	--+	+++	---	+++	+++	+++
10	Partial pre-equilibration	+++	---	+++	+++	+++	--+	+++	---	+++	+++	+++
11	Numeric initial concentration in condition table	+++	+++	+++	+++	+++	--+	+++	+++	+++	+++	+++
12	Numeric initial compartment sizes in condition table	---	+++	+++	+++	+++	---	+++	---	---	---	+++
13	Parametric initial concentrations in condition table	+++	+++	+++	+++	+++	--+	+++	---	+++	+++	+++
14	Numeric noise parameter overrides in measurement table	+++	+++	+++	+++	+++	--+	+++	---	+++	+++	+++
15	Parametric noise parameter overrides in measurement table	+++	+++	+++	+++	+++	--+	+++	---	+++	+++	+++
16	Observable transformations to log scale	+++	+++	+++	++-	+++	--+	+++	---	+++	+++	+++

Legend:

• First character indicates whether computing simulated data is supported and simulations are correct (+) or not (-).
• Second character indicates whether computing chi2 values of residuals are supported and correct (+) or not (-).
• Third character indicates whether computing likelihoods is supported and correct (+) or not (-).

Using PEtab

If you would like to use PEtab yourself, please have a look at:

• a PEtab tutorial going through the individual steps of setting up a parameter estimation problem in PEtab, independently of any specific software
• the PEtab format reference
• the example models provided in the benchmark collection.
• the tutorials provided with each of the softwares supporting PEtab

To convert your existing parameter estimation problem to the PEtab format, you will have to:

1. Specify your model in SBML.

2. Create a condition table.

3. Create a table of observables.

4. Create a table of measurements.

5. Create a parameter table.

If you are using Python, some handy functions of the PEtab library can help you with that. This includes also a PEtab validator called petablint which you can use to check if your files adhere to the PEtab standard. If you have further questions regarding PEtab, feel free to post an issue at our GitHub repository.

PEtab Python library

PEtab comes with a Python package for creating, checking, visualizing and working with PEtab files. This package is available at https://github.com/PEtab-dev/libpetab-python/.

PEtab R library

There is also an R package for PEtab in development, which currently supports: consistent manipulation of experimental conditions, measurements, and observables; and visualizing measurements. It also provides an interface to the PEtab Python library, and an interface to dMod that supports: conversion of dMod models to SBML; and simulation and visualization of results. The package is available at https://github.com/dlill/petab/.

Getting help

If you have any question or problems with PEtab, feel free to post them at our GitHub issue tracker.

petab's Issues

Handle observable and noise parameter mapping (from opt to sim parameters) with missing data

Is it possible that the overrides do not work, and thus names like observableParameter1... remain in the table, for conditions where some data are missing?

This is e.g. the case for the Schwen model.

Fill in condition-specific parameters during parameter mapping

Currently this only happens for dynamic parameter overrides.

Ignore empty space after a name

For example:
in the measurement data file I have the name 'IR1_P ' and in the SBML model I have 'IR1_P'. It would be good to be able to automatically ignore spaces at the end of the string.

• to avoid:
  Unknown observables in measurement file: {'observable_IR1_P '}

Extension of data format to allow for lists of simulationConditions and timepoints

To be discussed at a later point

add experimentId in the documentation

The experimentId which is used then for the plotting routines is not yet in the documentation. Its included in some of the models already for example Brannmark.

Allow constant species in condition table

At the moment we do not allow constant species in the condition table. To have these concentrations condition-specific, the current way to go would be to turn those species into parameters. For the simulation this is fine.

However, this takes away the possibility of listing those species as reaction modifiers, which makes sense in terms of underlying biology and for model visualization. Furthermore, keeping those species as SBML species would allow for better annotation.

What was the motivation for not allowing constant species in the condition table?

Handling of parameter estimation problems with multiple sbml models

In this model there are to model files and, therefore, two measurement data files and experimental condition files. But only one for the parameter file. The naming is:

• model_Becker_Science2010__BaF3_Exp.xml
• model_Becker_Science2010__binding.xml

At the moment, this throws an error in PEtab (as it does not follow the standard naming we established).

How should we circumvent this problem?

• Should we allow for finding a list of model names in the model folder and then check the respective pairs?
• Should we re-define the naming convention for such exception cases?

petab.Problem.from_folder does not set problem.name

To reproduce in pypesto:

petab_problem = petab.Problem.from_folder(test.petab_util.folder_base +
                                                  "Zheng_PNAS2012");
importer = pypesto.PetabImporter(petab_problem)

Preequilibration

How would I specify preequilibration/presimulation fixed parameters?

steady state data

How do I define steady state data? Only have the preequlibration condition, no simulation condition, and fill the time column with 0?

string split when noiseParameters are numeric values

File "/home/elba/PhD/PEtab/petab/core.py", line 314, in split_parameter_replacement_list
result = [x.strip() for x in list_string.split(';') if len(x.strip())]
AttributeError: 'int' object has no attribute 'split'

petab.Problem.create_parameter_df should optionally include local parameters

Currently only global SBML parameters are included. There should be an option to also include local ones. This is a bit tricky since there can be multiple local parameters with the same name in different reactions. We 'globalize' them by prefixing with reaction id, but this is non-standard.

sbml.constant_species_to_parameters does not handle all speciesReferences

Create coverage report on travisCi

Check conditionFile for required column "conditionId" before setting it as index in `petab.core.get_condition_df`

Easy one to get started ;)

Add function to create parameter table based on model, condition table and measurements

Has anybody started working on that already?

Requires #33

Come up with better name

If anybody has good ideas...

Model name needed in pypesto

In order to create the AMICI folder, PYPESTO needs some model name. This has been removed in the latest version of petab.

• Can a name be somehow extracted, or should the user be forced to create one in PYPESTO? (prefer the former)
• Might be good to store the name as a problem attribute, as some sort of identifier.

Remove experimentID

as discussed in #110 , remove the experimentID in favor of datasetID. don't know if a replacement for petab.generate_experiment_id will be needed.

Update documentation, remove TODOs

Adapt to latest discussions

Multiple Models

Have you thought about making model assignment condition specific?

Ensure float fields are floats, not int

... this makes downstream use easier

e.g.

• time in measurement table
• parameter values in condition table
  .....

assert_no_trailing_whitespace fails for all-nan columns

TypeError: expected string or bytes-like object

To reproduce: run petablint on Raia_CancerResearch2011

@elbaraim : Can you please look into that?

Extend validator to check if all required parameters are present in parameter table

See #42 for what to check.

Should be added to petab/lint.py:

def check_parameter_sheet(problem):

EDIT: Also check that there are no additional parameters

Use absolute paths in README for pypi

Since we use the README as the page shown in pypi as well (https://pypi.org/project/petab/#description), we probably should only use absolute path links, because otherwise those won't work there. Currently affects the link to the doc.

Add PEtab schema visualization

... showing how the different files are connected.

Pandas SettingWithCopyWarning

Introduced in eae08e2.
@DantongWang Can you please fix that?

tests/test_visualization.py::test_generate_experimentId_no_empty
tests/test_visualization.py::test_generate_experiment_id_empty
  /home/dweindl/src/PEtab/petab/generate_experiment_id.py:80: SettingWithCopyWarning: 
  A value is trying to be set on a copy of a slice from a DataFrame
  
  See the caveats in the documentation: http://pandas.pydata.org/pandas-docs/stable/indexing.html#indexing-view-versus-copy
    measurement_data.experimentId[ind] = 'experiment_' + str(count)

tests/test_visualization.py::test_generate_experimentId_no_empty
tests/test_visualization.py::test_generate_experiment_id_empty
  /home/dweindl/.local/lib/python3.7/site-packages/pandas/core/indexing.py:190: SettingWithCopyWarning: 
  A value is trying to be set on a copy of a slice from a DataFrame
  
  See the caveats in the documentation: http://pandas.pydata.org/pandas-docs/stable/indexing.html#indexing-view-versus-copy
    self._setitem_with_indexer(indexer, value)

-- Docs: https://docs.pytest.org/en/latest/warnings.html

Add static code analysis integration

Probably codacy

Test for pep8

We could have the fun of requesting pep8 conformity, which will 1) be nasty, and 2) ensure that the code follows common standards. Any opinions?

Make Problem serializable

Add support for non-constant parameter overrides in condition table

Need to adapt optimization to simulation parameter mapping (core.get_optimization_to_simulation_parameter_mapping). What else?

Allow for condition-specific dynamic parameter overrides with different scales

Need to

• adapt scale mapping
• remove checks for same scaling
• for constant overrides, apply scaling during mapping

petablint.py: handle missing files more gracefully

In case input files are missing, show that in a more informative way, without stack traces. Run all checks that can be run with the given set of inputs. If it was invoked with a model name and not individual file names, this should still be considered as an error.

Add libsbml check to setup.py

add in install_requires

Add automatic creation of visualizationSpecification.tsv for standard plots

Setup auto-deployment on tag

https://docs.travis-ci.com/user/deployment/pypi/

pypi deployment broken

From latest release: https://travis-ci.com/ICB-DCM/PEtab/builds/107290041#L682

Uploading petab-0.0.0a13.tar.gz
100%|██████████| 24.9k/24.9k [00:00<00:00, 90.0kB/s]
NOTE: Try --verbose to see response content.
HTTPError: 403 Client Error: Invalid or non-existent authentication information. for url: https://upload.pypi.org/legacy/
petab.egg-info/PKG-INFO already exists, no checkout
petab.egg-info/SOURCES.txt already exists, no checkout
petab.egg-info/dependency_links.txt already exists, no checkout
petab.egg-info/entry_points.txt already exists, no checkout
petab.egg-info/requires.txt already exists, no checkout
petab.egg-info/top_level.txt already exists, no checkout
Could not restore untracked files from stash entry
PyPI upload failed.
failed to deploy

Discuss: Which parameters must be included in parameter table

SBML + measurement-table - condition-table(numeric-only)?

-> all parameter from SBML model except for placeholders need to show up either in the conditon or parameter table

Condition-specific Scalings

Well, ok we don't want condition-specific scalings (like lin, log10 etc.) as the title suggests, but we have the problem that the scalings are defined for the optimization parameters, not for the simulation parameters. So, for each condition, according to the mapping used there, also the scalings need to be mapped.

[petabLint] Check parameter file

Add checks for

• Presence of mandatory columns
• Columns contain only valid entries
• parameterId is unique
• Consistency checks such as
  • log parameters > 0
  • lowerBound <= upperBound (is Inf a valid bound?)
  • ...

Fix dynamic parameter overrides for preequilibration parameters

The current parameter mapping assumes that preequilibration and simulation condition have the same dynamic parameters. So the mapping probably fails in case preequilibration and simulation condition have different dynamic parameter overrides.

Visulization routine: Saving plot to file optional

So far the plot is always saved to a file

# optimization parameter mismatch # model parameters

Regarding the branch feature_benchmark2 and the new data format:

Example: In the Crauste_CellSystems2017 model the number of model parameters is bigger than the number of optimization parameters stored in the file parameters_Crauste_CellSystems2017.tsv. The reason for that is, that I don't want to estimate in this specific model the noise, but in the model parameters (sbml-file) I have specified the different noise as parameters (noiseParameter1_*). So when I want to calculate the objective function, I get following issue:

INPUT: obj, edatas = importer.create_objective()
ERROR:

Traceback (most recent call last):
line 24, in <module>  obj, edatas = importer.create_objective()
line 200, in create_objective mapping_par_opt_to_par_sim=parameter_mapping
line 444, in get_optimization_to_simulation_scale_mapping
    scale = par_opt_scales_from_df[par_opt_ids_from_df.index(val)]
ValueError: 'noiseParameter1_Naive' is not in list

Add visualization routines for measurement files

To allow for visualization of training data. Dose-response and time-series data. ...

Run pytest on travisCI

petab.Problem.create_parameter_df should use SBML parameter values to populate 'nominalValue'

petab.Problem.create_parameter_df should use SBML parameter values to populate 'nominalValue'

Specify format for priors in parameter table

Automatically detect directories in model_name in get_default_*_file_name

And adapt paths accordingly

Set petab.__version__

Add python version check to setup.py

We need 3.6