BioSimulators recommends Vega for data visualizations of simulation results. Vega is a powerful, declarative grammar for describing interactive, two-dimensional data visualizations.

One key feature of Vega is that it modularly captures the graphical marks which comprise visualizations and how those graphical marks should be painted with data. This feature makes it easy to produce data visualizations for multiple simulation conditions by combining the same graphical marks with results from multiple simulations. This features also makes the provenance of data visualizations transparent. As a result, Vega is ideal for collaboration and publication.

Below, we provide recommendations for using Vega to visualize the results of simulation experiments described with SED-ML.

BioSimulators recommends creating Vega visualizations for simulation results as follows:

1. Create one or more SED-ML files.
2. Use tools such as the Vega Editor and Altair to design the structures of visualizations for the results of the SED-ML files.
3. Encode these diagramatic structures into Vega.

4. Indicate the Vega signals whose attributes should be rendered with the values of the attributes of SED-ML simulations.

   • To render the value of a Vega signal with information from a SED-ML file, add the key sedmlUri to the Vega signal.
   • To render an attribute of the bind attribute of a Vega signal with information from a SED-ML file, set the value of the attribute equal to a dictionary with a single key sedmlUri.

   The value of each sedmlUri key should be a list of the location of the SED-ML document, the id of the SED-ML simulation or report, and the name of the attribute of the simulation or report that the value of the signal or attribute of the bind attribute of the signal should be rendered with (e.g., ['location/of/simulation.sedml', 'simulationId', 'numberOfSteps']). To indicate that a sedmlUri key should be rendered with a list of the values of an attribute of multiple simulations or reports, use SedDocument:*, Simulation:*, or Report:* for the SED-ML document location or simulation/report id (e.g., ['SedDocument:*', 'Report:*', 'id'] to render an attribute with a list of the ids of the all of the reports of all of the SED-ML files in the COMBINE/OMEX archive).

5. Indicate the Vega data sets whose values should be rendered with the results of SED-ML reports by adding a key sedmlUri to such Vega datas. The values of these keys should be set as follows:
   • To render a Vega data set with the results of all of the reports of all of the SED-ML files in the parent COMBINE/OMEX archive, the value of sedmlUri should be set to an empty array ([]).
   • To render a Vega data set with the result of a single report of one of the SED-ML files in the parent COMBINE/OMEX archive, the value of sedmlUri should be set to a list of the location of the SED-ML document and the id of the SED-ML report (e.g., ['location/of/simulation.sedml', 'reportId']).
6. Package the SED-ML and Vega files into a COMBINE/OMEX archive. Include the Vega files in the manifest of the archive with the format http://purl.org/NET/mediatypes/application/vnd.vega.v5+json.

Simulation software tools, such as RunBioSimulations, should render such Vega visualizations linked to SED-ML files in COMBINE/OMEX archives as illustrated below:

1. Execute the SED-ML files in the COMBINE/OMEX archive and save each report.
2. Use the manifest of the archive to identify the Vega visualizations in the archive (contents with the format http://purl.org/NET/mediatypes/application/vnd.vega.v5+json).
3. Extract these Vega visualization files from the archive.
4. Use a JSON library to parse the Vega visualization files.
5. Identify the Vega signals and data sets whose values are intended to be rendered with the values of attributes of simulations of SED-ML documents and the results of reports of SED-ML documents (Vega signals and data sets with the key sedmlUri).
6. Set the values of these Vega signals and data sets equal to the values of the indicated attributes of SED-ML simulations and the resutls of SED-ML reports. As illustrated below, SED-ML reports should be encoded as lists of objects that represent the results of each SED-ML dataset. Data sets with multidimensional values should be captured using nested lists.
7. Use Vega-Embed to render the resultant Vega visualizations.

Several example COMBINE/OMEX archives with Vega visualizations are available here . This includes examples of canonical statistical charts, as well as interactive maps of metabolic networks.

Below are helpful tools for creating Vega visualizations:

• Altair is a Python library which provides methods for generating Vega visualizations similar to packages such as Matplotib and Seaborn.
• Lyra is a interactive graphical program for designing data visualizations.
• Vega Editor is a text editor for Vega documents which continuously renders Vega documents as they are edited.
• Vega-Embed is a JavaScript program for rendering Vega visualizations inside web pages.