Below is a collection of brief tutorials on BioSimulators:
The next live tutorial will be presented on 10/13/2022 during the COMBINE meeting. Videos and slides for past tutorials are available below.
In adddition, several interactive tutorials for BioSimulators' Python
packages and APIs are available from Binder
The simulation tools in the BioSimulators registry require modeling
projects (one or more simulations of one or more models) to be
encapsulated into a COMBINE/OMEX archive. Please follow these steps to
create COMBINE/OMEX archives. Alternatively, COMBINE/OMEX archives that
describe modeling projects can be obtained from the BioSimulations
repository of modeling projects
sedml:model) and model
attribute changes (sedml:changeAttribute, steady-state,
one step, and timecourse simulations (sedml:steadyState,
sedml:oneStep, and sedml:uniformTimeCourse),
tasks for the execution of individual simulations of individual models
(sedml:task), algorithms (sedml:algorithm)
and algorithm parameters (sedml:algorithmParameter), data
generators for individual variables (sedml:dataGenerator,
sedml:variable), data generators for mathematical
expressions (sedml:dataGenerator/@math), and report and
plot outputs (sedml:report, sedml:plot2D and
sedml:plot3D). Some of the simulation tools support the
full SED-ML specification, including more complex model changes and
repeated tasks (sedml:repeatedTask). Save this file to
the directory for your modeling project. More information about SED-ML
is available from the SED-ML website. Alternatively, simulations can
be obtained from the BioSimulations repository of modeling projects
The simulation tools in the BioSimulators collection support different model formats, modeling frameworks, simulation types, simulation algorithms, and observables. First, determine the format and framework of your model and the simulation type and algorithm which you would like to execute. Second, browse the simulators to identify a tool which can execute your project. In addition, RunBioSimulations provides a tool which can recommend simulators for specific combinations of model formats, modeling frameworks, simulation types, and simulation algorithms.
runBioSimulations
The BioSimulators simulation tools can also be used to execute simulations on your own machine. Please follow these steps to use a containerized simulation tool to execute a modeling study on your own machine.
docker pull biosimulators/{{ '{' }} simulator-id {{ '}' }}
for each simulator that you wish to use. This will download the
simulators and install them onto your machine.
Use the selected simulator(s) to execute simulations and save their results: Execute the following from your console:
docker run \
--tty \
--rm \
--mount type=bind,source={{ '{' }} path-to-directory-of-COMBINE-archive {{ '}' }},target=/tmp/project,readonly \
--mount type=bind,source={{ '{' }} path-to-save-results {{ '}' }},target=/tmp/results \
ghcr.io/biosimulators/{{ '{' }} simulator-id {{ '}' }} \
--archive /tmp/project/{{ '{' }} name-of-COMBINE-archive {{ '}' }} \
--out-dir /tmp/results
Your COMBINE archive should be located at
path-to-directory-of-COMBINE-archive/name-of-COMBINE-archive.
The results will be saved to path-to-save-results. The
data for reports and plots will be saved in Hierarchical Data Format
5 (HDF5) format and plots will be saved in Portable Document Format
(PDF) and bundled into a single zip archive. See the
specifications for reports
for more information about the format of reports.
For reports, the rows of each data table will represent the data
sets (sedml:dataSet) outlined in the SED-ML definition
of the report. The heading of each row will be the label of the
corresponding data set. For plots, the rows of each data table will
represent the data generators (sedml:dataGenerator)
outlined in the SED-ML definition of the plot. The heading of each
row will be the id of the corresponding data generator
Report tables of steady-state simulations will have a single column of the steady-state predictions of each data set. Report tables of one step simulations will have two columns that represent the predicted start and end states of each data set. Report tables of time course simulations will have multiple columns that represent the predicted time course of each data set. Report tables of non-spatial simulations will not have additional dimensions. Report tables of spatial simulations will have additional dimensions that represent the spatial axes of the simulation.
The BioSimulators simulation tools can also be running in
high-performance computing (HPC) environments where root access is not
available by first converting the Docker images for the tools into
Singularity images
All of the validated images for simulation tools are compatible with Singularity. As part of the validation process, we check that each Docker image can be converted into a Singularity image.
The steps below illustrate how Singularity can be used to execute the simulation tools in HPC environments.
docker pull ghcr.io/biosimulators/{{ '{' }} id {{ '}' }}:{{
'{'
}}
version {{ '}' }}.
singularity pull {{ '{' }} /path/to/save/singularity-image.sif
{{ '}' }} docker://ghcr.io/biosimulators/{{ '{' }} id {{ '}' }}:{{
'{'
}}
version {{ '}' }}.
singularity run {{ '{' }} /path/to/save/singularity-image.sif
{{ '}' }} ....
The command-line interfaces for simulation tools can also be installed and run locally. Note, this typically requires additional effort beyond using the Docker images because it requires installing the dependencies for simulation tools.
Please follow these steps to use a command-line interface for a simulation tool to execute a modeling study.
Use the command-line program to execute a simulation project and save its results: Execute the following from your console:
biosimulators-{{ '{' }} simulator-id {{ '}' }} \
--archive {{ '{' }} /path/to/COMBINE-archive.omex {{ '}' }} \
--out-dir {{ '{' }} /path/to/save/outputs {{ '}' }}
In the above example, the simulation project is located at
/path/to/COMBINE-archive.omex and the results will be
saved to /path/to/save/outputs.
The Python APIs for simulation tools provide additional flexibility beyond their Docker images and command-line interaces. However, using these APIs typically requires additional effort beyond using the Docker images because it requires installing the dependencies for simulation tools, as well as some knowledge of the data structures used by BioSimulators.
Please follow these steps to use a Python API for a simulation tool to execute a modeling study.
Use the Python API to execute a simulation project and save its results: Execute the following from your Python shell:
In the above example, the simulation project is located at
/path/to/COMBINE-archive.omex and the results will be
saved to /path/to/save/outputs.
The ghcr.io/biosimulators/biosimulators Docker image
contains most of the available Python APIs inside a single Python
environment. An ipython shell to this environment can be launched by
executing the following from your console:
docker pull ghcr.io/biosimulators/biosimulators
docker run -it --rm ghcr.io/biosimulators/biosimulators
Additional interactive tutorials are available from Binder
An API is available for retrieving information about the simulation
tools in the BioSimulators collection. Please see the documentation for
the REST API
An interactive tutorial for using the API is available from Binder
We welcome contributions of additional simulation tools!
All simulation tools submitted for validation by BioSimulators should support at least one modeling language, SED-ML, KiSAO, and COMBINE/OMEX.
sedml:model,
sedml:changeAttribute.
sedml:steadyState, sedml:oneStep, or
sedml:uniformTimeCourse.
sedml:task.
sedml:algorithm,
sedml:algorithmParameter.
sedml:dataGenerator, sedml:variable
sedml:report.
Please follow the steps below to create a containerized simulation tool
that adheres to the BioSimulators standards. Several examples are
available from the BioSimulators GitHub organization
Implement a BioSimulators-compliant command-line interface to your simulation tool. The interface should accept two keyword arguments:
-i, --archive: A path to a COMBINE archive that
contains descriptions of one or more simulation tasks.
-o, --out-dir: A path to a directory where the
outputs of the simulation tasks should be saved. Data for plots
and reports should be saved in HDF5 format (see the
specifications for data sets
for more information) and plots should be saved in Portable
Document Format (PDF)
{{ '{ ' }}out-dir{{ ' }' }}/reports.h5 and plots
should be saved to
{{ '{ ' }}out-dir/plots.zip{{ ' }' }}. Within the HDF5 file and the zip file, reports and plots
should be saved to paths equal to the relative path of their
parent SED-ML documents within the parent COMBINE/OMEX archive
and the id of the report/plot.
For reports, the rows of the data tables should correspond to
the data sets (sedml:dataSet) specified in the
SED-ML definition of the report (e.g., time, specific species).
The heading of each row should be the label of the corresponding
data set.
For plots, the rows of the data tables should correspond to the
data generators (sedml:dataGenerator) specified in
the SED-ML definition of each curve and surface of the plot
(e.g., time, specific species). The heading of each row should
be the id of the corresponding data generator.
Data tables of steady-state simulations should have a single column of the steady-state predictions of each data set. Data tables of one step simulations should have two columns that represent the predicted start and end states of each data set. Data tables of time course simulations should have multiple columns that represent the predicted time course of each data set. Data tables of non-spatial simulations should not have additional dimensions. Data tables of spatial simulations should have additional dimensions that represent the spatial axes of the simulation.
See the specifications for reports for more information.
In addition, we recommend providing optional arguments for reporting help and version information about your simulator:
-h, --help: This argument should instruct the
command-line program to print help information about itself.
-v, --version: This argument should instruct the
command-line program to report version information about itself.
The easiest way to create a BioSimulators-compliant command-line
interface is to create a BioSimulators-compliant Python API and then
use methods in BioSimulators-utils
FROM directive to choose a base operating
system such as Ubuntu.
RUN directive to describe how to install your
tool and any dependencies. Because Docker images are typically run
as root, reserve /root for the home directory of the
user which executes the image. Similarly, reserve
/tmp for temporary files that must be created during
the execution of the image. Install your simulation tool into a
different directory than /root and
/tmp such as /usr/local/bin.
assets/. These files can
then be deleted and squashed out of the final image and injected
again when the image is executed.
ENTRYPOINT directive to the path to your
command-line interface.
CMD directive to [].ENV directive to declare all environment
variables that your simulation tool supports.
USER directive to set the user which
will execute the image so that the user can be set at execution
time.
Use the LABEL directive to provide the metadata
about your simulation tool described below. This metadata is
also necessary to submit your image to BioContainers
org.opencontainers.image.title:
Human-readable title of the image.
org.opencontainers.image.version: Version of
the software in the image.
org.opencontainers.image.revision: Source
control revision identifier of the software in the image.
org.opencontainers.image.description:
Human-readable description of the software in the image.
org.opencontainers.image.url: URL to find
more information about the image.
org.opencontainers.image.documentation: URL
to get documentation about the image.
org.opencontainers.image.source: URL to get
the Dockerfile for building the image.
org.opencontainers.image.authors: Contact
details of the people or organization responsible for the
image.
org.opencontainers.image.vendor: Name of the
entity, organization or individual which distributes the
image.
org.opencontainers.image.licenses: SPDX
expression that describes the license(s) under which the
software in the image is distributed.
org.opencontainers.image.created: Date and
time when the image was built (RFC 3339).
version: Version of your image (e.g.,
1.0.0)
software: Simulation program wrapped into
your image (e.g., BioNetGen).
software.version: Version of the simulation
program wrapped into your image (e.g.,
2.5.0).
about.summary: Short description of the
simulation program (e.g.,
Package for rule-based modeling of complex biochemical
systems).
about.home: URL for the simulation program
(e.g., https://bionetgen.org/).
about.documentation: URL for documentation
for the simulation program (e.g.,
https://bionetgen.org/).
about.license_file: URL for the license for
the simulation program (e.g.,
https://github.com/RuleWorld/bionetgen/blob/master/LICENSE).
about.license: SPDX license id for the
license for the simulation program (e.g.,
SPDX:MIT). See SPDX
about.tags: Comma-separated list of tags
which describe the simulation program (e.g.,
rule-based modeling,dynamical simulation,systems
biology,BNGL,BioSimulators). Please include the tag BioSimulators.
extra.identifiers.biotools: Optionally, the
bio.tools identifier for the simulation program (e.g.,
bionetgen). Visit bio.tools
maintainer: Name and email of the person/team
who developed the image (e.g.,
Jonathan Karr <karr@mssm.edu>).
Below is an example of metadata for the BioNetGen image.
Use Docker and the Dockerfile to build an image for your simulation tool by executing the following from your console:
docker build \
--tag {{ '{' }} dockerhub-user-id {{ '}' }}/{{ '{' }} simulator-id {{ '}' }}:{{ '{' }} simulator-version {{ '}' }} \
--tag {{ '{' }} dockerhub-user-id {{ '}' }}/{{ '{' }} simulator-id {{ '}' }}:latest \
--file {{ '{' }} path-to-Dockerfile {{ '}' }} \
.
Create a JSON-encoded file that specifies the capabilities of
your simulation tool.
This file should adhere to the schema described in the BioSimulators
API
Use SBO, KiSAO, and EDAM to describe the modeling frameworks,
simulation algorithms, and modeling formats that your simulation
tool supports. As necessary, use the following issue trackers to
request additional SBO
Use the BioSimulators test suite to validate your image and its specifications. This will check that the image provides a BioSimulators-compliant Docker structure and command-line interface, and that it provides all of the simulation algorithms described in its specifications.
pip install biosimulators-test-suite
biosimulators-test-suite validate {{ '{' }} dockerhub-user-id {{ '}' }}/{{ '{' }} image-id {{ '}' }} {{ '{' }} path-to-specifications.json {{ '}' }}The command-line program for the test suite provides several helpful options such as for executing tasks directly through command-line interfaces and for executing individual test cases. More information is available here
We welcome contributions of additional simulation tools! We encourage developers to submit tools that support BioSimulators' standard containerized command-line interface. Supporting these standards makes it easier for other investigators to use simulators. However, BioSimulators also accepts simulation tools that are not available via standardized Docker images.
Please follow these steps to contribute a tool to BioSimulators:
Optionally, build a standardized command-line interface for your simulator. This interface should support the following standards and conventions:
BioSimulators utils
docker push {{ '{' }} image-url {{ '}' }}. Docker Hub, GitHub Container Registry, and Quay each provide free
accounts for public images.
Optionally, set up your continuous integration workflow to automatically push each release to BioSimulators. Within your continuous integration workflow (e.g., CircleCI, GitHub actions, Jenkins, Travis), use the GitHub REST API to automatically create issues that submit versions of your simulator to BioSimulators.
This requires a GitHub account and a personal access token with the
public_repo scope. Instructions for creating an access
token are available in the GitHub documentation
http://api.github.com/repos/biosimulators/Biosimulators/issues
POST{{ '{' }} github-username {{ '}' }}:{{
'{'
}}
github-person-access-token {{ '}' }}
application/vnd.github.v3+jsonSubmit {{ '{' }} simulator-name {{ '}' }}
{{ '{' }} simulator-version {{ '}' }}
---
name: {{ '{' }} simulator-name {{ '}' }}
version: "{{ '{' }} simulator-version {{ '}' }}"
specificationsUrl: {{ '{' }} specifications-url {{ '}' }}
specificationsPatch:
version: "{{ '{' }} simulator-version {{ '}' }}"
image:
url: {{ '{' }} docker-image-repo-url {{ '}' }}:{{ '{' }} simulator-version {{ '}' }}
validateImage: true
---validateImage to false.
curl code sample:
curl \
-X POST \
-u jonrkarr:********* \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/biosimulators/Biosimulators/issues \
-d '{{ '{' }}"labels": ["Validate/submit simulator"], "title": "Submit tellurium 2.1.6", "body": "---\nname: tellurium\nversion: 2.1.6\nspecificationsUrl: https://raw.githubusercontent.com/biosimulators/Biosimulators_tellurium/2.1.6/biosimulators.json\nvalidateImage: true\ncommitSimulator: true\n\n---"{{ '}' }}'
The above is implemented by the Python method
biosimulators_utils.simulator_registry.submit.submit_simulator_to_biosimulators_registry. See the documentation
A sample continuous integration workflow
Each time a commit is pushed to the repository, the workflow executes the following tasks:
ghcr.io/<owner>/<repo>/<simulator_id>:<simulator_version
and
ghcr.io/<owner>/<repo>/<simulator_id>:latest.
Each time the repository is tagged (git tag ...; git push --tags), the workflow also runs the above tasks. If the above tasks succeed,
the workflow executes the follwing additional tasks:
We welcome contributions to the BioSimulators platform (e.g., web
application, REST API, database)! Please see the Guide to Contributing