biosimulators / biosimulators_utils

Utilities for building standardized command-line interfaces for biosimulation software packages

BioSimulators utils

Command-line application and high-level utilities for reading, writing, validating, and executing COMBINE/OMEX format files that contain descriptions of simulations in Simulation Experiment Description Markup Language (SED-ML) format with models in formats such as the BioNetGen Language (BNGL) and the Systems Biology Markup Language (SBML).

Installation

Requirements

• Python >= 3.7
• pip (latest)

Optional requirements

• Docker: required to execute containerized simulation tools
• Java: required to parse and validate NeuroML/LEMS files
• Perl: required to parse and validate BioNetGen files
• RBApy: required to parse and validate RBA files
• XPP: required to parse and validate XPP files

Install latest release from PyPI

pip install biosimulators-utils

Install latest revision from GitHub

pip install git+https://github.com/biosimulators/Biosimulators_utils.git#biosimulators_utils

Installation optional features

To use BioSimulators utils to validate BNGL models, install BioSimulators utils with the bgnl option:

pip install biosimulators-utils[bgnl]

To use BioSimulators utils to validate CellML models, install BioSimulators utils with the cellml option:

pip install biosimulators-utils[cellml]

To use BioSimulators utils to validate LEMS models, install Java and then install BioSimulators utils with the lems option:

pip install biosimulators-utils[lems]

To use BioSimulators utils to validate NeuroML models, install BioSimulators utils with the neuroml option:

pip install biosimulators-utils[neuroml]

To use BioSimulators utils to validate SBML models, install BioSimulators utils with the sbml option:

pip install biosimulators-utils[sbml]

To use BioSimulators utils to validate SBML models, install BioSimulators utils with the smoldyn option:

pip install biosimulators-utils[smoldyn]

To use BioSimulators utils to convert Escher metabolic maps to Vega flux data visualizations, install BioSimulators utils with the escher option:

pip install biosimulators-utils[escher]

To use BioSimulators utils to execute containerized simulation tools, install BioSimulators utils with the containers option:

pip install biosimulators-utils[containers]

To use BioSimulators utils to log the standard output and error produced by simulation tools, install BioSimulators utils with the logging option:

pip install biosimulators-utils[logging]

Dockerfile and Docker image

This package is available in the ghcr.io/biosimulators/biosimulators Docker image. This image includes all of the optional dependencies and installation options.

To install and run this image, run the following commands:

docker pull ghcr.io/biosimulators/biosimulators
docker run -it --rm ghcr.io/biosimulators/biosimulators

This image includes this package, as well as standardized Python APIs for the simulation tools validated by BioSimulators. Because this image aims to incorporate as many simulation tools as possible within a single Python environment, this image may sometimes lag behind the latest version of this package.

The Dockerfile for this image is available here.

Tutorials

Command-line interface

A tutorial for the command-line interface is available here.

Python API

Interactive tutorials for using BioSimulators-utils and Python APIs for simulation tools to execute simulations are available online from Binder here. The Jupyter notebooks for these tutorials are also available here.

API documentation

API documentation is available here.

License

This package is released under the MIT license.

Development team

This package was developed by the Karr Lab at the Icahn School of Medicine at Mount Sinai in New York and the Center for Reproducible Biomedical Modeling with assistance from the contributors listed here.

Contributing to BioSimulators utils

We enthusiastically welcome contributions to BioSimulators utils! Please see the guide to contributing and the developer's code of conduct.

Funding

This work was supported by National Institutes of Health award P41EB023912.

Questions and comments

Please contact the BioSimulators Team with any questions or comments.

biosimulators_utils's Issues

Support plots

• 2d plots
• 3d plots

Change default report output formats to just HDF5

Can be done once VCell supports HDF5

• biosimulators_utils/combine/exec.py:exec_sedml_docs_in_archive
• biosimulators_utils/sedml/exec.py:exec_doc

Remove `seaborn` requirement for bionetgen once a new version of bionetgen is released to PyPI

in requirements.optional.txt

Latest version does not install on Ubuntu 20.04 due to missing `python-libcombine==0.2.9`

I just tried to install the latest version on Ubuntu, but the python-libcombine==0.2.9 package does not exist for ubuntu.

(sbmlsim) mkoenig@trip3:~/git/sbmlsim$ pip install biosimulators-utils==0.1.76
Collecting biosimulators-utils==0.1.76
  Using cached biosimulators_utils-0.1.76-py2.py3-none-any.whl (125 kB)
Requirement already satisfied: requests in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (2.25.1)
Requirement already satisfied: python-dateutil in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (2.8.1)
Collecting termcolor
  Downloading termcolor-1.1.0.tar.gz (3.9 kB)
Collecting h5py
  Downloading h5py-3.2.1-cp38-cp38-manylinux1_x86_64.whl (4.5 MB)
     |████████████████████████████████| 4.5 MB 1.8 MB/s 
Requirement already satisfied: cement in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (3.0.4)
Requirement already satisfied: mpmath in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (1.2.1)
Requirement already satisfied: matplotlib in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (3.3.4)
Requirement already satisfied: lxml in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (4.6.3)
Requirement already satisfied: pandas in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (1.2.2)
Collecting networkx
  Using cached networkx-2.5.1-py3-none-any.whl (1.6 MB)
