examples/Tutorial_plots.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simularium Conversion Tutorial : Adding Plots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "import numpy as np\n",
    "from simulariumio import (\n",
    "    TrajectoryConverter, \n",
    "    TrajectoryData, \n",
    "    AgentData, \n",
    "    UnitData, \n",
    "    MetaData, \n",
    "    ScatterPlotData, \n",
    "    HistogramPlotData,\n",
    ")"
   ]
  },
  {
   "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": [
    "## Create Converter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To demonstrate adding plots, we'll first create a Converter with some example spatial data. Spatial data is required to initialize Converter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from string import ascii_uppercase\n",
    "from random import choice\n",
    "\n",
    "# parameters\n",
    "total_steps = 5\n",
    "timestep = 0.5  # seconds\n",
    "box_size = 100\n",
    "n_agents = 5\n",
    "min_radius = 5\n",
    "max_radius = 10\n",
    "\n",
    "type_names = []\n",
    "for t in range(total_steps):\n",
    "    type_names.append([choice(ascii_uppercase) for i in range(n_agents)])\n",
    "    \n",
    "example_default_data = TrajectoryData(\n",
    "    meta_data=MetaData(\n",
    "        box_size=np.array([box_size, box_size, box_size]),\n",
    "    ),\n",
    "    agent_data=AgentData(\n",
    "        times=timestep * np.array(list(range(total_steps))),\n",
    "        n_agents=np.array(total_steps * [n_agents]),\n",
    "        viz_types=np.array(total_steps * [n_agents * [1000.0]]),  # default viz type = 1000\n",
    "        unique_ids=np.array(total_steps * [list(range(n_agents))]),\n",
    "        types=type_names,\n",
    "        positions=np.random.uniform(size=(total_steps, n_agents, 3)) * box_size - box_size * 0.5,\n",
    "        radii=(max_radius - min_radius) * np.random.uniform(size=(total_steps, n_agents)) + min_radius\n",
    "    ),\n",
    "    time_units=UnitData(\"ns\"),  # nanoseconds\n",
    "    spatial_units=UnitData(\"nm\"),  # nanometers\n",
    ")\n",
    "converter = TrajectoryConverter(example_default_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "## Add plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Metrics data you provide will be graphed in plots alongside your spatial data in the Simularium viewer. For now, Simularium supports scatterplots and histograms."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Scatterplots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Scatterplots require a `ScatterPlotData` object as a parameter ([see documentation](https://simularium.github.io/simulariumio/simulariumio.plot_readers.html#simulariumio.plot_readers.scatter_plot_reader.ScatterPlotReader))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's some random example scatterplot data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_scatter_plot = ScatterPlotData(\n",
    "    title=\"Test Scatterplot 1\",\n",
    "    xaxis_title=\"time (ns)\",\n",
    "    yaxis_title=\"concentration (uM)\",\n",
    "    xtrace=np.array(list(range(10))),\n",
    "    ytraces={\n",
    "        \"agent1\": 100 * np.random.uniform(size=(10)),\n",
    "        \"agent2\": 100 * np.random.uniform(size=(10)),\n",
    "        \"agent3\": 100 * np.random.uniform(size=(10)),\n",
    "    },\n",
    "    render_mode=\"lines\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To add it to the converter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Reading Scatter Plot Data -------------\n"
     ]
    }
   ],
   "source": [
    "converter.add_plot(example_scatter_plot, \"scatter\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Histograms"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Histograms require a `HistogramPlotData` object as a parameter ([see documentation](https://simularium.github.io/simulariumio/simulariumio.plot_readers.html#simulariumio.plot_readers.histogram_plot_reader.HistogramPlotReader))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's some random example histogram data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_histogram = HistogramPlotData(\n",
    "    title=\"Test Histogram 1\",\n",
    "    xaxis_title=\"angle (degrees)\",\n",
    "    traces={\n",
    "        \"crosslinked monomers\": 2 * np.random.uniform(size=(15)),\n",
    "        \"bent monomers\": 10 * np.random.uniform(size=(10)),\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To add it to the converter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Reading Histogram Data -------------\n"
     ]
    }
   ],
   "source": [
    "converter.add_plot(example_histogram, \"histogram\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Save the data with added plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you've added your plot data, write the data to file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Converting Trajectory Data to Binary -------------\n",
      "Writing Binary -------------\n",
      "saved to example_plots.simularium\n"
     ]
    }
   ],
   "source": [
    "converter.save(\"example_plots\")"
   ]
  },
  {
   "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
}