simulariumio 1.13.0

Python package that converts simulation outputs to the format consumed by the Simularium viewer website

Simularium repositories

This repository is part of the Simularium project (simularium.allencell.org), which includes repositories:

• simulariumIO - Python package that converts simulation outputs to the format consumed by the Simularium viewer website
• simularium-engine - C++ backend application that interfaces with biological simulation engines and serves simulation data to the front end website
• simularium-viewer - NPM package to view Simularium trajectories in 3D
• simularium-website - Front end website for the Simularium project, includes the Simularium viewer

---

---

SimulariumIO

---

---

Convert simulation outputs so they can be visualized in the Simularium Viewer.

1. Convert your data

Save your data as a .simularium file (click to see full file format (see Jupyter notebook examples):

import numpy as np
from simulariumio import TrajectoryConverter, TrajectoryData, MetaData, AgentData, ScatterPlotData

converter = TrajectoryConverter(
    TrajectoryData(
        meta_data=MetaData(
            box_size=BOX_SIZE_NUMPY_ARRAY,
            trajectory_title="Model A with parameter set 1",
        ),
        agent_data=AgentData(
            DATA_FOR_OBJECTS_MOVING_OVER_TIME
        ),
    )
)
converter.add_plot(
    ScatterPlotData(
        title="Something measured",
        xaxis_title="Time (s) or something else",
        yaxis_title="Some measurement (units)",
        xtrace=X_VALUES_NUMPY_ARRAY,
        ytraces={
            "Agent 1" : Y_VALUES_NUMPY_ARRAY,
        },
    )
)
converter.save("output_file_name")

See more details

2. Load in the Simularium Viewer

Load your file in the Simularium Viewer at https://simularium.allencell.org/viewer to interactively rotate and play back your data:

See more details

3. Share by URL

Upload your file to a public Dropbox or Google Drive folder or an AWS S3 bucket, and use the URL https://simularium.allencell.org/viewer?trajUrl=LINK_TO_YOUR_FILE. For example, https://simularium.allencell.org/viewer?trajUrl=https://aics-simularium-data.s3.us-east-2.amazonaws.com/trajectory/endocytosis.simularium.

See more details

---

---

Features

• Converts 3D spatiotemporal trajectories to .simularium JSON format
• Accepts spatial trajectories from the following biological simulation engines:
  • CytoSim (https://gitlab.com/f.nedelec/cytosim)
  • MCell (https://mcell.org/)
  • MEDYAN (http://medyan.org/)
  • PhysiCell (http://physicell.org/)
  • ReaDDy (https://readdy.github.io/)
  • Smoldyn (http://www.smoldyn.org/)
  • SpringSaLaD (https://vcell.org/ssalad)
  • Molecular dynamics trajectories via MDAnalysis (https://www.mdanalysis.org/)
• Conversions for data from custom engines can be implemented using the TrajectoryConverter class
• Also accepts metrics data for plots to display alongside spatial data

We're discussing the possibility of adding the ability to export Simularium files directly with the authors of some packages.

Current rendering capabilities of the viewer:

• Spheres: by default, each agent in a scene is represented as a single sphere
• Mesh surfaces: represent each agent as a mesh (loaded from an .obj file), e.g. coarse molecular surfaces
• Multi-sphere: provide Protein Databank .pdb files
• Line representations for fibers, filaments, or bonds

Rendering capabilities planned for future:

• Volume rendering for RDME or PDE-based simulation results
• Support for .cif files and coarse-grain sphereTree files for multi-sphere rendering

---

Installation

Install Requires:

• Requires Python 3.9 or 3.10

• If ReaDDy trajectories will be converted, the ReaDDy python package must be installed: (add conda forge channel if it's not already: conda config --add channels conda-forge) conda install readdy

Stable Release: pip install simulariumio

Development Head: pip install git+ssh://[e-mail]/simularium/simulariumio.git

Please note that to run the Jupyter notebook examples you should also install Jupyter, either with pip install jupyter, or by installing SimulariumIO with the tutorial requirements: pip install simulariumio[tutorial]

Install time depends on the speed of the connection and whether optional dependencies are included, but generally takes 30 seconds to a few minutes (see benchmarks for more details).

---

Quick Start

Convert spatial trajectory from a supported engine

See the Tutorial for the simulation engine you're using for details:

• Cytosim Tutorial
• MCell Tutorial
• MEDYAN Tutorial
• PhysiCell Tutorial
• ReaDDy Tutorial
• Smoldyn Tutorial
• SpringSaLaD Tutorial
• Molecular Dynamics Tutorial

An overview for data from ReaDDy:

import numpy as np
from simulariumio.readdy import ReaddyConverter, ReaddyData

# see ReaDDy Tutorial for parameter details
input_data = ReaddyData(
    meta_data=MetaData(
        box_size=BOX_SIZE,
    ),
    timestep=TIMESTEP,
    path_to_readdy_h5=PATH_TO_H5_FILE,
)
ReaddyConverter(input_data).save("output_file_name")

Convert spatial trajectory from a custom engine

See the Custom Data Tutorial for details. An overview:

import numpy as np
from simulariumio import TrajectoryConverter, TrajectoryData, MetaData, AgentData

# see Custom Data Tutorial for parameter details
input_data = TrajectoryData(
    meta_data=MetaData(
        box_size=BOX_SIZE,
    ),
    agent_data=AgentData(
        times=TIMES,
        n_agents=N_AGENTS,
        viz_types=VIZ_TYPES,
        unique_ids=UNIQUE_IDS,
        types=TYPE_IDS,
        positions=POSITIONS,
        radii=RADII,
        rotations=ROTATIONS,
    )
)
TrajectoryConverter(input_data).save("output_file_name")

Add metrics data to plot

See the Plots Tutorial for details. An overview:

import numpy as np
from simulariumio import ScatterPlotData

converter = TrajectoryConverter(input_data) # see above to create 
# see Plots Tutorial for parameter details
converter.add_plot(
    ScatterPlotData(
        title="Something measured",
        xaxis_title="Time (s) or something else",
        yaxis_title="Some measurement (units)",
        xtrace=X_VALUES,
        ytraces={
            "Agent 1" : Y_VALUES,
        },
    )
)
converter.save("output_file_name")

Render with meshes or PDB files

If you'd like to render agents as meshes instead of spheres, add a DisplayData for each agent type you'd like to be rendered with the mesh, and specify an OBJ mesh file. Alternately, you can provide a Protein Databank (PDB) file to render atoms for a molecule.

See the example notebook for the converter you are using to see how to add display data for that converter.

display_data={
    "A" : DisplayData(
        name="Molecule A",
        display_type=DISPLAY_TYPE.PDB,
        url="https://files.rcsb.org/download/3KIN.pdb",
        color="#0080ff",
    ),
    "B" : DisplayData(
        name="Molecule B",
        display_type=DISPLAY_TYPE.OBJ,
        url="molecule_b.obj",
        color="#333333",
    ),
}

Conversion time depends on hardware, the size of the input data, and which converter is used, but generally takes between less than a minute and five minutes (see benchmarks for more details).

---

Visualize results

1. In a supported browser (Firefox, Chrome, or Edge), navigate to https://simularium.allencell.org/viewer.
2. Drag the file output from SimulariumIO from your file browser onto the window or choose Load model > From your device, and select your file from the file upload dialogue.

• If your trajectory uses local geometry files, like .obj or .pdb files, load them at the same time as you load your .simularium file, either by dragging and dropping a collection of files, or by choosing multiple files in the upload dialogue.
• Currently the Viewer does not support loading folders of files, so make sure you are loading a collection of single files that does not include a folder. We're working to improve this.

---

Share link to results

1. Upload your Simularium file to one of the supported public cloud providers, including Dropbox, Google Drive, or Amazon S3, and get a publicly accessible link to the file.
2. In a supported browser (Firefox, Chrome, or Edge), navigate to https://simularium.allencell.org.
3. Choose Load model > From a URL. In the dialog, provide the URL to your .simularium file and choose Load.

• If your file uses geometry files, like .obj or .pdb files, make sure you've provided the full public URL to the files in DisplayData.

4. Once the file is loaded, you can copy the page URL and share this link with collaborators or post it on your website so that others can interactively view your results.

---

Documentation

For full package documentation please visit simularium.github.io/simulariumio.

---

Development

See CONTRIBUTING.md for information related to developing the code.