Collecting evalidate
  Using cached evalidate-0.7.7.tar.gz (6.3 kB)
Requirement already satisfied: appdirs in /home/mkoenig/envs/sbmlsim/lib/python3.8/site-packages (from biosimulators-utils==0.1.76) (1.4.4)
ERROR: Could not find a version that satisfies the requirement python-libcombine>=0.2.9 (from biosimulators-utils)
ERROR: No matching distribution found for python-libcombine>=0.2.9

Best Matthias

Parse time course from actions in BNGL files

Place into biosimulators_utils.model_lang.bngl.utils

Can be done once RuleWorld/PyBioNetGen#10 is addressed.

• Time course settings
• Algorithm parameters e.g., seed

Allow datasets to have different shapes through padding with nan

Motivation: stochastic simulations can can have lengths which are stochastic (e.g., because they terminate when a condition is reached, rather than terminating at a specific predetermined time point). It should be possible to build a report that includes predictions from multiple simulations that have different lengths.

Container exits with success code if no sedml is found

Example: https://run.biosimulations.dev/simulations/603d35ff5d7132300f9edd13#tab=log

The container exited successfully, resulting in the slurm job being successful as well. While true, the user might expect this to be a failure.

Support semantic versioning

Add validation for CellML 1.1

I'ved tried everything listed below, but couldn't get any of it to work.
https://www.cellml.org/tools/validation

This should cover imports

Incorporate validation of libOmexMeta files

@jhgennari @CiaranWelsh I'd like to incorporate validation of OMEX meta files here as part of comprehensive validation of COMBINE archives. Once integrated here, it will become part of validation deployed at https://run.biosimulations.org/validate and it will be integrated into each simulation tool.

• Can you provide a Python snippet to use pyomexmeta to validate a file?
• What is the format URL that you're using in conjunction with manifests of COMBINE archives?

Support validation of CellML 2.0 with imports

Can be resolved once question cellml/libcellml#870 is answered.

Allow less strict importing of SED-ML

E.g.,

• Send warning when data description can't be read in
• Send warning when repeated task can't be read in

Validate kisao ids for algorithm parameters are unique

Support new features introduced in SED-ML L1V4

• Combinations of targets and symbols (formerly handled with implicit XPATHs)
• Simple repeated task
• Remaining dimensions
• Plots styling
• New types of plots
• References from variables for specific models involved in repeated tasks

Support data descriptions

When a simulator input file is a plain zip archive (not a COMBINE archive), find all SED-ML files anyway

Inspired feature in tellurium. Allows execution of zip archives with SED-ML files to proceed (with a warning that its not a COMBINE archive).

Validate that ids of SED-ML objects are globally unique

Incorporate validation of NeuroML files

Enhance validation of LEMS to validate all imported content

Can do once NeuroML/pyNeuroML#104 is addressed.

Add commandline output for licence

According to GPL:

If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

{project}  Copyright (C) {year}  {fullname}
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w' and show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".

We can add a field to main.py that contains any needed licence text and options for displaying the licence

Deployed runBioSimulations API not returning `resultsSize`

The dev deployment returns resultsSize
https://dispatch.biosimulations.dev/run/5fdda8358b0da07b332ffa5a

but the deploy deployment does not
https://run.api.biosimulations.org/run/5fdd4ae450632203a037459a

Does https://run.api.biosimulations.org need to be re-deployed?

Incorporate validation of CellML files

Can be done once there's a libCellML distribution for Python3.9/Linux (could also be done by compiling from source, but a precompiled distribution is easier).

Annotate axes of HDF5 outputs

Use SIO to annotate semantic meaning of each implicit dimension (e.g., time, space, replicates)

• Dataset: SIO_000921 (dependent variable)
• Time: SIO_000418 (time instant)
• X-axis: SIO_000452 (x-axis)
• Y-axis: SIO_000453 (y-axis)
• Z-axis: SIO_000454 (z-axis)
• Replicates: SIO_001419 (collection of replicates)

This requires some discussion

• Reports can combine results from multiple simulations. In this case, the implicit dimensions don't have clear meanings. Should we limit reports to only have the results of a single simulation?

To implement this

• Upon collection of the results of each data generator/dataset, collect the meanings of the implicit dimensions from the simulators
  - UniformTimeCourse/non-spatial: time
  - UniformTimeCourse/spatial: time; x, y, z coordinates
• Pass this information to the ReportWriter

Switch LEMS validation to use new pyNeuroML method

Replace body of biosimulators_utils.model_lang.lems.validation.validate_model with pyneuroml.pynml.validate_neuroml2_lems_file.

Can be done when a new version of pyNeuroML is released (> 0.5.11).

Support additional types of SED-ML model changes

• AddXML
• ChangeXML
• RemoveXML
• ComputeChange

Add method to get observables for LEMS files

Can do once NeuroML/pyNeuroML#103 is addressed.

Use pipenv / pip.lock to better track dependencies of simulators

