Notebook demonstrating the loading of NWB namespaces in different contexts

print_namespaces.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b928755e-a460-4ab9-9da7-adade1320956",
   "metadata": {},
   "source": [
    "# Demonstration of the loading of NWB namespaces in different contexts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2b5167ef-4d7a-4c04-982e-9150076fa78c",
   "metadata": {},
   "source": [
    "### Set up imports, data path, and utility function to print namespaces in a type map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "8cab59f7-b8ee-43fb-8c8d-28875c2ac3d8",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pynwb\n",
    "from pynwb.spec import NWBDatasetSpec, NWBGroupSpec, NWBNamespace\n",
    "\n",
    "from hdmf.spec import NamespaceCatalog\n",
    "from hdmf.build import TypeMap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "feb2c8ac-073b-4667-ad6b-9c269721612b",
   "metadata": {},
   "outputs": [],
   "source": [
    "path = r\"C:\\Users\\Ryan\\Documents\\NWB_Data\\AIBS_ecephys_dandiset21\\sub-699733573_ses-715093703_probe-810755797_ecephys.nwb\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "5fd228b6-0f9b-4ad2-9ff1-53c44bbc584a",
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_namespace_versions(type_map):\n",
    "    \"\"\"Print the namespace name and version of all namespaces in the given type map.\"\"\"\n",
    "    for ns_name in type_map.namespace_catalog.namespaces:\n",
    "        print(\"%s: %s\" % (ns_name, type_map.namespace_catalog.get_namespace(ns_name)[\"version\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a074b040-c9e2-49c0-892a-51c723ce5e09",
   "metadata": {},
   "source": [
    "### Namespaces in global scope\n",
    "PyNWB contains the latest versions of certain namespaces (pynwb, hdmf-common, and hdmf-experimental) that are available at the time of release of this version of pynwb.\n",
    "These namespaces are automatically loaded into all `NWBHDF5IO` objects subsequently created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "f17f641f-0086-4bed-862d-960390e89061",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces loaded in global scope:\n",
      "hdmf-common: 1.5.1\n",
      "hdmf-experimental: 0.2.0\n",
      "core: 2.5.0\n"
     ]
    }
   ],
   "source": [
    "print(\"Namespaces loaded in global scope:\")\n",
    "print_namespace_versions(pynwb.get_manager().type_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f52f930-18f5-48e1-8512-6274ef543b57",
   "metadata": {},
   "source": [
    "### Cached namespaces in NWB file\n",
    "NWB files contain cached namespaces which may have different versions that the namespaces with the same name loaded in the global scope."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e32cd7c5-0e67-4f18-aa58-b3cf89affc2c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces cached in the NWB file 'C:\\Users\\Ryan\\Documents\\NWB_Data\\AIBS_ecephys_dandiset21\\sub-699733573_ses-715093703_probe-810755797_ecephys.nwb':\n",
      "hdmf-common: 1.1.3\n",
      "core: 2.2.2\n",
      "ndx-aibs-ecephys: 0.2.0\n"
     ]
    }
   ],
   "source": [
    "catalog = NamespaceCatalog(NWBGroupSpec, NWBDatasetSpec, NWBNamespace)\n",
    "pynwb.NWBHDF5IO.load_namespaces(catalog, path)\n",
    "tm = TypeMap(catalog)\n",
    "print(\"Namespaces cached in the NWB file '%s':\" % path)\n",
    "print_namespace_versions(tm)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7bde66f-3a6a-48ed-a1f3-3bba51fc21c4",
   "metadata": {},
   "source": [
    "### Loading cached namespaces into IO object\n",
    "The global scope namespaces are loaded into the `NWBHDF5IO` object when it is created when `load_namespaces=True`, all namespaces cached within the NWB file that are not\n",
    "already in the namespaces within the `NWBHDF5IO` object (ignoring the version of the namespace) are then loaded into the `NWBHDF5IO` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "b5ed4211-b53b-4a23-860e-35f3d0a6fa9f",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\users\\ryan\\documents\\nwb\\hdmf\\src\\hdmf\\spec\\namespace.py:532: UserWarning: Ignoring cached namespace 'hdmf-common' version 1.1.3 because version 1.5.1 is already loaded.\n",
      "  warn(\"Ignoring cached namespace '%s' version %s because version %s is already loaded.\"\n",
      "c:\\users\\ryan\\documents\\nwb\\hdmf\\src\\hdmf\\spec\\namespace.py:532: UserWarning: Ignoring cached namespace 'core' version 2.2.2 because version 2.5.0 is already loaded.\n",
      "  warn(\"Ignoring cached namespace '%s' version %s because version %s is already loaded.\"\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces loaded in the build manager for the NWB file 'C:\\Users\\Ryan\\Documents\\NWB_Data\\AIBS_ecephys_dandiset21\\sub-699733573_ses-715093703_probe-810755797_ecephys.nwb':\n",
      "hdmf-common: 1.5.1\n",
      "hdmf-experimental: 0.2.0\n",
      "core: 2.5.0\n",
      "ndx-aibs-ecephys: 0.2.0\n"
     ]
    }
   ],
   "source": [
    "io = pynwb.NWBHDF5IO(path, \"r\", load_namespaces=True)\n",
    "print(\"Namespaces loaded in the build manager for the NWB file '%s':\" % path)\n",
    "print_namespace_versions(io.manager.type_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23e2c4dc-09b3-44a0-8fbd-cbe3e869043b",
   "metadata": {},
   "source": [
    "Loading cached namespaces into an NWBHDF5IO object does not affect the namespaces loaded in the global scope."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "67a5221c-d6c2-402d-b0cd-fc7755205091",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces loaded in global scope:\n",
      "hdmf-common: 1.5.1\n",
      "hdmf-experimental: 0.2.0\n",
      "core: 2.5.0\n"
     ]
    }
   ],
   "source": [
    "print(\"Namespaces loaded in global scope:\")\n",
    "print_namespace_versions(pynwb.get_manager().type_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea4ea5b2-e9a3-42c2-bea4-bd7089cf3fa0",
   "metadata": {},
   "source": [
    "### Loading namespaces into the global scope\n",
    "Load a namespace into the global scope, which will be loaded into all `NWBHDF5IO` objects subsequently created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "fab92bb9-bae4-460d-b63d-1ad0e8d4c479",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'ndx-ecog': {'core': ('Container',\n",
       "   'NWBContainer',\n",
       "   'NWBDataInterface',\n",
       "   'Subject')}}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "namespace_filepath = \"ndx-ecog.namespace.yaml\"\n",
    "pynwb.load_namespaces(namespace_filepath)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ee31acf-1af0-4b53-b1aa-4ac9b7a885d1",
   "metadata": {},
   "source": [
    "Note that the new namespace is present in the global scope."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "29f1a9ca-0915-4e85-a21e-b68623cf60ed",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces loaded in global scope:\n",
      "hdmf-common: 1.5.1\n",
      "hdmf-experimental: 0.2.0\n",
      "core: 2.5.0\n",
      "ndx-ecog: 0.1.1\n"
     ]
    }
   ],
   "source": [
    "print(\"Namespaces loaded in global scope:\")\n",
    "print_namespace_versions(pynwb.get_manager().type_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "142b0708-18a5-41eb-83c7-d02be036e1f9",
   "metadata": {},
   "source": [
    "Note that the new namespace is present in the namespaces for this `NWBHDF5IO` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "44b79cfa-d219-4c73-a144-76b175f98631",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Namespaces loaded in the build manager for the NWB file 'C:\\Users\\Ryan\\Documents\\NWB_Data\\AIBS_ecephys_dandiset21\\sub-699733573_ses-715093703_probe-810755797_ecephys.nwb':\n",
      "hdmf-common: 1.5.1\n",
      "hdmf-experimental: 0.2.0\n",
      "core: 2.5.0\n",
      "ndx-ecog: 0.1.1\n",
      "ndx-aibs-ecephys: 0.2.0\n"
     ]
    }
   ],
   "source": [
    "io = pynwb.NWBHDF5IO(path, \"r\", load_namespaces=True)\n",
    "print(\"Namespaces loaded in the build manager for the NWB file '%s':\" % path)\n",
    "print_namespace_versions(io.manager.type_map)"
   ]
  }
 ],
 "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}