docs/basics/use_nwbwidgets.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e24d7599",
   "metadata": {},
   "source": [
    "# Exploring an NWB File\n",
    "It can get cumbersome to manually dissect an NWB file with print statements. There are a few ways to view an NWB file graphically instead. A great way to do this in a Jupyter notebook is with **[NWBWidgets](https://github.com/NeurodataWithoutBorders/nwbwidgets)**. Here, you can use NWBWidgets to view a file from a location on your machine. If you don't want to download a file just to view it, you can still use NWBWidgets to view it remotely. Check out [Streaming an NWB File with remfile](./stream_nwb.ipynb) to learn how to do this. Another way to explore an NWB file, that doesn't require Jupyter, is with [HDFView](https://www.hdfgroup.org/downloads/hdfview/)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e54a7fde",
   "metadata": {},
   "source": [
    "### Environment Setup\n",
    "⚠️**Note: If running on a new environment, run this cell once and then restart the kernel**⚠️"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d36f2f39",
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings('ignore')\n",
    "\n",
    "try:\n",
    "    from databook_utils.dandi_utils import dandi_stream_open\n",
    "except:\n",
    "    !git clone https://github.com/AllenInstitute/openscope_databook.git\n",
    "    %cd openscope_databook\n",
    "    %pip install -e ."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "24009707",
   "metadata": {},
   "outputs": [],
   "source": [
    "from dandi import dandiapi\n",
    "from nwbwidgets import nwb2widget\n",
    "from pynwb import NWBHDF5IO"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "5c8b955c",
   "metadata": {},
   "source": [
    "### Downloading an NWB File\n",
    "To examine an NWB File locally, it must first be downloaded. `dandiset_id` and `dandi_filepath` may be changed to select a different file off of DANDI. If the file of interest already downloaded, you don't need to run the download cell again. When trying to download an embargoed file, refer to the code from the [Downloading an NWB File](./download_nwb.ipynb) notebook. In the cells below, the DANDI API is used to facilitate the download. The `get_dandiset()` methods retrieves a specific dataset within DANDI while the `get_asset_by_path()` method retrieves a specific file within that dataset. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "16c587a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "dandiset_id = \"000021\"\n",
    "dandi_filepath = \"sub-699733573/sub-699733573_ses-715093703.nwb\"\n",
    "download_loc = \".\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "83d7e5f7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "sub-699733573_ses-715093703.nwb\n",
      "./sub-699733573_ses-715093703.nwb\n"
     ]
    }
   ],
   "source": [
    "filename = dandi_filepath.split(\"/\")[-1]\n",
    "filepath = f\"{download_loc}/{filename}\"\n",
    "\n",
    "print(filename)\n",
    "print(filepath)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "1c5db129",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloaded file to ./sub-699733573_ses-715093703.nwb\n"
     ]
    }
   ],
   "source": [
    "client = dandiapi.DandiAPIClient()\n",
    "my_dandiset = client.get_dandiset(dandiset_id)\n",
    "file = my_dandiset.get_asset_by_path(dandi_filepath)\n",
    "\n",
    "# this may take awhile, especially if the file to download is large\n",
    "file.download(filepath)\n",
    "\n",
    "print(f\"Downloaded file to {filepath}\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3df13a24",
   "metadata": {},
   "source": [
    "### Displaying an NWB file\n",
    "When passing in the NWB object, the `nwb2widget` function will display the NWB file embedded in the notebook with each of the fields and subfields as a widget. NWB Files can vary a lot in their specific structure, so it can be important to familiarize yourself with the structure of the data you're working with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "0691fffc",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "root pynwb.file.NWBFile at 0x1632846282416\n",
      "Fields:\n",
      "  acquisition: {\n",
      "    raw_running_wheel_rotation <class 'pynwb.base.TimeSeries'>,\n",
      "    running_wheel_signal_voltage <class 'pynwb.base.TimeSeries'>,\n",
      "    running_wheel_supply_voltage <class 'pynwb.base.TimeSeries'>\n",
      "  }\n",
      "  devices: {\n",
      "    probeA <class 'abc.EcephysProbe'>,\n",
      "    probeB <class 'abc.EcephysProbe'>,\n",
      "    probeC <class 'abc.EcephysProbe'>,\n",
      "    probeD <class 'abc.EcephysProbe'>,\n",
      "    probeE <class 'abc.EcephysProbe'>,\n",
      "    probeF <class 'abc.EcephysProbe'>\n",
      "  }\n",
      "  electrode_groups: {\n",
      "    probeA <class 'abc.EcephysElectrodeGroup'>,\n",
      "    probeB <class 'abc.EcephysElectrodeGroup'>,\n",
      "    probeC <class 'abc.EcephysElectrodeGroup'>,\n",
      "    probeD <class 'abc.EcephysElectrodeGroup'>,\n",
      "    probeE <class 'abc.EcephysElectrodeGroup'>,\n",
      "    probeF <class 'abc.EcephysElectrodeGroup'>\n",
      "  }\n",
      "  electrodes: electrodes <class 'hdmf.common.table.DynamicTable'>\n",
      "  file_create_date: [datetime.datetime(2020, 5, 26, 0, 53, 26, 986608, tzinfo=tzoffset(None, -25200))]\n",
      "  identifier: 715093703\n",
      "  institution: Allen Institute for Brain Science\n",
      "  intervals: {\n",
      "    drifting_gratings_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    flashes_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    gabors_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    invalid_times <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    natural_movie_one_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    natural_movie_three_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    natural_scenes_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    spontaneous_presentations <class 'pynwb.epoch.TimeIntervals'>,\n",
      "    static_gratings_presentations <class 'pynwb.epoch.TimeIntervals'>\n",
      "  }\n",
      "  invalid_times: invalid_times <class 'pynwb.epoch.TimeIntervals'>\n",
      "  processing: {\n",
      "    eye_tracking_rig_metadata <class 'pynwb.base.ProcessingModule'>,\n",
      "    optotagging <class 'pynwb.base.ProcessingModule'>,\n",
      "    running <class 'pynwb.base.ProcessingModule'>,\n",
      "    stimulus <class 'pynwb.base.ProcessingModule'>\n",
      "  }\n",
      "  session_description: Data and metadata for an Ecephys session\n",
      "  session_id: 715093703\n",
      "  session_start_time: 2019-01-19 00:54:18-08:00\n",
      "  stimulus_notes: brain_observatory_1.1\n",
      "  subject: subject abc.EcephysSpecimen at 0x1632846275360\n",
      "Fields:\n",
      "  age: P118D\n",
      "  age_in_days: 118.0\n",
      "  genotype: Sst-IRES-Cre/wt;Ai32(RCL-ChR2(H134R)_EYFP)/wt\n",
      "  sex: M\n",
      "  species: Mus musculus\n",
      "  specimen_name: Sst-IRES-Cre;Ai32-386129\n",
      "  subject_id: 699733573\n",
      "\n",
      "  timestamps_reference_time: 2019-01-19 00:54:18-08:00\n",
      "  units: units <class 'pynwb.misc.Units'>\n",
      "\n"
     ]
    }
   ],
   "source": [
    "io = NWBHDF5IO(filepath, mode=\"r\", load_namespaces=True)\n",
    "nwb = io.read()\n",
    "\n",
    "print(nwb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "65addc38",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "f61bae7dded44a92beb04b78c1511af2",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "VBox(children=(HBox(children=(Label(value='session_description:', layout=Layout(max_height='40px', max_width='…"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nwb2widget(nwb)"
   ]
  }
 ],
 "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.10.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}