Optionally infer null SED-ML references

For example, when there is only one model, assume all null references point to this one model

Support fully not resetting models during repeated tasks

• When RepeatedTask.resetModel=False and the model of the first task of an iteration is the same as the last model of the last task of the previous iteration, execute the simulation starting from the final state of the previous simulation (i.e., copy the final simulation state of the previous simulation to the initial conditions of the next simulation).
• When consecutive sub-tasks reference the same model, execute the second simulation starting from the final state of the previous simulation.

Support SED-ML files without namespaces defined for model targets

Support lambda, bvar

Allow model.source to be an id of another model

SED-ML allows the following additional ways of defining the sources of models

• id of another model
• MIRIAM URN for BioModels (e.g., urn:miriam:biomodels.db:BIOMD0000000012 --> https://identifiers.org/biomodels.db:BIOMD0000000012 --> https://www.ebi.ac.uk/biomodels-main/BIOMD0000000012)
• URL

For compatibility with the spirit of COMBINE archives, I think SED-ML files in COMBINE archives should be self-contained, and not reference external entities via URLs and identifiers.

Support aggregate mathematical functions

• min
• max
• sum
• product
• count
• mean,
• stdev
• variance

Support SED-ML repeated task

• Execution
• Logging

Improve error messaging

• Add SBML validation to BoolNet, COPASI
• More flexible recognition of SED URNs for model languages
• Stricter validation of unique ids

Add option to stream reports as soon as available

• After each SED task, output the portion of each report that is available
• Indicate percent completion of report

Initialize reports with their eventual shapes

this requires individual simulation tools to pass information about the shape of their output to this method

Add warning for model resolution by MIRIAM ids, that this will be deprecated

Support additional environment variables for simulator CLIs

• Flag to indicate whether KiSAO terms for algorithms should be strictly interpreted, or similar algorithms can be substituted
• Path to save status log file. See biosimulations/biosimulations#1733
• Report, plot formats e.g., csv, h5, pdf

Allow subtasks of a repeated task to use different models

This is mostly allowed with a couple exceptions

• Validation of XPath targets of variables of data generators needs to be appropriately handled for instances of Task
  • Check that targets are valid with the language of at least one subtask
• Handle errors in task executer not being able to generate all variables
• Add test for this to test suite

Support data generators that aren't equal to a single variable (target or symbol)

Expand capabilities of execution status logging

BioSimulators utils

• Execute each SED document, task, and output
  • Catch exceptions so that the execution doesn't stop on the first failure
  • Collect all exceptions and raise them at the end of the execution of the entire archive
  • When there's at least one exception, terminate with non-zero exit code
  • Generate as much of each output as possible
• For each archive, task, and output capture:
  • Exception
    • Type
    • Message
  • Reason for skip
  • Stdout/err
    • Stdout/err merged together
    • ANSI formatting codes
  • Walltime (duration)
• For each task capture
  • The KiSAO id for the algorithm that was executed
  • Additional simulator-specific details of the execution such as the method and its arguments
• Make CLI print errors in red
• Print warnings in yellow

tellurium

• Apply changes to exec_sed_doc in biosimulators_tellurium

Add warnings

• Inconsistent curve/surface axes
• Duplicate data set labels
• Tasks that don't contribute to outputs
• Data generators that don't contribute to outputs
• Data generators for reports/plots may have inconsistent shapes because from different kinds of tasks
  • Different kinds of simulations (e.g., time course vs steady-state)
  • Different kinds of tasks (basic vs. repeated)
• Data sets of reports, x/y of curves, x/y/z of surfaces have consistent shapes
  • Different kinds of simulations (e.g., time course vs steady-state)
  • Different kinds of tasks (basic vs. repeated)
• Subtasks have different shapes

Annotate the dimensions and slice of reports

It would be helpful to be able to capture information about the semantic meaning of each dimension and slice of a report. Presently, this is challenging to do in a general way because SED reports can mix results from multiple tasks of multiple simulations of multiple models. This would be possible if a report was restricted to contain the outputs of a single task (or repeated task)/

Incorporate validation of PETab files

Example:
https://github.com/PEtab-dev/libpetab-python/blob/master/doc/example/example_petablint.ipynb

Support random number generator functions new to SED-ML L1V4

• uniform
• normal
• lognormal
• gamma
• poisson

Add method of executing simulations with Singularity images

Example:
singularity run -B out:/root image.sif -i /root/Lotka-Volterra.omex -o /root

Incorporate as options of

• biosimulators_utils.simulator.exec.exec_sedml_docs_in_archive_with_containerized_simulator
• biosimulators_utils.__main__.ExecuteModelingProjectController

Should reports be disallowed from containing datasets with different time scales?

Example: A simulation experiment involves two tasks, one in minutes and one in seconds. Both tasks have the same number_of_points. Their results are combined into separate datasets within a single report. Doing this, obscures the meaning of the second (time) dimension of the report.

Should BioSimulators utils continue to support this, or raise an exception?

Switch pandas to xarray to support multidimensional reports

Make smoldyn requirement >= 2.67 once released

Update requirements.optional.txt