Simularium代码库

此代码库是Simularium项目（simularium.allencell.org）的一部分，该项目包括以下代码库：

• simulariumIO - Python包，将仿真输出转换为Simularium查看器网站所需的格式
• simularium-engine - C++后端应用程序，与生物仿真引擎接口，并向前端网站提供仿真数据
• simularium-viewer - NPM包，用于在3D中查看Simularium轨迹
• simularium-website - Simularium项目的客户端网站，包括Simularium查看器

SimulariumIO

将仿真输出转换为可在Simularium查看器中可视化的格式。

1. 转换您的数据

将您的数据保存为.simularium文件（点击查看完整文件格式（请参阅Jupyter笔记本示例）

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")

查看更多详细信息

2. 在Simularium查看器中加载

在https://simularium.allencell.org/viewer的Simularium查看器中加载您的文件，以交互式旋转和回放您的数据

查看更多详细信息

3. 通过URL共享

将您的文件上传到公共Dropbox或Google Drive文件夹或AWS S3桶中，并使用以下URL https://simularium.allencell.org/viewer?trajUrl=LINK_TO_YOUR_FILE。例如，https://simularium.allencell.org/viewer?trajUrl=https://aics-simularium-data.s3.us-east-2.amazonaws.com/trajectory/endocytosis.simularium。

查看更多详细信息

功能

• 将3D时空轨迹转换为.simularium JSON格式
• 接受以下生物仿真引擎的空间轨迹
  • CytoSim (https://gitlab.com/f.nedelec/cytosim)
  • MCell (https://mcell.org/)
  • MEDEYAN (http://medyan.org/)
  • PhysiCell (http://physicell.org/)
  • ReaDDy (https://readdy.github.io/)
  • Smoldyn (http://www.smoldyn.org/)
  • SpringSaLaD (https://vcell.org/ssalad)
  • 通过MDAnalysis（https://www.mdanalysis.org/）进行分子动力学轨迹
• 可以使用TrajectoryConverter类实现自定义引擎数据的转换
• 还接受与空间数据一起显示的指标数据

我们正在与一些软件包的作者讨论添加直接导出Simularium文件的能力

查看器的当前渲染能力

• 球体：默认情况下，场景中的每个代理都表示为一个单个球体
• 网格表面：将每个代理表示为网格（从.obj文件加载），例如粗分子表面
• 多球体：提供Protein Databank .pdb文件
• 纤维、细丝或键的线表示

计划中的未来渲染能力

• RDME或PDE模拟结果的体渲染
• 支持多球体渲染的.cif文件和粗粒度sphereTree文件

安装

安装需求

• 需要Python 3.7、3.8或3.9

• 如果将ReaDDy轨迹进行转换，则必须安装ReaDDy Python包：（如果尚未添加conda forge通道，请添加：conda config --add channels conda-forge） conda install readdy

稳定版本： pip install simulariumio

开发头： pip install git+ssh://git@github.com/simularium/simulariumio.git

请注意，要运行Jupyter笔记本示例，您还必须安装Jupyter，可以使用pip install jupyter，或者通过安装SimulariumIO与教程要求一起安装：pip install simulariumio[tutorial]

安装时间取决于连接速度以及是否包含可选依赖项，但通常需要30秒到几分钟（有关更多详细信息，请参阅benchmarks）。

快速入门

从支持该引擎的引擎转换空间轨迹

有关您使用的仿真引擎的详细信息，请参阅教程

• Cytosim教程
• MCell教程
• MEDEYAN教程
• PhysiCell教程
• ReaDDy教程
• Smoldyn教程
• SpringSaLaD教程
• 分子动力学教程

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")

从自定义引擎转换空间轨迹

有关详细信息，请参阅自定义数据教程。概述

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")

将指标数据添加到图表

有关详细信息，请参阅图表教程。概述

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")

使用网格或PDB文件进行渲染

如果您想将代理渲染为网格而不是球体，请为每个需要使用网格进行渲染的代理类型添加一个DisplayData，并指定OBJ网格文件。或者，您还可以提供Protein Databank (PDB)文件以渲染分子的原子。

有关您使用的转换器的示例笔记本，请参阅如何添加该转换器的显示数据。

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",
    ),
}

转换时间取决于硬件、输入数据的大小以及使用的转换器，但通常在不到一分钟到五分钟之间（更多详情请见性能测试）。

可视化结果

1. 在支持的浏览器（Firefox、Chrome或Edge）中，导航到https://simularium.allencell.org/viewer。
2. 将SimulariumIO的文件输出从文件浏览器拖放到窗口中，或者选择“加载模型”>“从您的设备”，然后在文件上传对话框中选择您的文件。

• 如果您的轨迹使用本地几何文件，如.obj或.pdb文件，请在加载.simularium文件的同时加载它们，可以通过拖放文件集合，或者在上传对话框中选择多个文件来实现。
• 目前查看器不支持加载文件文件夹，所以请确保您正在加载的文件集合不包含文件夹。我们正在努力改进这一点。

分享结果链接

1. 将您的Simularium文件上传到支持的公共云提供商之一，包括Dropbox、Google Drive或Amazon S3，并获取可公开访问的文件链接。
2. 在支持的浏览器（Firefox、Chrome或Edge）中，导航到https://simularium.allencell.org。
3. 选择“加载模型”>“从URL”。在对话框中，提供您的.simularium文件的URL，然后选择“加载”。

• 如果您的文件使用几何文件，如.obj或.pdb文件，请确保您已在DisplayData中提供了文件的完整公共URL。

4. 文件加载完成后，您可以复制页面URL，并将此链接与同事分享或发布到您的网站上，以便其他人可以交互式查看您的结果。

文档

有关完整软件包文档，请访问simularium.github.io/simulariumio。

开发

有关代码开发的详细信息，请参阅CONTRIBUTING.md。