01-NWB_Basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "nearby-amino",
   "metadata": {},
   "source": [
    "# NWB File Examples\n",
    "\n",
    "This example introduces the NWB file format, creating an example datafile with dummy data.\n",
    "\n",
    "This example is adapted from: https://pynwb.readthedocs.io/en/stable/tutorials/general/file.html\n",
    "\n",
    "This example uses [pynwb](https://github.com/NeurodataWithoutBorders/pynwb), the Python tool for interacting with NWB files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "unlike-inside",
   "metadata": {},
   "outputs": [],
   "source": [
    "%config Completer.use_jedi = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "early-fraction",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from datetime import datetime\n",
    "from dateutil.tz import tzlocal\n",
    "\n",
    "import numpy as np\n",
    "\n",
    "# Import utilities from pynwb\n",
    "from pynwb import NWBFile, NWBHDF5IO, TimeSeries"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "separated-elevation",
   "metadata": {},
   "source": [
    "## Settings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "sonic-monkey",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set path for data files\n",
    "data_path = 'data'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "federal-antique",
   "metadata": {},
   "source": [
    "## Initialize an NWB File\n",
    "\n",
    "NWB files are a file specification for [HDF5 files](https://www.hdfgroup.org/solutions/hdf5/).\n",
    "\n",
    "HDF5 files are a file format defined for large and/or heterogenous data. \n",
    "\n",
    "To get started initializing a HDF5 file, we can `NWBFile` function. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "unlike-opportunity",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get local timezone\n",
    "timezone = tzlocal() \n",
    "\n",
    "# Set time zone information\n",
    "start_time = datetime(2021, 3, 20, tzinfo=tzlocal())\n",
    "create_date = datetime(2021, 3, 20, tzinfo=tzlocal())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "historic-prediction",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define some metadata for the file\n",
    "session_info = 'NWBFile test'\n",
    "session_id = 'NWB123'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "centered-knight",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize an NWB file\n",
    "nwbfile = NWBFile(session_description=session_info,\n",
    "                  identifier=session_id,\n",
    "                  session_start_time=start_time,\n",
    "                  file_create_date=create_date)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "through-truth",
   "metadata": {},
   "source": [
    "## Add Data to NWB File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "classical-contribution",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create some dummy test data\n",
    "data = np.arange(100, 200, 10)\n",
    "timestamps = np.arange(10.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "varied-vegetation",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create dummy time series object\n",
    "test_ts = TimeSeries(name='test_timeseries', data=data, unit='m', timestamps=timestamps)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "improved-procurement",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add the dummy time series as an acquisition element\n",
    "nwbfile.add_acquisition(test_ts)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "grateful-performer",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "test_timeseries pynwb.base.TimeSeries at 0x140632470617248\n",
       "Fields:\n",
       "  comments: no comments\n",
       "  conversion: 1.0\n",
       "  data: [100 110 120 130 140 150 160 170 180 190]\n",
       "  description: no description\n",
       "  interval: 1\n",
       "  resolution: -1.0\n",
       "  timestamps: [0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]\n",
       "  timestamps_unit: seconds\n",
       "  unit: m"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Check the acquisition element\n",
    "nwbfile.acquisition['test_timeseries']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "juvenile-basic",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the newly added acquisition\n",
    "test_acq = nwbfile.get_acquisition('test_timeseries')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "brilliant-differential",
   "metadata": {},
   "source": [
    "## Save out NWB File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "positive-concert",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save out an example NWB file\n",
    "with NWBHDF5IO('data/nwb_basics.nwb', 'w') as io:\n",
    "    io.write(nwbfile)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "present-adjustment",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[]\n"
     ]
    }
   ],
   "source": [
    "# Check for saved out NWB files\n",
    "nwb_files = [file for file in os.listdir('.') if file.split('.')[-1] == 'nwb']\n",
    "print(nwb_files)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "minor-holder",
   "metadata": {},
   "source": [
    "## Validating NWB Files\n",
    "\n",
    "NWB has utilities to validate NWB files.\n",
    "\n",
    "More information: https://pynwb.readthedocs.io/en/stable/validation.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "arabic-greensboro",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The file nwb_basics.nwb does not exist.\r\n"
     ]
    }
   ],
   "source": [
    "# Run command line tool to validate NWB file\n",
    "!python -m pynwb.validate nwb_basics.nwb"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "statistical-utility",
   "metadata": {},
   "source": [
    "## Read in NWB File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "suburban-matrix",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Read in an example NWB file\n",
    "io = NWBHDF5IO('data/nwb_basics.nwb', 'r')\n",
    "nwbfile_in = io.read()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "major-pulse",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "root pynwb.file.NWBFile at 0x140632506119984\n",
       "Fields:\n",
       "  acquisition: {\n",
       "    test_timeseries <class 'pynwb.base.TimeSeries'>\n",
       "  }\n",
       "  file_create_date: [datetime.datetime(2021, 3, 20, 0, 0, tzinfo=tzoffset(None, -14400))]\n",
       "  identifier: NWB123\n",
       "  session_description: NWBFile test\n",
       "  session_start_time: 2021-03-20 00:00:00-04:00\n",
       "  timestamps_reference_time: 2021-03-20 00:00:00-04:00"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Check the overview information of our example file\n",
    "nwbfile_in"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "primary-hardwood",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Extract an example data object\n",
    "test_ts_in = nwbfile_in.acquisition['test_timeseries']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "bridal-monster",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "test_timeseries pynwb.base.TimeSeries at 0x140632512249040\n",
      "Fields:\n",
      "  comments: no comments\n",
      "  conversion: 1.0\n",
      "  data: <HDF5 dataset \"data\": shape (10,), type \"<i8\">\n",
      "  description: no description\n",
      "  interval: 1\n",
      "  resolution: -1.0\n",
      "  timestamps: <HDF5 dataset \"timestamps\": shape (10,), type \"<f8\">\n",
      "  timestamps_unit: seconds\n",
      "  unit: m\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Check the example data object\n",
    "print(test_ts_in)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "flexible-testament",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Close the file reader\n",
    "io.close()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}