examples/Tutorial_physicell.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simularium Conversion Tutorial : PhysiCell Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "import numpy as np\n",
    "from simulariumio.physicell import PhysicellConverter, PhysicellData\n",
    "from simulariumio import UnitData, MetaData, DisplayData, DISPLAY_TYPE, ModelMetaData"
   ]
  },
  {
   "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 PhysiCell, use `pip install simulariumio[physicell]`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "## Prepare your spatial data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Simularium `PhysicellConverter` consumes discrete cell data from PhysiCell. \n",
    "\n",
    "The converter requires a `PhysicellData` object as a parameter ([see documentation](https://simularium.github.io/simulariumio/simulariumio.physicell.html#simulariumio.physicell.physicell_data.PhysicellData)).\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",
    "\n",
    "example_data = PhysicellData(\n",
    "    timestep=360.0,\n",
    "    path_to_output_dir=\"../simulariumio/tests/data/physicell/default_output/\",\n",
    "    meta_data=MetaData(\n",
    "        box_size=np.array([box_size, box_size, 100.0]),\n",
    "        scale_factor=0.01,\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",
    "    nth_timestep_to_read=2,\n",
    "    display_data={\n",
    "        0: DisplayData(\n",
    "            name=\"tumor cell\",\n",
    "            display_type=DISPLAY_TYPE.OBJ,\n",
    "            url=\"tumor_cell.obj\",\n",
    "            color=\"#dfdacd\",\n",
    "        ),\n",
    "        1: DisplayData(\n",
    "            name=\"motile tumor cell\",\n",
    "            display_type=DISPLAY_TYPE.SPHERE,\n",
    "            color=\"#0080ff\",\n",
    "        ),\n",
    "    },\n",
    "    phase_names={\n",
    "        0: {4: \"G0G1\"},\n",
    "        1: {4: \"G0G1\"},\n",
    "    },\n",
    "    time_units=UnitData(\"s\"),  # seconds\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 PhysiCell Data -------------\n",
      "Reading ../simulariumio/tests/data/physicell/output/output00000000.xml\n",
      "Reading ../simulariumio/tests/data/physicell/output/initial_mesh0.mat\n",
      "Reading ../simulariumio/tests/data/physicell/output/output00000000_cells_physicell.mat\n",
      "Reading ../simulariumio/tests/data/physicell/output/output00000002.xml\n",
      "Reading ../simulariumio/tests/data/physicell/output/initial_mesh0.mat\n",
      "Reading ../simulariumio/tests/data/physicell/output/output00000002_cells_physicell.mat\n",
      "Converting Trajectory Data to Binary -------------\n",
      "Writing Binary -------------\n",
      "saved to example_physicell.simularium\n"
     ]
    }
   ],
   "source": [
    "PhysicellConverter(example_data).save(\"example_physicell\")"
   ]
  },
  {
   "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
}