Simularium Conversion helps convert simulation outputs to the format consumed by the Simularium viewer.
Project description
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
Simulariumio converts simulation outputs to the format consumed by the Simularium viewer.
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)
- 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 working to improve performance for converting large trajectories, and also discussing with the authors of some packages the possibility of adding the ability to export Simularium files directly.
Visualize results
- In a supported browser (Firefox, Chrome, or Edge), navigate to https://simularium.allencell.org/viewer.
- Drag the file output from SimulariumIO from your file browser onto the window or use the file upload dialogue to choose your file
Sharing links to results
- Upload your Simularium file to one of the supported public cloud providers, currently Dropbox, Google Drive, or Amazon S3, and get a publicly accessible link to the file.
- In a supported browser, navigate to https://simularium.allencell.org/viewer?trajUrl=[link to your file]. You can share this link with collaborators or post it on your website so that others can interactively view your results.
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
An overview for data from ReaDDy:
from simulariumio.readdy import ReaddyConverter, ReaddyData
# see ReaDDy Tutorial for parameter details
input_data = ReaddyData(
box_size=BOX_SIZE,
timestep=TIMESTEP,
path_to_readdy_h5=PATH_TO_H5_FILE,
)
ReaddyConverter(input_data).write_JSON("output_file_name")
Convert spatial trajectory from a custom engine
See the Custom Data Tutorial for details. An overview:
from simulariumio import TrajectoryConverter, TrajectoryData, AgentData
# see Custom Data Tutorial for parameter details
input_data = TrajectoryData(
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).write_JSON("output_file_name")
Add metrics data to plot
See the Plots Tutorial for details. An overview:
from simulariumio import ScatterPlotData
# see Plots Tutorial for parameter details
example_scatter_plot = ScatterPlotData(
title=TITLE,
xaxis_title=X_TITLE,
yaxis_title=Y_TITLE,
xtrace=X_VALUES,
ytraces=Y_VALUES,
)
converter = TrajectoryConverter(input_data) # see above to create converter
converter.add_plot(example_scatter_plot, "scatter")
converter.write_JSON("output_file_name")
Installation
Install Requires:
-
Requires Python 3.7 or 3.8
-
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 -c readdy readdy
Stable Release: pip install simulariumio
Development Head: pip install git+https://github.com/allen-cell-animated/simulariumio.git
Documentation
For full package documentation please visit allen-cell-animated.github.io/simulariumio.
Development
See CONTRIBUTING.md for information related to developing the code.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for simulariumio-1.2.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d0060df4d3cbffcd12901b111c46ea5d4a416fe6483eed0b3980f1398d00b37b |
|
MD5 | ac5c85ae8308f1a13869c9aac8827f21 |
|
BLAKE2b-256 | 55784d89da0db367ef74ccb919e3ca1f7cb8378458e8f9e30c6d5a4c356e9f96 |