examples/Tutorial_md.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simularium Conversion Tutorial : MD Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "\n",
    "import numpy as np\n",
    "from MDAnalysis import Universe\n",
    "from MDAnalysis.tests.datafiles import PSF, DCD\n",
    "\n",
    "from simulariumio.md import MdConverter, MdData\n",
    "from simulariumio import UnitData, MetaData, DisplayData, DISPLAY_TYPE, ModelMetaData, InputFileData\n",
    "from simulariumio.filters import TranslateFilter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook provides example python code for converting your own simulation trajectories into the format consumed by the Simularium Viewer. It creates a .simularium file which you can drag and drop onto the viewer like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![title](img/drag_drop.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# _Note:_\n",
    "To install simulariumio with all depencies needed for MD, use `pip install simulariumio[md]`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "## Prepare your spatial data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Simularium `MdConverter` consumes spatiotemporal data from molecular dynamics outputs using the MDAnalysis Python package. \n",
    "\n",
    "The converter requires a `MdData` object as a parameter ([see documentation](https://simularium.github.io/simulariumio/simulariumio.md.html#simulariumio.md.md_data.MdData)), which requires a MDAnalysis `Universe` object ([see documentation](https://docs.mdanalysis.org/stable/documentation_pages/core/universe.html))\n",
    "\n",
    "If you'd like to specify PDB or OBJ files or color for rendering an agent type, add a `DisplayData` object for that agent type, as shown below ([see documentation](https://simularium.github.io/simulariumio/simulariumio.data_objects.html#module-simulariumio.data_objects.display_data)).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_size = 100.\n",
    "\n",
    "example_data = MdData(\n",
    "    md_universe=Universe(PSF, DCD),\n",
    "    meta_data=MetaData(\n",
    "        box_size=np.array([box_size, box_size, box_size]),\n",
    "        trajectory_title=\"Some parameter set\",\n",
    "        model_meta_data=ModelMetaData(\n",
    "            title=\"Some molecular dynamics model\",\n",
    "            version=\"8.1\",\n",
    "            authors=\"A Modeler\",\n",
    "            description=(\n",
    "                \"A molecular dynamics model run with some parameter set\"\n",
    "            ),\n",
    "            doi=\"10.1016/j.bpj.2016.02.002\",\n",
    "            source_code_url=\"https://github.com/simularium/simulariumio\",\n",
    "            source_code_license_url=\"https://github.com/simularium/simulariumio/blob/main/LICENSE\",\n",
    "            input_data_url=\"https://allencell.org/path/to/native/engine/input/files\",\n",
    "            raw_output_data_url=\"https://allencell.org/path/to/native/engine/output/files\",\n",
    "        ),\n",
    "    ),\n",
    "    display_data={\n",
    "        # Atom colors (from Jmol) and abbreviations will be added automatically,\n",
    "        # but you can override them by providing colors and/or names here\n",
    "        \"S\": DisplayData(\n",
    "            name=\"Sulfur\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            color=\"#FF00FF\",\n",
    "        ),\n",
    "    },\n",
    "    time_units=UnitData(\"ps\"),  # picoseconds\n",
    "    spatial_units=UnitData(\"pm\"),  # picometers\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Convert and save as .simularium file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once your data is shaped like in the `example_data` object, you can use the converter to generate the file at the given path:\n",
    "\n",
    "(since this model's coordinates are all positive, use a `TranslateFilter` to center the data in the viewer.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Reading MD Data -------------\n",
      "Converting Trajectory Data to Binary -------------\n",
      "Writing Binary -------------\n",
      "saved to example_md.simularium\n"
     ]
    }
   ],
   "source": [
    "MdConverter(example_data).save(\"example_md\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualize in the Simularium viewer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a supported web-browser (Firefox or Chrome), navigate to https://simularium.allencell.org/ and import your file into the view."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}