Package: simulariumio
Simularium repositoriesThis 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 websitesimularium-engine- C++ backend application that interfaces with biological simulation engines and serves simulation data to the front end websitesimularium-viewer- NPM package to view Simularium trajectories in 3Dsimularium-website- Front end website for the Simularium project, includes the Simularium viewerSimulariumIOConvert simulation outputs so they can be visualized in theSimularium Viewer.1. Convert your dataSave your data as a .simularium file (see Jupyter notebookexamples):importnumpyasnpfromsimulariumioimportTrajectoryConverter,TrajectoryData,MetaData,AgentData,ScatterPlotDataconverter=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 details2. Load in theSimularium ViewerLoad your file in the Simularium Viewer athttps://simularium.allencell.org/viewerto interactively rotate and play back your data:See more details3. Share by URLUpload your file to a public Dropbox or Google Drive folder or an AWS S3 bucket, and use the URLhttps://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 detailsFeaturesConverts 3D spatiotemporal trajectories to .simularium JSON formatAccepts 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 classAlso accepts metrics data for plots to display alongside spatial dataWe'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 sphereMesh surfaces: represent each agent as a mesh (loaded from an .obj file), e.g. coarse molecular surfacesMulti-sphere: provide Protein Databank .pdb filesLine representations for fibers, filaments, or bondsRendering capabilities planned for future:Volume rendering for RDME or PDE-based simulation resultsSupport for .cif files and coarse-grain sphereTree files for multi-sphere renderingInstallationInstall Requires:Requires Python 3.7, 3.8, or 3.9If 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 readdyStable Release:pip install simulariumioDevelopment Head:pip install git+ssh://git@github.com/simularium/simulariumio.gitPlease notethat to run the Jupyter notebook examples you should also install Jupyter, either withpip install jupyter, or by installing SimulariumIO with the tutorial requirements:pip install simulariumio[tutorial]Install timedepends on the speed of the connection and whether optional dependencies are included, but generally takes 30 seconds to a few minutes (seebenchmarksfor more details).Quick StartConvert spatial trajectory from a supported engineSee the Tutorial for the simulation engine you're using for details:Cytosim TutorialMCell TutorialMEDYAN TutorialPhysiCell TutorialReaDDy TutorialSmoldyn TutorialSpringSaLaD TutorialMolecular Dynamics TutorialAn overview for data from ReaDDy:importnumpyasnpfromsimulariumio.readdyimportReaddyConverter,ReaddyData# see ReaDDy Tutorial for parameter detailsinput_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 engineSee theCustom Data Tutorialfor details. An overview:importnumpyasnpfromsimulariumioimportTrajectoryConverter,TrajectoryData,MetaData,AgentData# see Custom Data Tutorial for parameter detailsinput_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 plotSee thePlots Tutorialfor details. An overview:importnumpyasnpfromsimulariumioimportScatterPlotDataconverter=TrajectoryConverter(input_data)# see above to create# see Plots Tutorial for parameter detailsconverter.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 filesIf you'd like to render agents as meshes instead of spheres, add aDisplayDatafor 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 timedepends on hardware, the size of the input data, and which converter is used, but generally takes between less than a minute and five minutes (seebenchmarksfor more details).Visualize resultsIn a supported browser (Firefox, Chrome, or Edge), navigate tohttps://simularium.allencell.org/viewer.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 resultsUpload 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.In a supported browser (Firefox, Chrome, or Edge), navigate tohttps://simularium.allencell.org.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 inDisplayData.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.DocumentationFor full package documentation please visitsimularium.github.io/simulariumio.DevelopmentSeeCONTRIBUTING.mdfor information related to developing the code.