bio_compose

bio_compose.api.get_biomodel_archive(model_id: str, dest_dir: str | None = None) → str

Download all files for a given Biomodel as an OMEX archive from the Biomodels REST API, optionally specifying a download destination. NOTE: This file may be opened as a typical zip file.

Parameters:

• model_id – (Union[str, List[str]]) A single biomodel id as a string or a list of biomodel ids as strings.

• dest_dir – (str) destination directory at which to save downloaded file. If None is passed, downloads to cwd. Defaults to None.

Returns:

Filepath of the downloaded biomodel OMEX(zip) archive

Return type:

str

bio_compose.api.get_biomodel_file(model_query: str | List[str], dest_dir: str | None = None) → str

Download a model file (SBML) from the Biomodels REST API, optionally specifying a download destination.

Parameters:

• model_query – (Union[str, List[str]]) A single biomodel id as a string or a list of biomodel ids as strings.

• dest_dir – (str) destination directory at which to save downloaded file. If None is passed, downloads to cwd. Defaults to None.

Returns:

Filepath of the downloaded biomodel file as a .zip file.

Return type:

str

bio_compose.api.get_compatible_verification_simulators(entrypoint_file: str, return_versions: bool = False)

Get all simulators and optionally their versions for a given file. The File is expected to be either an OMEX/COMBINE archive or SBML file.

Parameters:

• entrypoint_file – (str) The path of the file to be checked.

• return_versions – (bool) Whether to return the compatible version of the given compatible simulator. Defaults to False.

Returns:

A list of compatible simulators and the current compatible version of the given compatible simulator.

Return type:

List[Union[Tuple[str, str], str]

bio_compose.api.get_output(job_id: str, download_dest: str | None = None, filename: str | None = None) → Dict

Fetch the current state of the job referenced with job_id. If the job has not yet been processed, it will return a status of PENDING. If the job is being processed by the service at the time of return, status will read IN_PROGRESS. If the job is complete, the job state will be returned, optionally with included result data (either JSON or downloadable file data).

Parameters:

• job_id – (str) The id of the job submission.

• download_dest – (Optional[str]) File download outputs only. Optional directory where the file will be downloaded if the output is a file. Defaults to the current directory.

• filename – (Optional[str]) File download outputs only. Optional filename to save the downloaded file as if the output is a file. If not provided, the filename will be extracted from the Content-Disposition header.

Returns:

If the output is a JSON response, return the parsed JSON as a dictionary. If the output is a file, download the file and return the filepath. If an error occurs, return a RequestError.

Return type:

Dict

bio_compose.api.run_batch_verification(model_files: list[str], *args) → Dict[str, VerificationResult]

Run a batch of verifications

Args: :param model_files: (list[str]) A list of biomodel SBML files to verify.

Positional arguments: :param args: (list | tuple) Positional arguments to pass to run_batch_verification: if sbml verifications, start, stop, steps.

Returns:

Verification results indexed by verification Job ID.

Return type:

dict

bio_compose.api.run_simulation(*args, **kwargs) → SimulationResult

Run a simulation with BioCompose.

Parameters:

args – Positional arguments

• 1 argument: smoldyn simulation configuration in which time parameters (dt, duration) are already defined. Smoldyn simulation only.

• 3 arguments: smoldyn configuration file, smoldyn simulation duration, smoldyn simulation dt. Smoldyn simulation only.

• 5 arguments: sbml filepath, simulation start, simulation end, simulation steps, simulator. SBML simulation only.

Parameters:

kwargs – Keyword arguments

Returns:

instance of simulation results.

Return type:

bio_compose.runner.SimulationResult

bio_compose.api.verify(*args) → VerificationResult

Verify and compare the outputs of simulators for a given entrypoint file of either sbml or omex.

Parameters:

args – Positional arguments

• 1 argument: submit omex verification with no time params. OMEX verification only.

• 2 arguments: omex filepath, simulators to include in the verification. OMEX verification only.

• 4 arguments: sbml filepath, start, stop, steps. SBML verification only.

• 5 arguments: sbml filepath, start, stop, steps, simulators. SBML verification only.

Returns:

instance of verification results.

Return type:

bio_compose.verifier.VerificationResult

bio_compose.api.visualize_observables(job_id: str, save_dest: str | None = None, hspace: float = 0.25, use_grid: bool = False)

Visualize simulation output (observables) data, not comparison data, with subplots for each species.

Parameters:

• job_id – (str) job id for the simulation observable output you wish to visualize.

• save_dest – (str) path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.

• hspace – (float) horizontal spacing between subplots. Defaults to 0.25.

• use_grid – (bool) whether to use a grid for each subplot. Defaults to False.

Returns:

matplotlib Figure and simulation observables indexed by simulator

Return type:

Tuple[matplotlib.Figure, Dict]

bio_compose.bundles

class bio_compose.bundles.BioBundle

Bases: object

add_emitter_node(composition: Dict[str, Dict[str, Any]], emitter_address_id: str, emitted_schema: Dict[str, str], memory_stores: List[str])

generate_node(composition: Dict[str, Dict[str, Any]], node_name: str, node_type: str, address: str, config: Dict[str, Any], input_ports: Dict[str, str] | List[str] | None = None, output_ports: Dict[str, str] | List[str] | None = None) → Dict

generate_port_spec(port_params: Dict[str, str] | List[str])

bio_compose.composer

class bio_compose.composer.Composer

Bases: Api

A new instance of the Verifier class. NOTE: this may clash with your record keeping in a notebook, so it is highly recommended that users treat instances of this class as quasi-singletons, although not necessary for fundamental interaction.

data: Dict

endpoint_root: str

run_composition(duration: int, doc: Dict)

submitted_jobs: List[Dict]

bio_compose.data_model

class bio_compose.data_model.Api

Bases: object

Base class inherited by the domain-specific polymorphisms native to this package: verifier.Verifier, composer.Composer, and runner.SimulationRunner.

Params:

• endpoint_root: str: default base endpoint used by this packaging.

• data: dict: default historical collection of data fetched by the given instance of this class.

• submitted_jobs: list[dict]: default list of jobs submitted by the given instance.

Generic base instance which is inherited by any flavor (tag group) of the BioCompose REST API. Polymorphism of this base class should pertain entirely to the tag group domain with which it is associated (e.g., ‘execute-simulations’, ‘verification’, etc.)

export_csv(data: Dict, save_dest: str)

Export the content passed in data as a CSV file.

Parameters:

• data (-) – Dict: simulation output data generated from Verifier.get_verify_output().

• save_dest (-) – str: Destination path to save the CSV file.

export_plot(fig: Figure, save_dest: str) → None

Save a matplotlib.pyplot.Figure instance generated from one of this class’ visualize_ methods, as a PDF file.

Parameters:

• fig (-) – matplotlib.pyplot.Figure: Figure instance generated from either Verifier.visualize_comparison() or Verifier.visualize_outputs().

• save_dest (-) – str: Destination path to save the plot to.

get_job_status(job_id: str)

get_observables(data: Dict) → DataFrame

Get the observables passed within data as a flattened dataframe in which each column is: <SPECIES NAME>_<SIMULATOR> for each species name and simulator involved within the comparison.

Parameters:

• data (-) – Dict: simulation output data generated from Verifier.get_verify_output(). This method assumes a resulting job status from the aforementioned get method as being ‘COMPLETED’. Tip: if the data does not yet have a completed status, try again.

• simulators (-) – List[str]: list of simulators to include in the dataframe.

Returns:

pd.DataFrame of observables.

get_output(job_id: str, download_dest: str | None = None, filename: str | None = None) → Dict[str, str | Dict] | RequestError

Fetch the current state of the job referenced with job_id. If the job has not yet been processed, it will return a status of PENDING. If the job is being processed by the service at the time of return, status will read IN_PROGRESS. If the job is complete, the job state will be returned, optionally with included result data (either JSON or downloadable file data).

Parameters:

• job_id (-) – str: The id of the job submission.

• download_dest (-) – Optional[str]: Optional directory where the file will be downloaded if the output is a file. Defaults to the current directory.

• filename (-) – Optional[str]: Optional filename to save the downloaded file as if the output is a file. If not provided, the filename will be extracted from the Content-Disposition header.

Returns:

If the output is a JSON response, return the parsed JSON as a dictionary. If the output is a file, download the file and return the filepath. If an error occurs, return a RequestError.

read_observables(csv_path: str) → DataFrame

Read in a dataframe generated from Verifier.export_csv().

select_observables(observables: List[str], data: Dict) → Dict

Select data from the input data that is passed which should be formatted such that the data has mappings of observable names to dicts in which the keys are the simulator names and the values are arrays. The data must have content accessible at: data[‘content’][‘results’].

class bio_compose.data_model.DynamicJson(data: Dict[Any, Any])

Bases: object

Dynamically create a JSON-like object from a dictionary/mapping of any shape.

class bio_compose.data_model.RequestError(error: str)

Bases: object

error: str

to_dict()

bio_compose.data_model.fetch_job(func)

Decorator for Api().visualize_ methods.

Parameters:

func (-) – Callable: Decorated Api().visualize_ method. Currently only implemented in Verifier().

bio_compose.data_model.save_plot(func)

Decorator for Api().visualize_ methods.

Parameters:

func (-) – Callable: Decorated Api().visualize_ method. Currently only implemented in Verifier().

bio_compose.processing_tools

bio_compose.processing_tools.generate_color_gradient(data_names) → List[str]

Generate a gradient of colors from red to green to blue for a list of data names.

Parameters:

data_names (-) – list[str]: Arbitrary list of data names. A hex color code will be generated for each data name.

Returns:

List of hex color codes for each name in data_names.

bio_compose.processing_tools.get_job_signature(job_id: str) → str

bio_compose.runner

class bio_compose.runner.SimulationResult(data: dict)

Bases: dict

visualize(**kwargs)

Visualize simulation output (observables) data.

Parameters:

**kwargs** –

Visualization kwargs are as follows:

job_id: str: job id for the simulation observables output you wish to visualize. hspace: float: horizontal spacing between subplots. Defaults to 0.25. use_grid: bool: whether to use a grid for each subplot. Defaults to False. save_dest: str: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.

Returns:

Tuple[matplotlib.Figure, Dict] of matplotlib Figure and simulation observables.

Raises:

IOError – If job_id does not contain a ‘results’ field.

class bio_compose.runner.SimulationRunner

Bases: Api

API which handles all aspects of running either UTC or Smoldyn (Brownian Motion) simulations using the REST API.

A new instance of the SimulationRunner class. NOTE: this may clash with your record keeping in a notebook, so it is highly recommended that users treat instances of this class as quasi-singletons, although not necessary for fundamental interaction.

generate_simularium_file(smoldyn_output_filepath: str, box_size: float, filename: str | None = None) → Dict

Run a Smoldyn simulation and generate a Simularium trajectory from the aforementioned simulation’s outputs.

Parameters:

• smoldyn_output_filepath (-) – str: The path to the Smoldyn output file for the given model simulation.

• box_size (-) – float: The box size to use for the Simularium trajectory.

• filename (-) – str: The name of the Simularium file that is generated. If None is passed, a general ‘simulation.simularium’ filename will be used. Defaults to None.

Returns:

The response for the Simularium submission request.

run_smoldyn_simulation(smoldyn_configuration_filepath: str, duration: int | None = None, dt: float | None = None) → Dict

Run a smoldyn simulation using a standard Smoldyn configuration file. Please see https://www.smoldyn.org/SmoldynManual.pdf for more information on running simulations with Smoldyn.

Parameters:

• smoldyn_configuration_filepath (-) – str: The path to the Smoldyn configuration file for the given model simulation.

• duration (-) – int: The duration of the simulation. If None is passed, duration inference will be attempted using time_stop parameter within the Smoldyn configuration. Defaults to None.

• dt (-) – float: The timestep to use within the Smoldyn simulation. If None is passed, dt inference will be attempted using the .dt parameter of the loaded Smoldyn simulation. Defaults to None.

Returns:

The response for the Smoldyn simulation submission request.

run_utc_simulation(sbml_filepath: str, start: int, end: int, steps: int, simulator: str) → Dict

Run a uniform time course simulation of the model specified in sbml_filepath with a supported simulator.

Parameters:

• sbml_filepath (-) – str: The path to a valid SBML file.

• start (-) – int: The start time of the simulation.

• end (-) – int: The end time of the simulation.

• steps (-) – int: The number of steps to record within the ODE.

• simulator (-) – str: The simulator to use. Currently, simulator choices include: ‘amici’, ‘copasi’, or ‘tellurium’.

Returns:

The response for the UTC simulation submission request.

visualize_observables(job_id: str, hspace: float = 0.25, use_grid: bool = False, save_dest: str = None)

Visualize simulation output (observables) data.

Parameters:

• job_id (-) – str: job id for the simulation observables output you wish to visualize.

• hspace (-) – float: horizontal spacing between subplots. Defaults to 0.25.

• use_grid (-) – bool: whether to use a grid for each subplot. Defaults to False.

• save_dest (-) –

  str: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.

  Returns:

  Tuple[matplotlib.Figure, Dict] of matplotlib Figure and simulation observables.

Raises:

IOError – If job_id does not contain a ‘results’ field.

bio_compose.verifier

class bio_compose.verifier.VerificationResult(data: dict)

Bases: dict

get_comparison(save_dest: str | None = None, fig_dimensions: tuple[int, int] | None = None, color_mapping: list[str] | None = None)

Visualize the root-mean-squared error between simulator verification outputs as a heatmap.

Parameters:

• save_dest – (str) destination at which to save figure. Defaults to None.

• fig_dimensions – (Tuple[int, int], optional) The value to use as the figsize parameter for a call to matplotlib.pyplot.figure(). If None is passed, default to (8, 6).

• color_mapping – (List[str], optional) list of colors to use for each simulator in the grid. Defaults to None.

Returns:

matplotlib Figure and simulator RMSE scores

Return type:

Tuple[matplotlib.Figure, Dict]

get_output_observables(save_dest: str | None = None, hspace: float = 0.25, use_grid: bool = False)

Visualize simulation output (observables) data, not comparison data, with subplots for each species.

Parameters:

• save_dest – (str) path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.

• hspace – (float) horizontal spacing between subplots. Defaults to 0.25.

• use_grid – (bool) whether to use a grid for each subplot. Defaults to False.

Returns:

matplotlib Figure and simulation observables indexed by simulator

Return type:

Tuple[matplotlib.Figure, Dict]

class bio_compose.verifier.Verifier

Bases: Api

API for verifying (running and comparing) the results of multiple simulators for a given SBML model.

A new instance of the Verifier class. NOTE: this may clash with your record keeping in a notebook, so it is highly recommended that users treat instances of this class as quasi-singletons, although not necessary for fundamental interaction.

get_compatible(file: str, versions: bool = False) → List[Tuple[Any, ...]] | RequestError

Get all simulators and optionally their versions for a given file. The File is expected to be either an OMEX/COMBINE archive or SBML file.

Parameters:

• file (-) – str: The path to the file to be checked.

• versions (-) – bool: Whether to return the compatible version of the given compatible simulator. Defaults to False.

Returns:

A dictionary of compatible simulators and the referenced file.

get_rmse(job_id: str) → dict

Get root-mean-square error scoring for all simulators involved in the last completed verification job.

Parameters:

job_id (-) – str: The unique identifier for the verification job.

Returns:

A dictionary mapping of simulator names to their respective root-mean-square error scores.

verify_omex(omex_filepath: str, simulators: List[str] | None = None, include_outputs: bool = True, comparison_id: str | None = None, expected_results: str | None = None, selection_list: List[str] | None = None, rTol: float | None = None, aTol: float | None = None, _steady_state: bool = False) → Dict[str, str] | RequestError

Submit a new uniform time course comparison job to the service and return confirmation of job submission.

Parameters:

• omex_filepath (-) – str: The path to the omex file to submit.

• simulators (-) – List[str]: The list of simulators to include in comparison. Defaults to all utc simulators (amici, copasi, tellurium)

• include_outputs (-) – bool, optional: Whether to include the output data used to calculate comparison in the job results on result fetch. Defaults to True.

• comparison_id (-) – str, optional: The unique identifier for the comparison job. Defaults to None. If None is passed, a comparison id of bio_check-request-<UUID> is generated.

• expected_results (-) – str, optional: The path to the ground expected_results report file to include in comparison. Defaults to None.

• selection_list (-) – List[str], optional: The list of observables to include in comparison output. Defaults to None (all observables).

• rTol (-) – float, optional: The relative tolerance used to determine the relative distance in a pairwise comparison.

• aTol (-) – float, optional: The absolute tolerance used to determine the absolute distance in a pairwise comparison.

• _steady_state (-) – bool, optional: Whether to include the steady state analysis job. NOTE: This feature will currently throw an error as it is not yet implemented.

Returns:

the return status should read PENDING.

Return type:

A dictionary containing the job submission results. Note

verify_sbml(entrypoint: str, start: int = 0, end: int = 10, steps: int = 10, simulators: List[str] | None = None, include_outputs: bool = True, comparison_id: str | None = None, expected_results: str | None = None, rTol: float | None = None, aTol: float | None = None, selection_list: List[str] | None = None, _steady_state: bool = False) → Dict[str, str] | RequestError

Submit a new uniform time course comparison job to the service and return confirmation of job submission.

Parameters:

• entrypoint (-) – str: One of either: a path to a sbml OR an antimony model/string that can be converted to SBML. NOTE: Currently, only SBML is supported as an entrypoint.

• start (-) – int: The start time of the time course to include in comparison.

• end (-) – int: The end of the comparison job in seconds.

• steps (-) – int: The number of steps in the comparison job.

• simulators (-) – List[str], optional: The list of simulators to include in comparison. Defaults to all utc simulators (amici, copasi, tellurium)

• include_outputs (-) – bool, optional: Whether to include the output data used to calculate comparison in the job results on result fetch. Defaults to True.

• comparison_id (-) – str, optional: The unique identifier for the comparison job. Defaults to None. If None is passed, a comparison id of bio_check-request-<UUID> is generated.

• expected_results (-) – str, optional: The path to the ground expected_results report file to include in comparison. Defaults to None.

• rTol (-) – float, optional: The relative tolerance used to determine the relative distance in a pairwise comparison.

• aTol (-) – float, optional: The absolute tolerance used to determine the absolute distance in a pairwise comparison.

• selection_list (-) – List[str], optional: Observables to include in the output. If passed, all observable names NOT in this list will be excluded. Defaults to None (all observables).

• _steady_state (-) – bool, optional: Whether to include the steady state analysis job. NOTE: This feature will currently throw an error as it is not yet implemented.

Returns:

the return status should read PENDING.

Return type:

A dictionary containing the job submission results. Note

visualize_comparison(data: Dict, simulators: List[str], comparison_type='proximity', color_mapping: List[str] | None = None) → Figure

Visualize simulation comparison matrix in the form of a heatmap.

Parameters:

• data (-) – dict: simulation output data

• simulators (-) – list[str]: list of simulators

• comparison_type (-) – str: type of comparison. Defaults to ‘proximity’.

• color_mapping (-) – list[str]: list of colors to use for True and False responses. Defaults to None.

Returns:

matplotlib.pyplot.Figure of a plot grid

visualize_observables(job_id: str, hspace: float = 0.25, use_grid: bool = False, save_dest: str = None)

Visualize simulation output (observables) data, not comparison data, with subplots for each species.

Parameters:

• job_id (-) – str: job id for the simulation observable output you wish to visualize.

• hspace (-) – float: horizontal spacing between subplots. Defaults to 0.25.

• use_grid (-) – bool: whether to use a grid for each subplot. Defaults to False.

• save_dest (-) –

  str: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.

  Returns:

  Tuple[matplotlib.Figure, Dict] of matplotlib Figure and simulation observables indexed by simulator

Raises:

IOError – If job_id does not contain a ‘results’ field.

visualize_rmse(job_id: str, fig_dimensions: tuple[int, int] = None, color_mapping: list[str] = None, save_dest: str = None)

Visualize the root-mean-squared error between simulator verification outputs as a heatmap.

Parameters:

• job_id – (str) verification job id. This value can be easily derived from either of Verifier’s .verify_… methods.

• fig_dimensions – (Tuple[int, int], optional) The value to use as the figsize parameter for a call to matplotlib.pyplot.figure(). If None is passed, default to (8, 6).

• color_mapping – (List[str], optional) list of colors to use for each simulator in the grid. Defaults to None.

• save_dest – (str) destination at which to save figure. Defaults to None.

Returns:

matplotlib Figure and simulator RMSE scores

Return type:

Tuple[matplotlib.Figure, Dict]