examples/Tutorial_medyan.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simularium Conversion Tutorial : MEDYAN Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "import numpy as np\n",
    "from simulariumio.medyan import MedyanConverter, MedyanData\n",
    "from simulariumio import MetaData, DisplayData, ModelMetaData, BinaryWriter, InputFileData, DISPLAY_TYPE\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": [
    "***\n",
    "## Prepare your spatial data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Simularium `MedyanConverter` consumes discrete cell data from MEDYAN. \n",
    "\n",
    "The converter requires a `MedyanData` object as a parameter ([see documentation](https://simularium.github.io/simulariumio/simulariumio.medyan.html#simulariumio.medyan.medyan_data.MedyanData)).\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 = 1000.0\n",
    "scale = 0.1\n",
    "\n",
    "example_data = MedyanData(\n",
    "    meta_data=MetaData(\n",
    "        box_size=np.array([box_size, box_size, box_size]),\n",
    "        scale_factor=scale,\n",
    "        trajectory_title=\"Some parameter set\",\n",
    "        model_meta_data=ModelMetaData(\n",
    "            title=\"Some agent-based model\",\n",
    "            version=\"8.1\",\n",
    "            authors=\"A Modeler\",\n",
    "            description=(\n",
    "                \"An agent-based 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",
    "    snapshot_file=InputFileData(\n",
    "        file_path=\"../simulariumio/tests/data/medyan/snapshot.traj\"\n",
    "    ),\n",
    "    filament_display_data={\n",
    "        0: DisplayData(\n",
    "            name=\"Filament\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            radius=5.0,\n",
    "            color=\"#ff1493\",\n",
    "        ),\n",
    "    },\n",
    "    linker_display_data={\n",
    "        0: DisplayData(\n",
    "            name=\"LinkerA\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            radius=8.0,\n",
    "            color=\"#ffffff\",\n",
    "        ),\n",
    "        1: DisplayData(\n",
    "            name=\"LinkerB\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            radius=8.0,\n",
    "        ),\n",
    "        2: DisplayData(\n",
    "            name=\"LinkerC\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            radius=8.0,\n",
    "        ),\n",
    "    },\n",
    "    motor_display_data={\n",
    "        1: DisplayData(\n",
    "            name=\"Motor\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            radius=2.0,\n",
    "            color=\"#0080ff\",\n",
    "        ),\n",
    "    },\n",
    "    agents_with_endpoints=[\"Motor\"],\n",
    "    center=True,\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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Reading MEDYAN Data -------------\n",
      "Filtering: translation -------------\n",
      "Converting Trajectory Data to Binary -------------\n",
      "Writing Binary -------------\n",
      "saved to example_medyan.simularium\n"
     ]
    }
   ],
   "source": [
    "MedyanConverter(example_data).save(\"example_medyan\")"
   ]
  },
  {
   "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
}