From d45c343ed165a1eb4f6808a413f7f0785dee24fb Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 11 Sep 2024 10:40:56 -0400
Subject: [PATCH 01/27] update name of python black notebook

---
 .../templates/jupyter_lab/templates/blank/metadata.json       | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
index 8c60b17..9d03ea9 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
@@ -1,6 +1,6 @@
 {
-    "title": "Blank notebook",
-    "description": "Notebook only inserting UUIDs of added datasets",
+    "title": "Blank Notebook in Python",
+    "description": "Notebook only inserting UUIDs of added datasets.",
     "tags": [
     ], 
     "is_multi_dataset_template": true,

From dd5fe752fa11c78072c2c37b4163531b75dc1964 Mon Sep 17 00:00:00 2001
From: "Bruce W. Herr II" <bherr@indiana.edu>
Date: Wed, 11 Sep 2024 15:25:56 -0400
Subject: [PATCH 02/27] Added initial HRA API and HRA UI jupyterlab templates

---
 .../templates/hra_api_tutorial/README.md      |    0
 .../templates/hra_api_tutorial/metadata.json  |   19 +
 .../templates/hra_api_tutorial/render.py      |    6 +
 .../templates/hra_api_tutorial/template.txt   | 1283 +++++++++++++++++
 .../hra_ui_widgets_tutorial/README.md         |    0
 .../hra_ui_widgets_tutorial/metadata.json     |   19 +
 .../hra_ui_widgets_tutorial/render.py         |    6 +
 .../hra_ui_widgets_tutorial/template.txt      |  194 +++
 8 files changed, 1527 insertions(+)
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/README.md
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/render.py
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/README.md
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/render.py
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/README.md b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
new file mode 100644
index 0000000..1bae420
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
@@ -0,0 +1,19 @@
+{
+  "title": "Human Reference Atlas (HRA) API Tutorial",
+  "description": "This notebook shows users how to instantiate and use the HuBMAP HRA APIs.",
+  "tags": [
+    "hra",
+    "api"
+  ],
+  "is_multi_dataset_template": true,
+  "template_format": "jinja",
+  "examples": [
+    {
+      "title": "Working with the HRA API examples",
+      "description": "Example metadata and available files for four datasets.",
+      "datasets": ["41d665c06bbec9b4dcaec6d835acb0fb", "03a8a12acfa25c2414cfdada4a4b5fd6", "880474c3108655acfe6f8c30137f22ae", "3bc3ad124014a632d558255626bf38c9"]
+    }
+  ],
+  "is_hidden": false,
+  "last_modified_unix_timestamp": 1723749414
+}
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/render.py b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/render.py
new file mode 100644
index 0000000..7fec3bd
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/render.py
@@ -0,0 +1,6 @@
+from user_templates_api.templates.jupyter_lab.render import JupyterLabRender
+
+
+class JupyterLabExampleJinjaRender(JupyterLabRender):
+    def __init__(self):
+        pass
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
new file mode 100644
index 0000000..913a16b
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
@@ -0,0 +1,1283 @@
+[
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "40dd5488",
+    "metadata": {},
+    "source": [
+      "## HRA-API Documentation"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "47b355bd",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# linked datasets\n",
+      "uuids = {{ uuids | safe }}"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "e2d89b95",
+    "metadata": {},
+    "source": [
+      "# INDEX\n",
+      "1. [Installation](#install) \n",
+      "2. [Imports](#imports)\n",
+      "3. [Configuration](#config)\n",
+      "4. [Methods](#methods)\n",
+      "    1. [Database Status](#db_status) \n",
+      "    2. [Run a Sparql query](#sparql_get) \n",
+      "    3. [Run a Sparql query (POST)](#sparql_post) \n",
+      "    4. [Get aggregate results / statistics](#agg_results) \n",
+      "    5. [Given a SpatialEntity already placed relative to a reference SpatialEntity retrieve a new direct SpatialPlacement to the given SpatialEntity IRI](#spatial_entity)\n",
+      "    6. [Get all hubmap rui locations](#rui_loc)\n",
+      "    7. [Get number of ontology term occurrences for a search](#ontology_term) \n",
+      "    8. [Get number of cell type term occurrences for a search](#cell_term_occ) \n",
+      "    9.  [Get ontology term tree nodes](#ontology_nodes) \n",
+      "    10. [Get cell type tree nodes](#cell_nodes)\n",
+      "    11. [Get tissue provider names (for filtering)](#providers) \n",
+      "    12. [Get all reference organs](#ref_organs) \n",
+      "    13. [Get all nodes to form the 3D scene for an organ](#3d_scene) \n",
+      "    14. [Get all nodes to form the 3D scene of reference body, organs, and tissues](#nodes_3d) \n",
+      "    15. [Get technology names (for filtering)](#tech) \n",
+      "    16. [Get Tissue Block Results](#tissue_block) \n",
+      "    17. [Get all GTEx rui locations (if enabled)](#gtex_rui)\n",
+      "    18. [Token](#token_usage) \n",
+      "    19. [Generate a 3D corridor](#corridors)\n",
+      "    20. [Mesh-Based Collision Detection](#collision)\n",
+      "    21. [3D Cell Generation](#3d_cell)\n"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "43773186",
+    "metadata": {},
+    "source": [
+      "<a id='install'></a>\n",
+      "### Installation\n",
+      "\n",
+      "#### hra-api-client can be installed via `pip` from [PyPI](https://pypi.org/project/hra-api-client/#description).\n",
+      "***\n",
+      "> `pip install hra-api-client`\n",
+      "***\n",
+      "\n",
+      "You may also specify the version number:\n",
+      "***\n",
+      "> `pip install hra-api-client==0.10.0`\n",
+      "***"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "fd9a85aa",
+    "metadata": {},
+    "source": []
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "c3f1f6d5",
+    "metadata": {},
+    "source": [
+      "<a id='imports'></a>\n",
+      "### Imports \n",
+      "\n",
+      "We import the hra-api-client as follows:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "e5e21389",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import hra_api_client"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "0d6f2a35",
+    "metadata": {},
+    "source": [
+      "Although we can use hra-api-client for all our tasks, it is easier if we have individual imports as follows:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "d9f69dc1",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "from hra_api_client.api import v1_api as default_api\n",
+      "from hra_api_client.models.aggregate_count import AggregateCount\n",
+      "from hra_api_client.models.database_status import DatabaseStatus\n",
+      "from hra_api_client.models.error_message import ErrorMessage\n",
+      "from hra_api_client.models.flat_spatial_placement import FlatSpatialPlacement\n",
+      "from hra_api_client.models.get_spatial_placement_request import GetSpatialPlacementRequest\n",
+      "from hra_api_client.models.min_max import MinMax\n",
+      "from hra_api_client.models.ontology_tree import OntologyTree\n",
+      "from hra_api_client.models.sparql_query_request import SparqlQueryRequest\n",
+      "from hra_api_client.models.spatial_entity import SpatialEntity\n",
+      "from hra_api_client.models.spatial_scene_node import SpatialSceneNode\n",
+      "from hra_api_client.models.spatial_search import SpatialSearch\n",
+      "from hra_api_client.models.tissue_block import TissueBlock"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "7c4af109",
+    "metadata": {},
+    "source": [
+      "For the purposes of this documentation we need some other libraries imported here: "
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "3952039c",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import time\n",
+      "from pprint import pprint\n",
+      "from io import StringIO"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "a490f22e",
+    "metadata": {},
+    "source": [
+      "<a id='config'></a>\n",
+      "### Configuration\n",
+      "The HRA API can fetch data from \n",
+      "> HRA-API: https://apps.humanatlas.io/hra-api/v1 <br> \n",
+      "> Staging Server: https://apps.humanatlas.io/hra-api--staging/v1 <br>\n",
+      "> You could also use any other instance that you decide to host our code on\n",
+      "\n",
+      "You can get more information about our APIs [here](https://apps.humanatlas.io/hra-api/#/).\n",
+      "\n",
+      "You'll need to point the host in the configuration to one of the links: "
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "2e090732",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# may need to remove `v1`\n",
+      "configuration = hra_api_client.Configuration(\n",
+      "    host = \"https://apps.humanatlas.io/api\" \n",
+      ")"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "9faf09af",
+    "metadata": {},
+    "source": [
+      "<a id='api'></a>\n",
+      "### Creating the API Instance \n",
+      "We will need to create an instance of ApiClient from hra-api-client. The configuration we created above will be passed as a parameter for the constructor. <br> <br>\n",
+      "Using the instance of ApiClient we create an instance of DefaultApi from the default_api module we imported above. This instance represents the API interface and provides methods to interact with the API endpoints defined in the OpenAPI specification."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "3d7b7374",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "api_client = hra_api_client.ApiClient(configuration)\n",
+      "\n",
+      "api_instance = default_api.V1Api(api_client)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "ed96d236",
+    "metadata": {},
+    "source": [
+      "<a id='methods'></a>\n",
+      "### Methods\n",
+      "\n",
+      "hra-api-client provides multiple methods which we have described below. Each method is described in more detail below : "
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "4ba8a38f",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='db_status'></a>\n",
+      "#### Database Status \n",
+      "On first run the database might take some time to be ready, so we run it on loop and wait until it's ready.\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    token - (string) (optional)\n",
+      "</pre>\n",
+      "***\n",
+      "> You can still use the other methods without waiting for the database to be ready, but the initial requests might take a little longer."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "49d052a1",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# replace dict notation with dot notation\n",
+      "db_ready = False\n",
+      "result = None\n",
+      "while not db_ready:\n",
+      "    result = api_instance.db_status()\n",
+      "    print(result)\n",
+      "    if result.status == 'Ready':\n",
+      "        db_ready = True\n",
+      "    else:\n",
+      "        print('Database not ready yet! Retrying...', result)\n",
+      "        time.sleep(2)\n",
+      "print('Database ready!\\n', result)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "173d4800",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='sparql_get'></a>\n",
+      "#### Run a SPARQL query\n",
+      "<pre>\n",
+      "Accepted Parameters: \n",
+      "    token - (string) (optional)\n",
+      "    format - (string) (optional) (use only application/json in format, any other formats will result in errors.)\n",
+      "    query - (string) (required)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "4a739313",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.sparql(query='SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10', format='application/json')\n",
+      "    # help(api_instance.sparql)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "230194fd",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='sparql_post'></a>\n",
+      "#### Run a SPARQL query (POST) \n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    token - (string) (optional)\n",
+      "    format - (string) (optional) (use only application/json in format, any other formats will result in errors.)\n",
+      "    sparql_query_request - { \"query\": \"\" } (required)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "b3533391",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "request = {\"query\": \"SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10\"}\n",
+      "# use only application/json in format, any other formats will result in errors.\n",
+      "try:\n",
+      "    # help(api_instance.sparql_post)\n",
+      "    api_response = api_instance.sparql_post(sparql_query_request=request, format='application/json')\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->sparql_post: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "2e383f49",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='agg_results'></a>\n",
+      "#### Get aggregate results / statistics\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional) \n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "20a78738",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    api_response = api_instance.aggregate_results(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "bd967bab",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='spatial_entity'></a>\n",
+      "#### Given a SpatialEntity already placed relative to a reference SpatialEntity retrieve a new direct SpatialPlacement to the given SpatialEntity IRI &#x274C;\n",
+      "More Info : https://apps.humanatlas.io/hra-api/#/operations/get-spatial-placement\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    get_spatial_placement_request = {\n",
+      "        \"target_iri\": (string) (required)\n",
+      "        \"rui_location\": {\n",
+      "            A Spatial Entity defines a bounded cartesian space and the units it is measured in.\n",
+      "            It typically represents a real world thing, e.g., a human body, a human kidney, a tissue section,\n",
+      "            or an individual cell.\n",
+      "            \n",
+      "            \"@id\": string<uri> (required)\n",
+      "            \"@type\": (string) (required) (allowed value: SpatialEntity)\n",
+      "            \n",
+      "            \"entityId\": string<uri> (optional) (Identifier of the entity the spatial object represents)\n",
+      "            \"ccf_annotations\": array[string]<uri> (optional) (Annotations attached to the entity.)\n",
+      "            \"representation_of\": string<uri> (optional) (Identifier for the item the spatial object represents.)\n",
+      "            \"reference_organ\": string<uri> (optional) (Identifier for the organ the spatial object represents.)\n",
+      "            \n",
+      "            \"creator\": (string) (optional)\n",
+      "            \"creator_first_name\": (string) (optional)\n",
+      "            \"creator_last_name\": (string) (optional)\n",
+      "            \"creator_orcid\": (string) (optional)\n",
+      "            \"creation_date\": (string)<date>,\n",
+      "            \n",
+      "            \"x_dimension\": (number) (required),\n",
+      "            \"y_dimension\": (number) (required),\n",
+      "            \"z_dimension\": (number) (required),\n",
+      "            \"dimension_units\": (string) (required) (default: millimeters),\n",
+      "            \n",
+      "            \"label\": (string) (optional)\n",
+      "            \"comment\": (string) (optional)\n",
+      "            \"rui_rank\": (integer) (optional)\n",
+      "            \"sex\": (string) (optional)\n",
+      "            \"side\": (string) (optional) (Used for organs that come in pairs to distinguish between them, i.e. kidneys, etc)\n",
+      "            \"slice_count\": (integer) (optional)\n",
+      "            \"slice_thickness\": (number) (optional)\n",
+      "            \n",
+      "            \n",
+      "            \"placement\": {\n",
+      "                \"@id\": (string) (required),\n",
+      "                \"@type\": (string) (required) (allowed value: SpatialEntity),\n",
+      "                \"placement_date\": string<date>,\n",
+      "                \"x_translation\": (number) (required),\n",
+      "                \"y_translation\": (number) (required),\n",
+      "                \"z_translation\": (number) (required),\n",
+      "                \"translation_units\": (number) (required) (allowed value: millimeters),\n",
+      "                \"x_rotation\": (number) (required),\n",
+      "                \"y_rotation\": (number) (required),\n",
+      "                \"z_rotation\": (number) (required),\n",
+      "                \"rotation_units\": (string) (required) (allowed value: degree),\n",
+      "                \"x_scaling\": (number) (required),\n",
+      "                \"y_scaling\": (number) (required),\n",
+      "                \"z_scaling\": (number)  (optional),\n",
+      "                \"scaling_units\": (string) (required) (allowed value: degree),\n",
+      "                \"target\": (string) (required),\n",
+      "        }\n",
+      "            \n",
+      "        }\n",
+      "    }\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "4de04419",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "get_spatial_placement_request = {\n",
+      "    \"target_iri\": \"http://purl.org/ccf/latest/ccf.owl#VHFemale\",\n",
+      "    \"rui_location\": {\n",
+      "        \"@id\": \"http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869\",\n",
+      "        \"@type\": \"SpatialEntity\",\n",
+      "        \"creator\": \"Bruce Herr\",\n",
+      "        \"creator_first_name\": \"Bruce\",\n",
+      "        \"creator_last_name\": \"Herr\",\n",
+      "        \"creation_date\": \"2022-04-27\",\n",
+      "        \"ccf_annotations\": [\"http://purl.obolibrary.org/obo/UBERON_0002015\", \"http://purl.obolibrary.org/obo/UBERON_0000362\", \"http://purl.obolibrary.org/obo/UBERON_0004200\", \"http://purl.obolibrary.org/obo/UBERON_0001225\", \"http://purl.obolibrary.org/obo/UBERON_0001284\", \"http://purl.obolibrary.org/obo/UBERON_0002189\"],\n",
+      "        \"x_dimension\": 11,\n",
+      "        \"y_dimension\": 12,\n",
+      "        \"z_dimension\": 13,\n",
+      "        \"dimension_units\": \"millimeter\",\n",
+      "        \"placement\": {\n",
+      "            \"@id\": \"http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869_placement\",\n",
+      "            \"@type\": \"SpatialPlacement\",\n",
+      "            \"target\": \"http://purl.org/ccf/latest/ccf.owl#VHFLeftKidneyV1.1\",\n",
+      "            \"placement_date\": \"2022-04-27\",\n",
+      "            \"x_scaling\": 1,\n",
+      "            \"y_scaling\": 1,\n",
+      "            \"z_scaling\": 1,\n",
+      "            \"scaling_units\": \"ratio\",\n",
+      "            \"x_rotation\": -61,\n",
+      "            \"y_rotation\": 50,\n",
+      "            \"z_rotation\": -84,\n",
+      "            \"rotation_order\": \"XYZ\",\n",
+      "            \"rotation_units\": \"degree\",\n",
+      "            \"x_translation\": 20.149,\n",
+      "            \"y_translation\": 109.963,\n",
+      "            \"z_translation\": 38.79,\n",
+      "            \"translation_units\": \"millimeter\"\n",
+      "        }\n",
+      "    }\n",
+      "}\n",
+      "try:\n",
+      "    # Get spatial placement\n",
+      "    api_response = api_instance.get_spatial_placement(get_spatial_placement_request)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->get_spatial_placement: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "0a2c6460",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='rui_loc'></a>\n",
+      "#### Get all hubmap rui locations (if enabled)\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "f15c90b1",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.gtex_rui_locations(cache = True)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "6e6fc39a",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='ontology_term'></a>\n",
+      "#### Get number of ontology term occurrences for a search\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional) \n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "dabe4526",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    api_response = api_instance.ontology_term_occurences(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "ae1132cc",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='cell_term_occ'></a>\n",
+      "#### Get number of cell type term occurrences for a search\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional) \n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "db1e1ebd",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    api_response = api_instance.cell_type_term_occurences(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "0e8bd39d",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='ontology_nodes'></a>\n",
+      "#### Get ontology term tree nodes\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "7d5e5dd0",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.ontology_tree_model(cache=True)\n",
+      "    for item in api_response:\n",
+      "        pprint(item)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "7170f6f3",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='cell_nodes'></a>\n",
+      "#### Get cell type tree nodes\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "e27e8ac1",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.cell_type_tree_model(cache = False)\n",
+      "    for item in api_response:\n",
+      "        pprint(item)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "0965c71e",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='providers'></a>\n",
+      "#### Get tissue provider names (for filtering)\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "5ff1a305",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.provider_names(cache = True)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "1537015d",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='ref_organs'></a>\n",
+      "#### Get all reference organs\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "eeaf481b",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.reference_organs(cache = True)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "1b602f81",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='3d_scene'></a>\n",
+      "#### Get all nodes to form the 3D scene for an organ\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional)\n",
+      "    organ-iri - (string) (required)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "87710b53",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "organ_iri = \"http://purl.obolibrary.org/obo/UBERON_0004539\"\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    # Get aggregate results / statistics\n",
+      "    api_response = api_instance.reference_organ_scene(organ_iri=organ_iri, age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
+      ")\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "1afabd89",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='nodes_3d'></a>\n",
+      "#### Get all nodes to form the 3D scene of reference body, organs, and tissues\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "2160f41b",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    # Get aggregate results / statistics\n",
+      "    api_response = api_instance.scene(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
+      ")\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "8e0e94cb",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='tech'></a>\n",
+      "#### Get technology names (for filtering)\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional)\n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "3f79894f",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try:\n",
+      "    api_response = api_instance.technology_names(cache = False)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "80c2337f",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='tissue_block'></a>\n",
+      "#### Get Tissue Block Results\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    cache - (boolean)  (optional) (defaults to True)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) \n",
+      "    cell_type_terms - (string) (optional) \n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional)\n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "8f690344",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "cache = True\n",
+      "sex = \"female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
+      "        ),]\n",
+      "token = \"\"\n",
+      "\n",
+      "try:\n",
+      "    api_response = api_instance.tissue_blocks(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
+      ")\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "9cafd1d8",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='gtex_rui'></a>\n",
+      "#### Get all GTEx rui locations (if enabled)\n",
+      "<pre>\n",
+      "Accepted Parameters:\n",
+      "    cache - (boolean) (optional) \n",
+      "</pre>"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "3af8f4db",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "try: \n",
+      "    api_response = api_instance.gtex_rui_locations(cache = False)\n",
+      "    pprint(api_response)\n",
+      "except hra_api_client.ApiException as e:\n",
+      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "id": "1484a7ff",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='token_usage'></a>\n",
+      "#### Token Usage"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "a6157188",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "token = 'abbee123099245'\n",
+      "result = api_instance.db_status(token=token)\n",
+      "pprint(result)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "acbf417a",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='corridors'></a>\n",
+      "#### Generate a 3D corridor"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "4753f26a",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
+      "extraction_site = {\n",
+      "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
+      "    \"@type\": \"SpatialEntity\",\n",
+      "    \"creator\": \"demo demo\",\n",
+      "    \"creator_first_name\": \"demo\",\n",
+      "    \"creator_last_name\": \"demo\",\n",
+      "    \"creation_date\": \"2024-08-20\",\n",
+      "    \"ccf_annotations\": [\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
+      "    ],\n",
+      "    \"x_dimension\": 10,\n",
+      "    \"y_dimension\": 10,\n",
+      "    \"z_dimension\": 10,\n",
+      "    \"dimension_units\": \"millimeter\",\n",
+      "    \"placement\": {\n",
+      "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
+      "        \"@type\": \"SpatialPlacement\",\n",
+      "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
+      "        \"placement_date\": \"2024-08-20\",\n",
+      "        \"x_scaling\": 1,\n",
+      "        \"y_scaling\": 1,\n",
+      "        \"z_scaling\": 1,\n",
+      "        \"scaling_units\": \"ratio\",\n",
+      "        \"x_rotation\": 0,\n",
+      "        \"y_rotation\": 0,\n",
+      "        \"z_rotation\": 0,\n",
+      "        \"rotation_order\": \"XYZ\",\n",
+      "        \"rotation_units\": \"degree\",\n",
+      "        \"x_translation\": 72.366,\n",
+      "        \"y_translation\": 79.067,\n",
+      "        \"z_translation\": 34.77,\n",
+      "        \"translation_units\": \"millimeter\"\n",
+      "    }\n",
+      "}\n",
+      "\n",
+      "# POST the extraction site\n",
+      "model = api_instance.corridor(extraction_site)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "09075bd6",
+    "metadata": {},
+    "source": [
+      "Save corridor to file:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "74fcb536",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "corridor_file_name = \"corridor.glb\"\n",
+      "\n",
+      "# \"ab\" mode to append\n",
+      "with open(corridor_file_name, \"wb\") as binary_file:\n",
+      "\n",
+      "    # Write bytes to file\n",
+      "    binary_file.write(model)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "a7c4fad1",
+    "metadata": {},
+    "source": [
+      "##### Display with `pyvista`"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "fdb827fe",
+    "metadata": {},
+    "source": [
+      "Make sure to run:\n",
+      "`pip install \"pyvista[jupyter]\"`"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "073db386",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import pyvista\n",
+      "from pyvista import examples\n",
+      "from itkwidgets import view\n",
+      "\n",
+      "pl = pyvista.Plotter()\n",
+      "pl.import_gltf(corridor_file_name)\n",
+      "pl.camera.zoom(1.0)\n",
+      "pl.show()"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "6ceb5a43",
+    "metadata": {},
+    "source": [
+      "##### Display with `k3d`/`vtk`"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "3d232ee1",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import k3d\n",
+      "import vtk\n",
+      "import ipywidgets as widgets\n",
+      "\n",
+      "reader = vtk.vtkGLTFReader()\n",
+      "reader.SetFileName(corridor_file_name)\n",
+      "reader.Update()\n",
+      "\n",
+      "plot = k3d.plot()\n",
+      "mb = reader.GetOutput()\n",
+      "\n",
+      "iterator = mb.NewIterator()\n",
+      "\n",
+      "vtk_polyobjects = []\n",
+      "while not iterator.IsDoneWithTraversal():\n",
+      "    item = iterator.GetCurrentDataObject()\n",
+      "    vtk_polyobjects.append(item)\n",
+      "    iterator.GoToNextItem()\n",
+      "\n",
+      "\n",
+      "for obj in vtk_polyobjects:\n",
+      "    plot += k3d.vtk_poly_data(obj, color=0x222222)\n",
+      "plot.display()\n",
+      "\n",
+      "debug_info = widgets.HTML()"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "ebd70311",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='collision'></a>\n",
+      "#### Mesh-Based Collision Detection"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "8fe568bf",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
+      "extraction_site = {\n",
+      "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
+      "    \"@type\": \"SpatialEntity\",\n",
+      "    \"creator\": \"demo demo\",\n",
+      "    \"creator_first_name\": \"demo\",\n",
+      "    \"creator_last_name\": \"demo\",\n",
+      "    \"creation_date\": \"2024-08-20\",\n",
+      "    \"ccf_annotations\": [\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
+      "    ],\n",
+      "    \"x_dimension\": 10,\n",
+      "    \"y_dimension\": 10,\n",
+      "    \"z_dimension\": 10,\n",
+      "    \"dimension_units\": \"millimeter\",\n",
+      "    \"placement\": {\n",
+      "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
+      "        \"@type\": \"SpatialPlacement\",\n",
+      "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
+      "        \"placement_date\": \"2024-08-20\",\n",
+      "        \"x_scaling\": 1,\n",
+      "        \"y_scaling\": 1,\n",
+      "        \"z_scaling\": 1,\n",
+      "        \"scaling_units\": \"ratio\",\n",
+      "        \"x_rotation\": 0,\n",
+      "        \"y_rotation\": 0,\n",
+      "        \"z_rotation\": 0,\n",
+      "        \"rotation_order\": \"XYZ\",\n",
+      "        \"rotation_units\": \"degree\",\n",
+      "        \"x_translation\": 72.366,\n",
+      "        \"y_translation\": 79.067,\n",
+      "        \"z_translation\": 34.77,\n",
+      "        \"translation_units\": \"millimeter\"\n",
+      "    }\n",
+      "}\n",
+      "\n",
+      "# Get mesh-based collisions\n",
+      "pprint(api_instance.collisions(extraction_site))"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "id": "13760167",
+    "metadata": {},
+    "source": [
+      "***\n",
+      "<a id='3d_cell'></a>\n",
+      "#### 3D Cell Generation"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "id": "9773778c",
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# import pandas to convert API response into a DataFrame for easier downstream handling\n",
+      "import pandas as pd\n",
+      "\n",
+      "# Create your request parameters\n",
+      "params = {\n",
+      "    \"file\": \"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\",\n",
+      "    \"file_subpath\": \"VH_F_renal_pyramid_L_a\",\n",
+      "    \"num_nodes\": 10,\n",
+      "    \"node_distribution\": {\n",
+      "        \"KEY1\": 0.1,\n",
+      "        \"KEY2\": 0.3\n",
+      "    }\n",
+      "}\n",
+      "\n",
+      "# The result is a list of objects with x, y, z positions and types, accoording to the distribution and number of nodes specified in the parameters\n",
+      "response = api_instance.mesh3d_cell_population(params)\n",
+      "\n",
+      "# Convert to string\n",
+      "as_string = str(response, 'utf-8')\n",
+      "\n",
+      "# Convert the string to a DataFrame\n",
+      "df = pd.read_csv(StringIO(as_string))\n",
+      "\n",
+      "# Display the DataFrame\n",
+      "print(df)"
+    ]
+  }
+]
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/README.md b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
new file mode 100644
index 0000000..eb7c5c1
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
@@ -0,0 +1,19 @@
+{
+  "title": "Human Reference Atlas (HRA) UI Jupyter Widgets Tutorial",
+  "description": "This notebook shows users how to instantiate and use the HuBMAP HRA UI Jupyter Widgets.",
+  "tags": [
+    "hra",
+    "visualization"
+  ],
+  "is_multi_dataset_template": true,
+  "template_format": "jinja",
+  "examples": [
+    {
+      "title": "Working with the HRA UI Jupyter Widgets examples",
+      "description": "Example metadata and available files for four datasets.",
+      "datasets": ["41d665c06bbec9b4dcaec6d835acb0fb", "03a8a12acfa25c2414cfdada4a4b5fd6", "880474c3108655acfe6f8c30137f22ae", "3bc3ad124014a632d558255626bf38c9"]
+    }
+  ],
+  "is_hidden": false,
+  "last_modified_unix_timestamp": 1723749414
+}
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/render.py b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/render.py
new file mode 100644
index 0000000..7fec3bd
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/render.py
@@ -0,0 +1,6 @@
+from user_templates_api.templates.jupyter_lab.render import JupyterLabRender
+
+
+class JupyterLabExampleJinjaRender(JupyterLabRender):
+    def __init__(self):
+        pass
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
new file mode 100644
index 0000000..0f52a6d
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
@@ -0,0 +1,194 @@
+[
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Usage\n",
+      "This notebook shows how to use the different widgets provided by the hra_jupyter_widgets package."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# linked datasets\n",
+      "uuids = {{ uuids | safe }}"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Install package"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "%pip install hra_jupyter_widgets"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Import widgets"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import ipywidgets as widgets\n",
+      "from hra_jupyter_widgets import (\n",
+      "    EuiOrganInformation,\n",
+      "    FtuExplorer,\n",
+      "    FtuExplorerSmall,\n",
+      "    MedicalIllustration,\n",
+      "    ModelViewer\n",
+      ")"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Configure organ and illustration"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Kidney uberon id\n",
+      "organ = \"http://purl.obolibrary.org/obo/UBERON_0002113\"\n",
+      "illustration = \"https://purl.humanatlas.io/2d-ftu/kidney-renal-corpuscle\""
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Create and use a widget"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "medical_illustration = MedicalIllustration(selected_illustration=illustration)\n",
+      "display(medical_illustration)"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Create an output widget\n",
+      "output = widgets.Output()\n",
+      "\n",
+      "\n",
+      "# Create an event listener that prints to the output widget\n",
+      "# It takes a single argument - the event data\n",
+      "def cell_click(cell):\n",
+      "    with output:\n",
+      "        print(f\"Cell clicked: '{cell['label']}'\")\n",
+      "\n",
+      "\n",
+      "# Register the listener\n",
+      "medical_illustration.on_cell_click(cell_click)\n",
+      "# Listeners can be removed by calling on_cell_click with remove=True, i.e.\n",
+      "# medical_illustration.on_cell_click(cell_click, remove=True)\n",
+      "\n",
+      "display(output)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Widget showcase"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "#### Eui Organ Information"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "organ_info = EuiOrganInformation(organ_iri=organ)\n",
+      "display(organ_info)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "#### FTU explorer (small version)"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "ftu_explorer_small = FtuExplorerSmall(selected_illustration=illustration)\n",
+      "display(ftu_explorer_small)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "#### FTU explorer (full version)"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "ftu_explorer = FtuExplorer()\n",
+      "display(ftu_explorer)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "#### 3D Model Viewer"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "model_viewer = ModelViewer(url=\"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\")\n",
+      "display(model_viewer)"
+    ]
+  }
+]

From be0ae7308d62106176020c09a0bdd133de34faf2 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 11 Sep 2024 16:35:26 -0400
Subject: [PATCH 03/27] add start for R template

---
 .../jupyter_lab/templates/blank_r/README.md      |  0
 .../jupyter_lab/templates/blank_r/metadata.json  | 16 ++++++++++++++++
 .../jupyter_lab/templates/blank_r/render.py      |  6 ++++++
 .../jupyter_lab/templates/blank_r/template.txt   | 12 ++++++++++++
 4 files changed, 34 insertions(+)
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/blank_r/README.md
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/blank_r/render.py
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/README.md b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
new file mode 100644
index 0000000..c1a6657
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -0,0 +1,16 @@
+{
+  "title": "Blank Notebook in R",
+  "description": "Notebook only inserting UUIDs of added datasets",
+  "tags": [
+  ], 
+  "is_multi_dataset_template": true,
+  "template_format": "jinja",
+  "examples": [
+    {
+      "title": "Workspace Tutorial datasets",
+      "description": "Create a blank notebook with a CODEX and Slideseq dataset linked.",
+      "datasets": ["69c70762689b20308bb049ac49653342", "a1d17fdd270a69c813b872a927dfa5f3"]
+    }
+  ],
+  "is_hidden": false
+}
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/render.py b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/render.py
new file mode 100644
index 0000000..7fec3bd
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/render.py
@@ -0,0 +1,6 @@
+from user_templates_api.templates.jupyter_lab.render import JupyterLabRender
+
+
+class JupyterLabExampleJinjaRender(JupyterLabRender):
+    def __init__(self):
+        pass
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt
new file mode 100644
index 0000000..682b107
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt
@@ -0,0 +1,12 @@
+[
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# linked datasets\n",
+    "uuids <- c({{ uuids|join(', ') }})"
+   ]
+  }
+]
\ No newline at end of file

From 17fde45734dca969be7340a43df2779ccfc891af Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Thu, 12 Sep 2024 08:23:17 -0400
Subject: [PATCH 04/27] fix uuid insertion for R template (django instead of
 jinja)

---
 .../templates/jupyter_lab/templates/blank_r/template.txt        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt
index 682b107..c7f33a2 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/template.txt
@@ -6,7 +6,7 @@
    "outputs": [],
    "source": [
     "# linked datasets\n",
-    "uuids <- c({{ uuids|join(', ') }})"
+    "uuids <- c('{{ uuids|join:'\', \'' }}')"
    ]
   }
 ]
\ No newline at end of file

From dbe2dc062bbc266652d813695f8bcc107467e1ee Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Thu, 12 Sep 2024 08:27:07 -0400
Subject: [PATCH 05/27] update R template name to indicate environment

---
 .../templates/jupyter_lab/templates/blank_r/metadata.json       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
index c1a6657..ef8b8dc 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -1,5 +1,5 @@
 {
-  "title": "Blank Notebook in R",
+  "title": "Blank Notebook in R (Jupyter Lab: Python + R)",
   "description": "Notebook only inserting UUIDs of added datasets",
   "tags": [
   ], 

From 939cc5c00a00dbf631ed6f6ac5a3386dc61f1b84 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Thu, 12 Sep 2024 10:25:21 -0400
Subject: [PATCH 06/27] add job types to R template

---
 .../templates/jupyter_lab/templates/blank_r/metadata.json      | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
index ef8b8dc..b843b50 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -1,10 +1,11 @@
 {
-  "title": "Blank Notebook in R (Jupyter Lab: Python + R)",
+  "title": "Blank Notebook in R",
   "description": "Notebook only inserting UUIDs of added datasets",
   "tags": [
   ], 
   "is_multi_dataset_template": true,
   "template_format": "jinja",
+  "job_types": ["jupyter_lab_r"],
   "examples": [
     {
       "title": "Workspace Tutorial datasets",

From b02c38f35b33da5acdabc4282a021192d62683e6 Mon Sep 17 00:00:00 2001
From: "Thomas C. Smits" <90332819+thomcsmits@users.noreply.github.com>
Date: Thu, 12 Sep 2024 14:09:21 -0400
Subject: [PATCH 07/27] Apply suggestions from code review

Co-authored-by: John Conroy <62477388+john-conroy@users.noreply.github.com>
---
 .../templates/jupyter_lab/templates/blank/metadata.json         | 2 +-
 .../templates/jupyter_lab/templates/blank_r/metadata.json       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
index 9d03ea9..913ee77 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank/metadata.json
@@ -1,5 +1,5 @@
 {
-    "title": "Blank Notebook in Python",
+    "title": "Blank Notebook",
     "description": "Notebook only inserting UUIDs of added datasets.",
     "tags": [
     ], 
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
index b843b50..416574b 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -1,5 +1,5 @@
 {
-  "title": "Blank Notebook in R",
+  "title": "Blank Notebook",
   "description": "Notebook only inserting UUIDs of added datasets",
   "tags": [
   ], 

From bbc01c61476f3e7a0fbf8269580988d54b20fd38 Mon Sep 17 00:00:00 2001
From: John Conroy <john-conroy@users.noreply.github.com>
Date: Mon, 16 Sep 2024 15:32:10 -0400
Subject: [PATCH 08/27] Add R tag to blank notebook

---
 .../templates/jupyter_lab/templates/blank_r/metadata.json      | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
index 416574b..4574f25 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -1,8 +1,7 @@
 {
   "title": "Blank Notebook",
   "description": "Notebook only inserting UUIDs of added datasets",
-  "tags": [
-  ], 
+  "tags": ["R"], 
   "is_multi_dataset_template": true,
   "template_format": "jinja",
   "job_types": ["jupyter_lab_r"],

From fc37d34b83141eb7802112f676a3f496bdc104e9 Mon Sep 17 00:00:00 2001
From: "Bruce W. Herr II" <bherr@indiana.edu>
Date: Mon, 16 Sep 2024 21:43:51 -0400
Subject: [PATCH 09/27] Updated templates to address feedback

---
 .../templates/hra_api_tutorial/template.txt   | 1885 ++++++-----------
 .../hra_ui_widgets_tutorial/template.txt      |  417 ++--
 2 files changed, 825 insertions(+), 1477 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
index 913a16b..48a89da 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
@@ -1,1283 +1,602 @@
-[
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "40dd5488",
-    "metadata": {},
-    "source": [
-      "## HRA-API Documentation"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "47b355bd",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# linked datasets\n",
-      "uuids = {{ uuids | safe }}"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "e2d89b95",
-    "metadata": {},
-    "source": [
-      "# INDEX\n",
-      "1. [Installation](#install) \n",
-      "2. [Imports](#imports)\n",
-      "3. [Configuration](#config)\n",
-      "4. [Methods](#methods)\n",
-      "    1. [Database Status](#db_status) \n",
-      "    2. [Run a Sparql query](#sparql_get) \n",
-      "    3. [Run a Sparql query (POST)](#sparql_post) \n",
-      "    4. [Get aggregate results / statistics](#agg_results) \n",
-      "    5. [Given a SpatialEntity already placed relative to a reference SpatialEntity retrieve a new direct SpatialPlacement to the given SpatialEntity IRI](#spatial_entity)\n",
-      "    6. [Get all hubmap rui locations](#rui_loc)\n",
-      "    7. [Get number of ontology term occurrences for a search](#ontology_term) \n",
-      "    8. [Get number of cell type term occurrences for a search](#cell_term_occ) \n",
-      "    9.  [Get ontology term tree nodes](#ontology_nodes) \n",
-      "    10. [Get cell type tree nodes](#cell_nodes)\n",
-      "    11. [Get tissue provider names (for filtering)](#providers) \n",
-      "    12. [Get all reference organs](#ref_organs) \n",
-      "    13. [Get all nodes to form the 3D scene for an organ](#3d_scene) \n",
-      "    14. [Get all nodes to form the 3D scene of reference body, organs, and tissues](#nodes_3d) \n",
-      "    15. [Get technology names (for filtering)](#tech) \n",
-      "    16. [Get Tissue Block Results](#tissue_block) \n",
-      "    17. [Get all GTEx rui locations (if enabled)](#gtex_rui)\n",
-      "    18. [Token](#token_usage) \n",
-      "    19. [Generate a 3D corridor](#corridors)\n",
-      "    20. [Mesh-Based Collision Detection](#collision)\n",
-      "    21. [3D Cell Generation](#3d_cell)\n"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "43773186",
-    "metadata": {},
-    "source": [
-      "<a id='install'></a>\n",
-      "### Installation\n",
-      "\n",
-      "#### hra-api-client can be installed via `pip` from [PyPI](https://pypi.org/project/hra-api-client/#description).\n",
-      "***\n",
-      "> `pip install hra-api-client`\n",
-      "***\n",
-      "\n",
-      "You may also specify the version number:\n",
-      "***\n",
-      "> `pip install hra-api-client==0.10.0`\n",
-      "***"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "fd9a85aa",
-    "metadata": {},
-    "source": []
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "c3f1f6d5",
-    "metadata": {},
-    "source": [
-      "<a id='imports'></a>\n",
-      "### Imports \n",
-      "\n",
-      "We import the hra-api-client as follows:"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "e5e21389",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "import hra_api_client"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "0d6f2a35",
-    "metadata": {},
-    "source": [
-      "Although we can use hra-api-client for all our tasks, it is easier if we have individual imports as follows:"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "d9f69dc1",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "from hra_api_client.api import v1_api as default_api\n",
-      "from hra_api_client.models.aggregate_count import AggregateCount\n",
-      "from hra_api_client.models.database_status import DatabaseStatus\n",
-      "from hra_api_client.models.error_message import ErrorMessage\n",
-      "from hra_api_client.models.flat_spatial_placement import FlatSpatialPlacement\n",
-      "from hra_api_client.models.get_spatial_placement_request import GetSpatialPlacementRequest\n",
-      "from hra_api_client.models.min_max import MinMax\n",
-      "from hra_api_client.models.ontology_tree import OntologyTree\n",
-      "from hra_api_client.models.sparql_query_request import SparqlQueryRequest\n",
-      "from hra_api_client.models.spatial_entity import SpatialEntity\n",
-      "from hra_api_client.models.spatial_scene_node import SpatialSceneNode\n",
-      "from hra_api_client.models.spatial_search import SpatialSearch\n",
-      "from hra_api_client.models.tissue_block import TissueBlock"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "7c4af109",
-    "metadata": {},
-    "source": [
-      "For the purposes of this documentation we need some other libraries imported here: "
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "3952039c",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "import time\n",
-      "from pprint import pprint\n",
-      "from io import StringIO"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "a490f22e",
-    "metadata": {},
-    "source": [
-      "<a id='config'></a>\n",
-      "### Configuration\n",
-      "The HRA API can fetch data from \n",
-      "> HRA-API: https://apps.humanatlas.io/hra-api/v1 <br> \n",
-      "> Staging Server: https://apps.humanatlas.io/hra-api--staging/v1 <br>\n",
-      "> You could also use any other instance that you decide to host our code on\n",
-      "\n",
-      "You can get more information about our APIs [here](https://apps.humanatlas.io/hra-api/#/).\n",
-      "\n",
-      "You'll need to point the host in the configuration to one of the links: "
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "2e090732",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# may need to remove `v1`\n",
-      "configuration = hra_api_client.Configuration(\n",
-      "    host = \"https://apps.humanatlas.io/api\" \n",
-      ")"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "9faf09af",
-    "metadata": {},
-    "source": [
-      "<a id='api'></a>\n",
-      "### Creating the API Instance \n",
-      "We will need to create an instance of ApiClient from hra-api-client. The configuration we created above will be passed as a parameter for the constructor. <br> <br>\n",
-      "Using the instance of ApiClient we create an instance of DefaultApi from the default_api module we imported above. This instance represents the API interface and provides methods to interact with the API endpoints defined in the OpenAPI specification."
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "3d7b7374",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "api_client = hra_api_client.ApiClient(configuration)\n",
-      "\n",
-      "api_instance = default_api.V1Api(api_client)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "ed96d236",
-    "metadata": {},
-    "source": [
-      "<a id='methods'></a>\n",
-      "### Methods\n",
-      "\n",
-      "hra-api-client provides multiple methods which we have described below. Each method is described in more detail below : "
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "4ba8a38f",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='db_status'></a>\n",
-      "#### Database Status \n",
-      "On first run the database might take some time to be ready, so we run it on loop and wait until it's ready.\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    token - (string) (optional)\n",
-      "</pre>\n",
-      "***\n",
-      "> You can still use the other methods without waiting for the database to be ready, but the initial requests might take a little longer."
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "49d052a1",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# replace dict notation with dot notation\n",
-      "db_ready = False\n",
-      "result = None\n",
-      "while not db_ready:\n",
-      "    result = api_instance.db_status()\n",
-      "    print(result)\n",
-      "    if result.status == 'Ready':\n",
-      "        db_ready = True\n",
-      "    else:\n",
-      "        print('Database not ready yet! Retrying...', result)\n",
-      "        time.sleep(2)\n",
-      "print('Database ready!\\n', result)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "173d4800",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='sparql_get'></a>\n",
-      "#### Run a SPARQL query\n",
-      "<pre>\n",
-      "Accepted Parameters: \n",
-      "    token - (string) (optional)\n",
-      "    format - (string) (optional) (use only application/json in format, any other formats will result in errors.)\n",
-      "    query - (string) (required)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "4a739313",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.sparql(query='SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10', format='application/json')\n",
-      "    # help(api_instance.sparql)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "230194fd",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='sparql_post'></a>\n",
-      "#### Run a SPARQL query (POST) \n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    token - (string) (optional)\n",
-      "    format - (string) (optional) (use only application/json in format, any other formats will result in errors.)\n",
-      "    sparql_query_request - { \"query\": \"\" } (required)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "b3533391",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "request = {\"query\": \"SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10\"}\n",
-      "# use only application/json in format, any other formats will result in errors.\n",
-      "try:\n",
-      "    # help(api_instance.sparql_post)\n",
-      "    api_response = api_instance.sparql_post(sparql_query_request=request, format='application/json')\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->sparql_post: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "2e383f49",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='agg_results'></a>\n",
-      "#### Get aggregate results / statistics\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional) \n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "20a78738",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    api_response = api_instance.aggregate_results(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "bd967bab",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='spatial_entity'></a>\n",
-      "#### Given a SpatialEntity already placed relative to a reference SpatialEntity retrieve a new direct SpatialPlacement to the given SpatialEntity IRI &#x274C;\n",
-      "More Info : https://apps.humanatlas.io/hra-api/#/operations/get-spatial-placement\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    get_spatial_placement_request = {\n",
-      "        \"target_iri\": (string) (required)\n",
-      "        \"rui_location\": {\n",
-      "            A Spatial Entity defines a bounded cartesian space and the units it is measured in.\n",
-      "            It typically represents a real world thing, e.g., a human body, a human kidney, a tissue section,\n",
-      "            or an individual cell.\n",
-      "            \n",
-      "            \"@id\": string<uri> (required)\n",
-      "            \"@type\": (string) (required) (allowed value: SpatialEntity)\n",
-      "            \n",
-      "            \"entityId\": string<uri> (optional) (Identifier of the entity the spatial object represents)\n",
-      "            \"ccf_annotations\": array[string]<uri> (optional) (Annotations attached to the entity.)\n",
-      "            \"representation_of\": string<uri> (optional) (Identifier for the item the spatial object represents.)\n",
-      "            \"reference_organ\": string<uri> (optional) (Identifier for the organ the spatial object represents.)\n",
-      "            \n",
-      "            \"creator\": (string) (optional)\n",
-      "            \"creator_first_name\": (string) (optional)\n",
-      "            \"creator_last_name\": (string) (optional)\n",
-      "            \"creator_orcid\": (string) (optional)\n",
-      "            \"creation_date\": (string)<date>,\n",
-      "            \n",
-      "            \"x_dimension\": (number) (required),\n",
-      "            \"y_dimension\": (number) (required),\n",
-      "            \"z_dimension\": (number) (required),\n",
-      "            \"dimension_units\": (string) (required) (default: millimeters),\n",
-      "            \n",
-      "            \"label\": (string) (optional)\n",
-      "            \"comment\": (string) (optional)\n",
-      "            \"rui_rank\": (integer) (optional)\n",
-      "            \"sex\": (string) (optional)\n",
-      "            \"side\": (string) (optional) (Used for organs that come in pairs to distinguish between them, i.e. kidneys, etc)\n",
-      "            \"slice_count\": (integer) (optional)\n",
-      "            \"slice_thickness\": (number) (optional)\n",
-      "            \n",
-      "            \n",
-      "            \"placement\": {\n",
-      "                \"@id\": (string) (required),\n",
-      "                \"@type\": (string) (required) (allowed value: SpatialEntity),\n",
-      "                \"placement_date\": string<date>,\n",
-      "                \"x_translation\": (number) (required),\n",
-      "                \"y_translation\": (number) (required),\n",
-      "                \"z_translation\": (number) (required),\n",
-      "                \"translation_units\": (number) (required) (allowed value: millimeters),\n",
-      "                \"x_rotation\": (number) (required),\n",
-      "                \"y_rotation\": (number) (required),\n",
-      "                \"z_rotation\": (number) (required),\n",
-      "                \"rotation_units\": (string) (required) (allowed value: degree),\n",
-      "                \"x_scaling\": (number) (required),\n",
-      "                \"y_scaling\": (number) (required),\n",
-      "                \"z_scaling\": (number)  (optional),\n",
-      "                \"scaling_units\": (string) (required) (allowed value: degree),\n",
-      "                \"target\": (string) (required),\n",
-      "        }\n",
-      "            \n",
-      "        }\n",
-      "    }\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "4de04419",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "get_spatial_placement_request = {\n",
-      "    \"target_iri\": \"http://purl.org/ccf/latest/ccf.owl#VHFemale\",\n",
-      "    \"rui_location\": {\n",
-      "        \"@id\": \"http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869\",\n",
-      "        \"@type\": \"SpatialEntity\",\n",
-      "        \"creator\": \"Bruce Herr\",\n",
-      "        \"creator_first_name\": \"Bruce\",\n",
-      "        \"creator_last_name\": \"Herr\",\n",
-      "        \"creation_date\": \"2022-04-27\",\n",
-      "        \"ccf_annotations\": [\"http://purl.obolibrary.org/obo/UBERON_0002015\", \"http://purl.obolibrary.org/obo/UBERON_0000362\", \"http://purl.obolibrary.org/obo/UBERON_0004200\", \"http://purl.obolibrary.org/obo/UBERON_0001225\", \"http://purl.obolibrary.org/obo/UBERON_0001284\", \"http://purl.obolibrary.org/obo/UBERON_0002189\"],\n",
-      "        \"x_dimension\": 11,\n",
-      "        \"y_dimension\": 12,\n",
-      "        \"z_dimension\": 13,\n",
-      "        \"dimension_units\": \"millimeter\",\n",
-      "        \"placement\": {\n",
-      "            \"@id\": \"http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869_placement\",\n",
-      "            \"@type\": \"SpatialPlacement\",\n",
-      "            \"target\": \"http://purl.org/ccf/latest/ccf.owl#VHFLeftKidneyV1.1\",\n",
-      "            \"placement_date\": \"2022-04-27\",\n",
-      "            \"x_scaling\": 1,\n",
-      "            \"y_scaling\": 1,\n",
-      "            \"z_scaling\": 1,\n",
-      "            \"scaling_units\": \"ratio\",\n",
-      "            \"x_rotation\": -61,\n",
-      "            \"y_rotation\": 50,\n",
-      "            \"z_rotation\": -84,\n",
-      "            \"rotation_order\": \"XYZ\",\n",
-      "            \"rotation_units\": \"degree\",\n",
-      "            \"x_translation\": 20.149,\n",
-      "            \"y_translation\": 109.963,\n",
-      "            \"z_translation\": 38.79,\n",
-      "            \"translation_units\": \"millimeter\"\n",
-      "        }\n",
-      "    }\n",
-      "}\n",
-      "try:\n",
-      "    # Get spatial placement\n",
-      "    api_response = api_instance.get_spatial_placement(get_spatial_placement_request)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->get_spatial_placement: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "0a2c6460",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='rui_loc'></a>\n",
-      "#### Get all hubmap rui locations (if enabled)\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "f15c90b1",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.gtex_rui_locations(cache = True)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "6e6fc39a",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='ontology_term'></a>\n",
-      "#### Get number of ontology term occurrences for a search\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional) \n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "dabe4526",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    api_response = api_instance.ontology_term_occurences(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "ae1132cc",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='cell_term_occ'></a>\n",
-      "#### Get number of cell type term occurrences for a search\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional) \n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "db1e1ebd",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    api_response = api_instance.cell_type_term_occurences(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "0e8bd39d",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='ontology_nodes'></a>\n",
-      "#### Get ontology term tree nodes\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "7d5e5dd0",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.ontology_tree_model(cache=True)\n",
-      "    for item in api_response:\n",
-      "        pprint(item)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "7170f6f3",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='cell_nodes'></a>\n",
-      "#### Get cell type tree nodes\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "e27e8ac1",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.cell_type_tree_model(cache = False)\n",
-      "    for item in api_response:\n",
-      "        pprint(item)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "0965c71e",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='providers'></a>\n",
-      "#### Get tissue provider names (for filtering)\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "5ff1a305",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.provider_names(cache = True)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "1537015d",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='ref_organs'></a>\n",
-      "#### Get all reference organs\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "eeaf481b",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.reference_organs(cache = True)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "1b602f81",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='3d_scene'></a>\n",
-      "#### Get all nodes to form the 3D scene for an organ\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional)\n",
-      "    organ-iri - (string) (required)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "87710b53",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "organ_iri = \"http://purl.obolibrary.org/obo/UBERON_0004539\"\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    # Get aggregate results / statistics\n",
-      "    api_response = api_instance.reference_organ_scene(organ_iri=organ_iri, age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
-      ")\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "1afabd89",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='nodes_3d'></a>\n",
-      "#### Get all nodes to form the 3D scene of reference body, organs, and tissues\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "2160f41b",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    # Get aggregate results / statistics\n",
-      "    api_response = api_instance.scene(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
-      ")\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "8e0e94cb",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='tech'></a>\n",
-      "#### Get technology names (for filtering)\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional)\n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "3f79894f",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try:\n",
-      "    api_response = api_instance.technology_names(cache = False)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "80c2337f",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='tissue_block'></a>\n",
-      "#### Get Tissue Block Results\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-      "    cache - (boolean)  (optional) (defaults to True)\n",
-      "    sex - (string)  (optional) (male, female, both)\n",
-      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-      "    providers - (string) (optional) \n",
-      "    ontology_terms - (string) (optional) \n",
-      "    cell_type_terms - (string) (optional) \n",
-      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-      "    token - (string) (optional)\n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "8f690344",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "age = MinMax(min=45.0, max=60.0)\n",
-      "bmi = MinMax(min=65.0, max=83.0)\n",
-      "cache = True\n",
-      "sex = \"female\"\n",
-      "technologies = []\n",
-      "providers = []\n",
-      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-      "spatial = [SpatialSearch(\n",
-      "            x=84.0,\n",
-      "            y=146.0,\n",
-      "            z=53.0,\n",
-      "            radius=12.0,\n",
-      "            target=\"http://purl.org/ccf/latest/ccf.owl#VHFAllenBrain\",\n",
-      "        ),]\n",
-      "token = \"\"\n",
-      "\n",
-      "try:\n",
-      "    api_response = api_instance.tissue_blocks(age=age, bmi=bmi, cache=cache, ontology_terms=ontology_terms, cell_type_terms=cell_type_terms, providers=providers, sex=sex, spatial=spatial, technologies=technologies, token=token\n",
-      ")\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "9cafd1d8",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='gtex_rui'></a>\n",
-      "#### Get all GTEx rui locations (if enabled)\n",
-      "<pre>\n",
-      "Accepted Parameters:\n",
-      "    cache - (boolean) (optional) \n",
-      "</pre>"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "3af8f4db",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "try: \n",
-      "    api_response = api_instance.gtex_rui_locations(cache = False)\n",
-      "    pprint(api_response)\n",
-      "except hra_api_client.ApiException as e:\n",
-      "    print(\"Exception when calling DefaultApi->aggregate_results: %s\\n\" % e)"
-    ]
-  },
-  {
-    "attachments": {},
-    "cell_type": "markdown",
-    "id": "1484a7ff",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='token_usage'></a>\n",
-      "#### Token Usage"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "a6157188",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "token = 'abbee123099245'\n",
-      "result = api_instance.db_status(token=token)\n",
-      "pprint(result)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "acbf417a",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='corridors'></a>\n",
-      "#### Generate a 3D corridor"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "4753f26a",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
-      "extraction_site = {\n",
-      "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-      "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
-      "    \"@type\": \"SpatialEntity\",\n",
-      "    \"creator\": \"demo demo\",\n",
-      "    \"creator_first_name\": \"demo\",\n",
-      "    \"creator_last_name\": \"demo\",\n",
-      "    \"creation_date\": \"2024-08-20\",\n",
-      "    \"ccf_annotations\": [\n",
-      "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
-      "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
-      "    ],\n",
-      "    \"x_dimension\": 10,\n",
-      "    \"y_dimension\": 10,\n",
-      "    \"z_dimension\": 10,\n",
-      "    \"dimension_units\": \"millimeter\",\n",
-      "    \"placement\": {\n",
-      "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-      "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
-      "        \"@type\": \"SpatialPlacement\",\n",
-      "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
-      "        \"placement_date\": \"2024-08-20\",\n",
-      "        \"x_scaling\": 1,\n",
-      "        \"y_scaling\": 1,\n",
-      "        \"z_scaling\": 1,\n",
-      "        \"scaling_units\": \"ratio\",\n",
-      "        \"x_rotation\": 0,\n",
-      "        \"y_rotation\": 0,\n",
-      "        \"z_rotation\": 0,\n",
-      "        \"rotation_order\": \"XYZ\",\n",
-      "        \"rotation_units\": \"degree\",\n",
-      "        \"x_translation\": 72.366,\n",
-      "        \"y_translation\": 79.067,\n",
-      "        \"z_translation\": 34.77,\n",
-      "        \"translation_units\": \"millimeter\"\n",
-      "    }\n",
-      "}\n",
-      "\n",
-      "# POST the extraction site\n",
-      "model = api_instance.corridor(extraction_site)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "09075bd6",
-    "metadata": {},
-    "source": [
-      "Save corridor to file:"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "74fcb536",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "corridor_file_name = \"corridor.glb\"\n",
-      "\n",
-      "# \"ab\" mode to append\n",
-      "with open(corridor_file_name, \"wb\") as binary_file:\n",
-      "\n",
-      "    # Write bytes to file\n",
-      "    binary_file.write(model)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "a7c4fad1",
-    "metadata": {},
-    "source": [
-      "##### Display with `pyvista`"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "fdb827fe",
-    "metadata": {},
-    "source": [
-      "Make sure to run:\n",
-      "`pip install \"pyvista[jupyter]\"`"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "073db386",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "import pyvista\n",
-      "from pyvista import examples\n",
-      "from itkwidgets import view\n",
-      "\n",
-      "pl = pyvista.Plotter()\n",
-      "pl.import_gltf(corridor_file_name)\n",
-      "pl.camera.zoom(1.0)\n",
-      "pl.show()"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "6ceb5a43",
-    "metadata": {},
-    "source": [
-      "##### Display with `k3d`/`vtk`"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "3d232ee1",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "import k3d\n",
-      "import vtk\n",
-      "import ipywidgets as widgets\n",
-      "\n",
-      "reader = vtk.vtkGLTFReader()\n",
-      "reader.SetFileName(corridor_file_name)\n",
-      "reader.Update()\n",
-      "\n",
-      "plot = k3d.plot()\n",
-      "mb = reader.GetOutput()\n",
-      "\n",
-      "iterator = mb.NewIterator()\n",
-      "\n",
-      "vtk_polyobjects = []\n",
-      "while not iterator.IsDoneWithTraversal():\n",
-      "    item = iterator.GetCurrentDataObject()\n",
-      "    vtk_polyobjects.append(item)\n",
-      "    iterator.GoToNextItem()\n",
-      "\n",
-      "\n",
-      "for obj in vtk_polyobjects:\n",
-      "    plot += k3d.vtk_poly_data(obj, color=0x222222)\n",
-      "plot.display()\n",
-      "\n",
-      "debug_info = widgets.HTML()"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "ebd70311",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='collision'></a>\n",
-      "#### Mesh-Based Collision Detection"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "8fe568bf",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
-      "extraction_site = {\n",
-      "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-      "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
-      "    \"@type\": \"SpatialEntity\",\n",
-      "    \"creator\": \"demo demo\",\n",
-      "    \"creator_first_name\": \"demo\",\n",
-      "    \"creator_last_name\": \"demo\",\n",
-      "    \"creation_date\": \"2024-08-20\",\n",
-      "    \"ccf_annotations\": [\n",
-      "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
-      "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
-      "    ],\n",
-      "    \"x_dimension\": 10,\n",
-      "    \"y_dimension\": 10,\n",
-      "    \"z_dimension\": 10,\n",
-      "    \"dimension_units\": \"millimeter\",\n",
-      "    \"placement\": {\n",
-      "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-      "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
-      "        \"@type\": \"SpatialPlacement\",\n",
-      "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
-      "        \"placement_date\": \"2024-08-20\",\n",
-      "        \"x_scaling\": 1,\n",
-      "        \"y_scaling\": 1,\n",
-      "        \"z_scaling\": 1,\n",
-      "        \"scaling_units\": \"ratio\",\n",
-      "        \"x_rotation\": 0,\n",
-      "        \"y_rotation\": 0,\n",
-      "        \"z_rotation\": 0,\n",
-      "        \"rotation_order\": \"XYZ\",\n",
-      "        \"rotation_units\": \"degree\",\n",
-      "        \"x_translation\": 72.366,\n",
-      "        \"y_translation\": 79.067,\n",
-      "        \"z_translation\": 34.77,\n",
-      "        \"translation_units\": \"millimeter\"\n",
-      "    }\n",
-      "}\n",
-      "\n",
-      "# Get mesh-based collisions\n",
-      "pprint(api_instance.collisions(extraction_site))"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "id": "13760167",
-    "metadata": {},
-    "source": [
-      "***\n",
-      "<a id='3d_cell'></a>\n",
-      "#### 3D Cell Generation"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "9773778c",
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# import pandas to convert API response into a DataFrame for easier downstream handling\n",
-      "import pandas as pd\n",
-      "\n",
-      "# Create your request parameters\n",
-      "params = {\n",
-      "    \"file\": \"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\",\n",
-      "    \"file_subpath\": \"VH_F_renal_pyramid_L_a\",\n",
-      "    \"num_nodes\": 10,\n",
-      "    \"node_distribution\": {\n",
-      "        \"KEY1\": 0.1,\n",
-      "        \"KEY2\": 0.3\n",
-      "    }\n",
-      "}\n",
-      "\n",
-      "# The result is a list of objects with x, y, z positions and types, accoording to the distribution and number of nodes specified in the parameters\n",
-      "response = api_instance.mesh3d_cell_population(params)\n",
-      "\n",
-      "# Convert to string\n",
-      "as_string = str(response, 'utf-8')\n",
-      "\n",
-      "# Convert the string to a DataFrame\n",
-      "df = pd.read_csv(StringIO(as_string))\n",
-      "\n",
-      "# Display the DataFrame\n",
-      "print(df)"
-    ]
-  }
-]
+{
+  "cells": [
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "40dd5488",
+      "metadata": {},
+      "source": [
+        "## HRA API Usage\n",
+        "This notebook shows how to use the HRA API method calls provided by the `hra_api_client` package. We will show how to set up the client and make a few calls. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "b5d71a77",
+      "metadata": {},
+      "source": [
+        "### Install package\n",
+        "For this notebook, we'll install the `hra-api-client` and a set of HRA UI widgets called `hra-jupyter-widgets`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "54983b34",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%pip install hra-api-client hra-jupyter-widgets"
+      ]
+    },
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "c3f1f6d5",
+      "metadata": {},
+      "source": [
+        "<a id='imports'></a>\n",
+        "### Imports \n",
+        "\n",
+        "We import the hra-api-client as follows:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "id": "e5e21389",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import hra_api_client"
+      ]
+    },
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "0d6f2a35",
+      "metadata": {},
+      "source": [
+        "Although we can use hra-api-client for all our tasks, it is easier if we have individual imports as follows:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "id": "d9f69dc1",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from hra_api_client.api import v1_api\n",
+        "from hra_api_client.api import hra_pop_api\n",
+        "from hra_api_client.api import ds_graph_api\n",
+        "from hra_api_client.models.aggregate_count import AggregateCount\n",
+        "from hra_api_client.models.database_status import DatabaseStatus\n",
+        "from hra_api_client.models.error_message import ErrorMessage\n",
+        "from hra_api_client.models.flat_spatial_placement import FlatSpatialPlacement\n",
+        "from hra_api_client.models.get_spatial_placement_request import GetSpatialPlacementRequest\n",
+        "from hra_api_client.models.min_max import MinMax\n",
+        "from hra_api_client.models.ontology_tree import OntologyTree\n",
+        "from hra_api_client.models.sparql_query_request import SparqlQueryRequest\n",
+        "from hra_api_client.models.spatial_entity import SpatialEntity\n",
+        "from hra_api_client.models.spatial_scene_node import SpatialSceneNode\n",
+        "from hra_api_client.models.spatial_search import SpatialSearch\n",
+        "from hra_api_client.models.tissue_block import TissueBlock"
+      ]
+    },
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "7c4af109",
+      "metadata": {},
+      "source": [
+        "For the purposes of this demonstration we need some other libraries imported here: "
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "id": "3952039c",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import time\n",
+        "from pprint import pprint\n",
+        "from hra_jupyter_widgets import ModelViewer"
+      ]
+    },
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "9faf09af",
+      "metadata": {},
+      "source": [
+        "### Creating the API Instance \n",
+        "We will now create an instance of the API client to use methods provided by the HRA API."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "id": "3d7b7374",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Client configuration, the default API endpoint is https://apps.humanatlas.io/api\n",
+        "configuration = hra_api_client.Configuration(\n",
+        "    host = \"https://apps.humanatlas.io/api\" \n",
+        ")\n",
+        "\n",
+        "# Base Client Object\n",
+        "api_client = hra_api_client.ApiClient(configuration)\n",
+        "\n",
+        "# Instance with which to call the primary /v1 routes from our API\n",
+        "api_instance = v1_api.V1Api(api_client)\n",
+        "\n",
+        "# Instance with which to call the /hra-pop routes\n",
+        "hra_pop_api_instance = hra_pop_api.HraPopApi(api_client)\n",
+        "\n",
+        "# Instance with which to call the /ds-graph routes\n",
+        "ds_graph_api_instance = ds_graph_api.DsGraphApi(api_client)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "536f4af1",
+      "metadata": {},
+      "source": [
+        "## Aggregate statistics\n",
+        "To get a quick idea of what data is available in the HRA API, you can use the `aggregate_results` method. With no options, it returns various counts for all default (federated) data."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "e42d97af",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "api_response = api_instance.aggregate_results()\n",
+        "for x in api_response:\n",
+        "  print(x.count, x.label)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "9afdfe07",
+      "metadata": {},
+      "source": [
+        "## Get a session token for HuBMAP data\n",
+        "You can limit to certain sets of data by creating a session token. We will create a session for just HuBMAP data. Filters, discussed later, can also be used here to make a smaller set of data for more targeted studies.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "2cd78368",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Session configuration. You can add your HuBMAP token after ?token= to get private data\n",
+        "session_configuration = { \"dataSources\": [\"https://apps.humanatlas.io/api/ds-graph/hubmap?token=\"] }\n",
+        "\n",
+        "# Get a session token for this configuration\n",
+        "api_response = api_instance.session_token(session_configuration)\n",
+        "token=api_response.token\n",
+        "print(token)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "f7c9d42e",
+      "metadata": {},
+      "source": [
+        "After we get the session token, we wait to make sure the session is ready."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "49d052a1",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "db_ready = False\n",
+        "while not db_ready:\n",
+        "    api_response = api_instance.db_status(token)\n",
+        "    print(api_response)\n",
+        "    if api_response.status == 'Ready':\n",
+        "        db_ready = True\n",
+        "    else:\n",
+        "        print('Database not ready yet! Retrying...')\n",
+        "        time.sleep(2)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "053ef46e",
+      "metadata": {},
+      "source": [
+        "## Examine the HuBMAP data\n",
+        "Now we can check the data available in the session we created"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "180bfa92",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# get aggregate statistics\n",
+        "api_response = api_instance.aggregate_results(token=token)\n",
+        "for x in api_response:\n",
+        "  print(x.count, x.label)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "4f4c3fcb",
+      "metadata": {},
+      "source": [
+        "Let's get all of the tissue blocks (with a RUI location) in HuBMAP"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "3b35d563",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# get all tissue blocks\n",
+        "api_response = api_instance.tissue_blocks(token=token)\n",
+        "\n",
+        "# print first five block links\n",
+        "for x in api_response[0:5]:\n",
+        "  print(x.link)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "ab610593",
+      "metadata": {},
+      "source": [
+        "## Filter the HuBMAP data"
+      ]
+    },
+    {
+      "attachments": {},
+      "cell_type": "markdown",
+      "id": "2e383f49",
+      "metadata": {},
+      "source": [
+        "Certain parameters can be used to filter the data. Most methods that query the data have these filters to use:\n",
+        "<pre>\n",
+        "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+        "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+        "    sex - (string)  (optional) (male, female, both)\n",
+        "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+        "    providers - (string) (optional) \n",
+        "    ontology_terms - (string) (optional) (List of ontology terms)\n",
+        "    cell_type_terms - (string) (optional) (List of ontology tems)\n",
+        "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+        "    token - (string) (optional) the session token, if not provided it will use the default dataset\n",
+        "</pre>\n",
+        "\n",
+        "Example instantantiations of the filters are below."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "20a78738",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "age = MinMax(min=45.0, max=60.0)\n",
+        "bmi = MinMax(min=65.0, max=83.0)\n",
+        "sex = \"Female\"\n",
+        "technologies = []\n",
+        "providers = []\n",
+        "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+        "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+        "spatial = [SpatialSearch(\n",
+        "            x=84.0,\n",
+        "            y=146.0,\n",
+        "            z=53.0,\n",
+        "            radius=12.0,\n",
+        "            target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
+        "        ),]\n",
+        "\n",
+        "# get filtered aggregate statistics\n",
+        "api_response = api_instance.aggregate_results(\n",
+        "                    age=age,\n",
+        "                    bmi=bmi, \n",
+        "                    ontology_terms=ontology_terms,\n",
+        "                    cell_type_terms=cell_type_terms, \n",
+        "                    providers=providers,\n",
+        "                    sex=sex,\n",
+        "                    spatial=spatial,\n",
+        "                    technologies=technologies,\n",
+        "                    token=token)\n",
+        "for x in api_response:\n",
+        "  print(x.count, x.label)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "7ec49d8f",
+      "metadata": {},
+      "source": [
+        "Another way to manage these filters is to create a Dictionary and use python's `**kwargs` syntax to create and pass around a filter object. We'll use this filter object for several methods below."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "431c8aac",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "filter = {\n",
+        "  \"age\": MinMax(min=45.0, max=60.0),\n",
+        "  \"bmi\": MinMax(min=65.0, max=83.0),\n",
+        "  \"sex\": \"Female\",\n",
+        "  \"technologies\": [],\n",
+        "  \"providers\": [],\n",
+        "  \"ontology_terms\": [\"http://purl.obolibrary.org/obo/UBERON_0000955\"],\n",
+        "  \"cell_type_terms\": [\"http://purl.obolibrary.org/obo/CL_0000000\"],\n",
+        "  \"spatial\": [\n",
+        "    SpatialSearch(\n",
+        "      x=84.0,\n",
+        "      y=146.0,\n",
+        "      z=53.0,\n",
+        "      radius=12.0,\n",
+        "      target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
+        "    )\n",
+        "  ]\n",
+        "}\n",
+        "\n",
+        "# get filtered aggregate statistics\n",
+        "api_response = api_instance.aggregate_results(token=token, **filter)\n",
+        "for x in api_response:\n",
+        "  print(x.count, x.label)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "f64b8987",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# get anatomical structures that the tissue blocks collided with\n",
+        "api_response = api_instance.ontology_term_occurences(token=token, **filter)\n",
+        "\n",
+        "# Print the first 5 results\n",
+        "for (anatomical_structure, count) in list(api_response.items())[0:5]:\n",
+        "  print(anatomical_structure, count)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "a972877d",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# get cell types located in anatomical structures that the tissue blocks collided with\n",
+        "api_response = api_instance.cell_type_term_occurences(token=token, **filter)\n",
+        "\n",
+        "# Print the first 5 results\n",
+        "for (cell_type, count) in list(api_response.items())[0:5]:\n",
+        "  print(cell_type, count)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "98d83caf",
+      "metadata": {},
+      "source": [
+        "## Query the HRA Knowledge Graph with SPARQL\n",
+        "The HRA API provides a SPARQL endpoint to query the HRA knowledge graph. This allows you to select out very specific data using advanced SPARQL querying. \n",
+        "\n",
+        "To demonstrate, let's get all the anatomical structures in the latest HRA release."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "f2db2619",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "query = '''\n",
+        "PREFIX ccf: <http://purl.org/ccf/>\n",
+        "SELECT ?as ?label\n",
+        "FROM <https://purl.humanatlas.io/collection/hra>\n",
+        "WHERE {\n",
+        "  ?as ccf:ccf_asctb_type ?type ;\n",
+        "    ccf:ccf_pref_label ?label .\n",
+        "  FILTER(?type = 'AS')\n",
+        "}\n",
+        "'''\n",
+        "api_response = api_instance.sparql(query=query)\n",
+        "rows = api_response['results']['bindings']\n",
+        "\n",
+        "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
+        "\n",
+        "# Print the first 5 results\n",
+        "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
+        "  print(anatomical_structure, label)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "4434af2f",
+      "metadata": {},
+      "source": [
+        "If your SPARQL query is longer (thousands of characters), you can do a SPARQL POST which allows for sending more data."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "70bef89a",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "api_response = api_instance.sparql_post({'query': query})\n",
+        "rows = api_response['results']['bindings']\n",
+        "\n",
+        "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
+        "\n",
+        "# Print the first 5 results\n",
+        "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
+        "  print(anatomical_structure, label)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "579311b2",
+      "metadata": {},
+      "source": [
+        "## Working with extraction sites (aka RUI locations)\n",
+        "After obtaining an extraction site either via the RUI or from queries like above, there are a few things you can do with this data."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "acbf417a",
+      "metadata": {},
+      "source": [
+        "### Generate a 3D corridor\n",
+        "\n",
+        "We can compute a corridor from any extraction site. A corridor shows where else an extraction site could go in the same organ and still maintain the same overlaps with anatomical structures. We will take an example extraction site and see what it's corridor looks like."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "8a5e9e88",
+      "metadata": {},
+      "source": [
+        "An example extraction site:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 17,
+      "id": "4753f26a",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
+        "extraction_site = {\n",
+        "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+        "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
+        "    \"@type\": \"SpatialEntity\",\n",
+        "    \"creator\": \"demo demo\",\n",
+        "    \"creator_first_name\": \"demo\",\n",
+        "    \"creator_last_name\": \"demo\",\n",
+        "    \"creation_date\": \"2024-08-20\",\n",
+        "    \"ccf_annotations\": [\n",
+        "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
+        "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
+        "    ],\n",
+        "    \"x_dimension\": 10,\n",
+        "    \"y_dimension\": 10,\n",
+        "    \"z_dimension\": 10,\n",
+        "    \"dimension_units\": \"millimeter\",\n",
+        "    \"placement\": {\n",
+        "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+        "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
+        "        \"@type\": \"SpatialPlacement\",\n",
+        "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
+        "        \"placement_date\": \"2024-08-20\",\n",
+        "        \"x_scaling\": 1,\n",
+        "        \"y_scaling\": 1,\n",
+        "        \"z_scaling\": 1,\n",
+        "        \"scaling_units\": \"ratio\",\n",
+        "        \"x_rotation\": 0,\n",
+        "        \"y_rotation\": 0,\n",
+        "        \"z_rotation\": 0,\n",
+        "        \"rotation_order\": \"XYZ\",\n",
+        "        \"rotation_units\": \"degree\",\n",
+        "        \"x_translation\": 72.366,\n",
+        "        \"y_translation\": 79.067,\n",
+        "        \"z_translation\": 34.77,\n",
+        "        \"translation_units\": \"millimeter\"\n",
+        "    }\n",
+        "}"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "b7c51796",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Generate a corridor for the extraction site\n",
+        "model = api_instance.corridor(extraction_site)\n",
+        "\n",
+        "# Display it in 3D\n",
+        "viewer = ModelViewer(data=model)\n",
+        "display(viewer)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "ebd70311",
+      "metadata": {},
+      "source": [
+        "### Find anatomical structure collisions for an extraction site\n",
+        "For any extraction site, we can analyze what anatomical structures it collides with in the 3D reference organ and by how much."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "8fe568bf",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Get mesh-based collisions\n",
+        "collisions = api_instance.collisions(extraction_site)\n",
+        "\n",
+        "pprint(collisions[0:5])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "ee5d1ae3",
+      "metadata": {},
+      "source": [
+        "## Conclusion\n",
+        "This concludes this tutorial. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples. If you have any issues, problems, or questions, feel free to file an issue on the HRA API GitHub at <https://github.com/x-atlas-consortia/hra-api>."
+      ]
+    }
+  ],
+  "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.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
index 0f52a6d..f445872 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
@@ -1,194 +1,223 @@
-[
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "## Usage\n",
-      "This notebook shows how to use the different widgets provided by the hra_jupyter_widgets package."
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# linked datasets\n",
-      "uuids = {{ uuids | safe }}"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "### Install package"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "%pip install hra_jupyter_widgets"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "### Import widgets"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "import ipywidgets as widgets\n",
-      "from hra_jupyter_widgets import (\n",
-      "    EuiOrganInformation,\n",
-      "    FtuExplorer,\n",
-      "    FtuExplorerSmall,\n",
-      "    MedicalIllustration,\n",
-      "    ModelViewer\n",
-      ")"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "### Configure organ and illustration"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# Kidney uberon id\n",
-      "organ = \"http://purl.obolibrary.org/obo/UBERON_0002113\"\n",
-      "illustration = \"https://purl.humanatlas.io/2d-ftu/kidney-renal-corpuscle\""
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "### Create and use a widget"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "medical_illustration = MedicalIllustration(selected_illustration=illustration)\n",
-      "display(medical_illustration)"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "# Create an output widget\n",
-      "output = widgets.Output()\n",
-      "\n",
-      "\n",
-      "# Create an event listener that prints to the output widget\n",
-      "# It takes a single argument - the event data\n",
-      "def cell_click(cell):\n",
-      "    with output:\n",
-      "        print(f\"Cell clicked: '{cell['label']}'\")\n",
-      "\n",
-      "\n",
-      "# Register the listener\n",
-      "medical_illustration.on_cell_click(cell_click)\n",
-      "# Listeners can be removed by calling on_cell_click with remove=True, i.e.\n",
-      "# medical_illustration.on_cell_click(cell_click, remove=True)\n",
-      "\n",
-      "display(output)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "### Widget showcase"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "#### Eui Organ Information"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "organ_info = EuiOrganInformation(organ_iri=organ)\n",
-      "display(organ_info)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "#### FTU explorer (small version)"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "ftu_explorer_small = FtuExplorerSmall(selected_illustration=illustration)\n",
-      "display(ftu_explorer_small)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "#### FTU explorer (full version)"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "ftu_explorer = FtuExplorer()\n",
-      "display(ftu_explorer)"
-    ]
-  },
-  {
-    "cell_type": "markdown",
-    "metadata": {},
-    "source": [
-      "#### 3D Model Viewer"
-    ]
-  },
-  {
-    "cell_type": "code",
-    "execution_count": null,
-    "metadata": {},
-    "outputs": [],
-    "source": [
-      "model_viewer = ModelViewer(url=\"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\")\n",
-      "display(model_viewer)"
-    ]
-  }
-]
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## HRA UI Jupyter Widgets Usage\n",
+        "This notebook shows how to use the different widgets provided by the `hra-jupyter-widgets` package."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Install package\n",
+        "For this notebook, we'll install the `hra-jupyter-widgets` and `ipywidgets` for displaying the widgets."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%pip install hra-jupyter-widgets ipywidgets"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Imports"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We import the Jupyter Widgets as follows:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 17,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from hra_jupyter_widgets import (\n",
+        "    EuiOrganInformation,\n",
+        "    FtuExplorerSmall,\n",
+        "    MedicalIllustration,\n",
+        "    ModelViewer\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "For the purposes of this demonstration we need some other libraries imported here: "
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 18,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import ipywidgets as widgets"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Configure organ and illustration to use\n",
+        "Other options are available, but we will focus on Kidney and the renal corpuscle FTU in the widgets below."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 19,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Kidney uberon id\n",
+        "organ = \"http://purl.obolibrary.org/obo/UBERON_0002113\"\n",
+        "illustration = \"https://purl.humanatlas.io/2d-ftu/kidney-renal-corpuscle\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Full example with FTU"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create and use a medical illustration widget\n",
+        "Let's display a medical illustration of the kidney corpuscle."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "medical_illustration = MedicalIllustration(selected_illustration=illustration)\n",
+        "display(medical_illustration)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can listen to interaction events in the medical illustration and output them below."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Create an output widget\n",
+        "output = widgets.Output()\n",
+        "\n",
+        "# Create an event listener that prints to the output widget\n",
+        "# It takes a single argument - the event data\n",
+        "def cell_click(cell):\n",
+        "    with output:\n",
+        "        print(f\"Cell clicked: '{cell['label']}'\")\n",
+        "\n",
+        "# Register the listener\n",
+        "medical_illustration.on_cell_click(cell_click)\n",
+        "\n",
+        "# Listeners can be removed by calling on_cell_click with remove=True, i.e.\n",
+        "# medical_illustration.on_cell_click(cell_click, remove=True)\n",
+        "\n",
+        "display(output)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Organ Information Widget\n",
+        "Let's create an organ information widget for the Kidney to see all data registered there."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "organ_info = EuiOrganInformation(organ_iri=organ)\n",
+        "display(organ_info)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## FTU explorer\n",
+        "Let's make an FTU explorer instance that shows the renal corpuscle by default."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "ftu_explorer_small = FtuExplorerSmall(selected_illustration=illustration)\n",
+        "display(ftu_explorer_small)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 3D Model Viewer\n",
+        "We have integrated Google's Model Viewer web component here as a jupyter widget. You can use it to view 3D models using the GLB format."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "model_viewer = ModelViewer(url=\"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\")\n",
+        "display(model_viewer)"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": ".venv",
+      "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.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 2
+}

From c2ab046d92af3ac7c7b1be31c729b20bd2cdb589 Mon Sep 17 00:00:00 2001
From: "Bruce W. Herr II" <bherr@indiana.edu>
Date: Tue, 17 Sep 2024 07:56:15 -0400
Subject: [PATCH 10/27] Removed example datasets

---
 .../jupyter_lab/templates/hra_api_tutorial/metadata.json      | 2 +-
 .../templates/hra_ui_widgets_tutorial/metadata.json           | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
index 1bae420..bbaaa7d 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
@@ -11,7 +11,7 @@
     {
       "title": "Working with the HRA API examples",
       "description": "Example metadata and available files for four datasets.",
-      "datasets": ["41d665c06bbec9b4dcaec6d835acb0fb", "03a8a12acfa25c2414cfdada4a4b5fd6", "880474c3108655acfe6f8c30137f22ae", "3bc3ad124014a632d558255626bf38c9"]
+      "datasets": []
     }
   ],
   "is_hidden": false,
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
index eb7c5c1..90c9870 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
@@ -9,9 +9,9 @@
   "template_format": "jinja",
   "examples": [
     {
-      "title": "Working with the HRA UI Jupyter Widgets examples",
+      "title": "Working with the HRA UI Jupyter Widgets",
       "description": "Example metadata and available files for four datasets.",
-      "datasets": ["41d665c06bbec9b4dcaec6d835acb0fb", "03a8a12acfa25c2414cfdada4a4b5fd6", "880474c3108655acfe6f8c30137f22ae", "3bc3ad124014a632d558255626bf38c9"]
+      "datasets": []
     }
   ],
   "is_hidden": false,

From 8ae332e04b9cf417dd0283b573cd435c63f1a7cd Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 09:45:00 -0400
Subject: [PATCH 11/27] update descriptions of examples

---
 .../jupyter_lab/templates/hra_api_tutorial/metadata.json        | 2 +-
 .../jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
index bbaaa7d..0d2feea 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
@@ -10,7 +10,7 @@
   "examples": [
     {
       "title": "Working with the HRA API examples",
-      "description": "Example metadata and available files for four datasets.",
+      "description": "Retrieve aggregate statistics, query and filter and examine extraction sites.",
       "datasets": []
     }
   ],
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
index 90c9870..c5e1c63 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
@@ -10,7 +10,7 @@
   "examples": [
     {
       "title": "Working with the HRA UI Jupyter Widgets",
-      "description": "Example metadata and available files for four datasets.",
+      "description": "Examine the organ widget, FTU explorer, and 3D model viewer.",
       "datasets": []
     }
   ],

From 74cff990193e1717d54fbe72e3ce209335b0b5fa Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 09:48:29 -0400
Subject: [PATCH 12/27] fix formatting of templates

---
 .../templates/hra_api_tutorial/template.txt   | 1141 ++++++++---------
 .../hra_ui_widgets_tutorial/template.txt      |  423 +++---
 2 files changed, 739 insertions(+), 825 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
index 48a89da..faa42aa 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/template.txt
@@ -1,602 +1,539 @@
-{
-  "cells": [
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "40dd5488",
-      "metadata": {},
-      "source": [
-        "## HRA API Usage\n",
-        "This notebook shows how to use the HRA API method calls provided by the `hra_api_client` package. We will show how to set up the client and make a few calls. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples."
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "b5d71a77",
-      "metadata": {},
-      "source": [
-        "### Install package\n",
-        "For this notebook, we'll install the `hra-api-client` and a set of HRA UI widgets called `hra-jupyter-widgets`."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "54983b34",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "%pip install hra-api-client hra-jupyter-widgets"
-      ]
-    },
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "c3f1f6d5",
-      "metadata": {},
-      "source": [
-        "<a id='imports'></a>\n",
-        "### Imports \n",
-        "\n",
-        "We import the hra-api-client as follows:"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 2,
-      "id": "e5e21389",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import hra_api_client"
-      ]
-    },
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "0d6f2a35",
-      "metadata": {},
-      "source": [
-        "Although we can use hra-api-client for all our tasks, it is easier if we have individual imports as follows:"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 3,
-      "id": "d9f69dc1",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "from hra_api_client.api import v1_api\n",
-        "from hra_api_client.api import hra_pop_api\n",
-        "from hra_api_client.api import ds_graph_api\n",
-        "from hra_api_client.models.aggregate_count import AggregateCount\n",
-        "from hra_api_client.models.database_status import DatabaseStatus\n",
-        "from hra_api_client.models.error_message import ErrorMessage\n",
-        "from hra_api_client.models.flat_spatial_placement import FlatSpatialPlacement\n",
-        "from hra_api_client.models.get_spatial_placement_request import GetSpatialPlacementRequest\n",
-        "from hra_api_client.models.min_max import MinMax\n",
-        "from hra_api_client.models.ontology_tree import OntologyTree\n",
-        "from hra_api_client.models.sparql_query_request import SparqlQueryRequest\n",
-        "from hra_api_client.models.spatial_entity import SpatialEntity\n",
-        "from hra_api_client.models.spatial_scene_node import SpatialSceneNode\n",
-        "from hra_api_client.models.spatial_search import SpatialSearch\n",
-        "from hra_api_client.models.tissue_block import TissueBlock"
-      ]
-    },
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "7c4af109",
-      "metadata": {},
-      "source": [
-        "For the purposes of this demonstration we need some other libraries imported here: "
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 4,
-      "id": "3952039c",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import time\n",
-        "from pprint import pprint\n",
-        "from hra_jupyter_widgets import ModelViewer"
-      ]
-    },
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "9faf09af",
-      "metadata": {},
-      "source": [
-        "### Creating the API Instance \n",
-        "We will now create an instance of the API client to use methods provided by the HRA API."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 5,
-      "id": "3d7b7374",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Client configuration, the default API endpoint is https://apps.humanatlas.io/api\n",
-        "configuration = hra_api_client.Configuration(\n",
-        "    host = \"https://apps.humanatlas.io/api\" \n",
-        ")\n",
-        "\n",
-        "# Base Client Object\n",
-        "api_client = hra_api_client.ApiClient(configuration)\n",
-        "\n",
-        "# Instance with which to call the primary /v1 routes from our API\n",
-        "api_instance = v1_api.V1Api(api_client)\n",
-        "\n",
-        "# Instance with which to call the /hra-pop routes\n",
-        "hra_pop_api_instance = hra_pop_api.HraPopApi(api_client)\n",
-        "\n",
-        "# Instance with which to call the /ds-graph routes\n",
-        "ds_graph_api_instance = ds_graph_api.DsGraphApi(api_client)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "536f4af1",
-      "metadata": {},
-      "source": [
-        "## Aggregate statistics\n",
-        "To get a quick idea of what data is available in the HRA API, you can use the `aggregate_results` method. With no options, it returns various counts for all default (federated) data."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "e42d97af",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "api_response = api_instance.aggregate_results()\n",
-        "for x in api_response:\n",
-        "  print(x.count, x.label)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "9afdfe07",
-      "metadata": {},
-      "source": [
-        "## Get a session token for HuBMAP data\n",
-        "You can limit to certain sets of data by creating a session token. We will create a session for just HuBMAP data. Filters, discussed later, can also be used here to make a smaller set of data for more targeted studies.\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "2cd78368",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Session configuration. You can add your HuBMAP token after ?token= to get private data\n",
-        "session_configuration = { \"dataSources\": [\"https://apps.humanatlas.io/api/ds-graph/hubmap?token=\"] }\n",
-        "\n",
-        "# Get a session token for this configuration\n",
-        "api_response = api_instance.session_token(session_configuration)\n",
-        "token=api_response.token\n",
-        "print(token)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "f7c9d42e",
-      "metadata": {},
-      "source": [
-        "After we get the session token, we wait to make sure the session is ready."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "49d052a1",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "db_ready = False\n",
-        "while not db_ready:\n",
-        "    api_response = api_instance.db_status(token)\n",
-        "    print(api_response)\n",
-        "    if api_response.status == 'Ready':\n",
-        "        db_ready = True\n",
-        "    else:\n",
-        "        print('Database not ready yet! Retrying...')\n",
-        "        time.sleep(2)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "053ef46e",
-      "metadata": {},
-      "source": [
-        "## Examine the HuBMAP data\n",
-        "Now we can check the data available in the session we created"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "180bfa92",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# get aggregate statistics\n",
-        "api_response = api_instance.aggregate_results(token=token)\n",
-        "for x in api_response:\n",
-        "  print(x.count, x.label)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "4f4c3fcb",
-      "metadata": {},
-      "source": [
-        "Let's get all of the tissue blocks (with a RUI location) in HuBMAP"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "3b35d563",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# get all tissue blocks\n",
-        "api_response = api_instance.tissue_blocks(token=token)\n",
-        "\n",
-        "# print first five block links\n",
-        "for x in api_response[0:5]:\n",
-        "  print(x.link)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "ab610593",
-      "metadata": {},
-      "source": [
-        "## Filter the HuBMAP data"
-      ]
-    },
-    {
-      "attachments": {},
-      "cell_type": "markdown",
-      "id": "2e383f49",
-      "metadata": {},
-      "source": [
-        "Certain parameters can be used to filter the data. Most methods that query the data have these filters to use:\n",
-        "<pre>\n",
-        "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
-        "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
-        "    sex - (string)  (optional) (male, female, both)\n",
-        "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
-        "    providers - (string) (optional) \n",
-        "    ontology_terms - (string) (optional) (List of ontology terms)\n",
-        "    cell_type_terms - (string) (optional) (List of ontology tems)\n",
-        "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
-        "    token - (string) (optional) the session token, if not provided it will use the default dataset\n",
-        "</pre>\n",
-        "\n",
-        "Example instantantiations of the filters are below."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "20a78738",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "age = MinMax(min=45.0, max=60.0)\n",
-        "bmi = MinMax(min=65.0, max=83.0)\n",
-        "sex = \"Female\"\n",
-        "technologies = []\n",
-        "providers = []\n",
-        "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
-        "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
-        "spatial = [SpatialSearch(\n",
-        "            x=84.0,\n",
-        "            y=146.0,\n",
-        "            z=53.0,\n",
-        "            radius=12.0,\n",
-        "            target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
-        "        ),]\n",
-        "\n",
-        "# get filtered aggregate statistics\n",
-        "api_response = api_instance.aggregate_results(\n",
-        "                    age=age,\n",
-        "                    bmi=bmi, \n",
-        "                    ontology_terms=ontology_terms,\n",
-        "                    cell_type_terms=cell_type_terms, \n",
-        "                    providers=providers,\n",
-        "                    sex=sex,\n",
-        "                    spatial=spatial,\n",
-        "                    technologies=technologies,\n",
-        "                    token=token)\n",
-        "for x in api_response:\n",
-        "  print(x.count, x.label)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "7ec49d8f",
-      "metadata": {},
-      "source": [
-        "Another way to manage these filters is to create a Dictionary and use python's `**kwargs` syntax to create and pass around a filter object. We'll use this filter object for several methods below."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "431c8aac",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "filter = {\n",
-        "  \"age\": MinMax(min=45.0, max=60.0),\n",
-        "  \"bmi\": MinMax(min=65.0, max=83.0),\n",
-        "  \"sex\": \"Female\",\n",
-        "  \"technologies\": [],\n",
-        "  \"providers\": [],\n",
-        "  \"ontology_terms\": [\"http://purl.obolibrary.org/obo/UBERON_0000955\"],\n",
-        "  \"cell_type_terms\": [\"http://purl.obolibrary.org/obo/CL_0000000\"],\n",
-        "  \"spatial\": [\n",
-        "    SpatialSearch(\n",
-        "      x=84.0,\n",
-        "      y=146.0,\n",
-        "      z=53.0,\n",
-        "      radius=12.0,\n",
-        "      target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
-        "    )\n",
-        "  ]\n",
-        "}\n",
-        "\n",
-        "# get filtered aggregate statistics\n",
-        "api_response = api_instance.aggregate_results(token=token, **filter)\n",
-        "for x in api_response:\n",
-        "  print(x.count, x.label)"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "f64b8987",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# get anatomical structures that the tissue blocks collided with\n",
-        "api_response = api_instance.ontology_term_occurences(token=token, **filter)\n",
-        "\n",
-        "# Print the first 5 results\n",
-        "for (anatomical_structure, count) in list(api_response.items())[0:5]:\n",
-        "  print(anatomical_structure, count)"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "a972877d",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# get cell types located in anatomical structures that the tissue blocks collided with\n",
-        "api_response = api_instance.cell_type_term_occurences(token=token, **filter)\n",
-        "\n",
-        "# Print the first 5 results\n",
-        "for (cell_type, count) in list(api_response.items())[0:5]:\n",
-        "  print(cell_type, count)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "98d83caf",
-      "metadata": {},
-      "source": [
-        "## Query the HRA Knowledge Graph with SPARQL\n",
-        "The HRA API provides a SPARQL endpoint to query the HRA knowledge graph. This allows you to select out very specific data using advanced SPARQL querying. \n",
-        "\n",
-        "To demonstrate, let's get all the anatomical structures in the latest HRA release."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "f2db2619",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "query = '''\n",
-        "PREFIX ccf: <http://purl.org/ccf/>\n",
-        "SELECT ?as ?label\n",
-        "FROM <https://purl.humanatlas.io/collection/hra>\n",
-        "WHERE {\n",
-        "  ?as ccf:ccf_asctb_type ?type ;\n",
-        "    ccf:ccf_pref_label ?label .\n",
-        "  FILTER(?type = 'AS')\n",
-        "}\n",
-        "'''\n",
-        "api_response = api_instance.sparql(query=query)\n",
-        "rows = api_response['results']['bindings']\n",
-        "\n",
-        "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
-        "\n",
-        "# Print the first 5 results\n",
-        "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
-        "  print(anatomical_structure, label)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "4434af2f",
-      "metadata": {},
-      "source": [
-        "If your SPARQL query is longer (thousands of characters), you can do a SPARQL POST which allows for sending more data."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "70bef89a",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "api_response = api_instance.sparql_post({'query': query})\n",
-        "rows = api_response['results']['bindings']\n",
-        "\n",
-        "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
-        "\n",
-        "# Print the first 5 results\n",
-        "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
-        "  print(anatomical_structure, label)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "579311b2",
-      "metadata": {},
-      "source": [
-        "## Working with extraction sites (aka RUI locations)\n",
-        "After obtaining an extraction site either via the RUI or from queries like above, there are a few things you can do with this data."
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "acbf417a",
-      "metadata": {},
-      "source": [
-        "### Generate a 3D corridor\n",
-        "\n",
-        "We can compute a corridor from any extraction site. A corridor shows where else an extraction site could go in the same organ and still maintain the same overlaps with anatomical structures. We will take an example extraction site and see what it's corridor looks like."
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "8a5e9e88",
-      "metadata": {},
-      "source": [
-        "An example extraction site:"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 17,
-      "id": "4753f26a",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
-        "extraction_site = {\n",
-        "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-        "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
-        "    \"@type\": \"SpatialEntity\",\n",
-        "    \"creator\": \"demo demo\",\n",
-        "    \"creator_first_name\": \"demo\",\n",
-        "    \"creator_last_name\": \"demo\",\n",
-        "    \"creation_date\": \"2024-08-20\",\n",
-        "    \"ccf_annotations\": [\n",
-        "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
-        "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
-        "    ],\n",
-        "    \"x_dimension\": 10,\n",
-        "    \"y_dimension\": 10,\n",
-        "    \"z_dimension\": 10,\n",
-        "    \"dimension_units\": \"millimeter\",\n",
-        "    \"placement\": {\n",
-        "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
-        "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
-        "        \"@type\": \"SpatialPlacement\",\n",
-        "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
-        "        \"placement_date\": \"2024-08-20\",\n",
-        "        \"x_scaling\": 1,\n",
-        "        \"y_scaling\": 1,\n",
-        "        \"z_scaling\": 1,\n",
-        "        \"scaling_units\": \"ratio\",\n",
-        "        \"x_rotation\": 0,\n",
-        "        \"y_rotation\": 0,\n",
-        "        \"z_rotation\": 0,\n",
-        "        \"rotation_order\": \"XYZ\",\n",
-        "        \"rotation_units\": \"degree\",\n",
-        "        \"x_translation\": 72.366,\n",
-        "        \"y_translation\": 79.067,\n",
-        "        \"z_translation\": 34.77,\n",
-        "        \"translation_units\": \"millimeter\"\n",
-        "    }\n",
-        "}"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "b7c51796",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Generate a corridor for the extraction site\n",
-        "model = api_instance.corridor(extraction_site)\n",
-        "\n",
-        "# Display it in 3D\n",
-        "viewer = ModelViewer(data=model)\n",
-        "display(viewer)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "ebd70311",
-      "metadata": {},
-      "source": [
-        "### Find anatomical structure collisions for an extraction site\n",
-        "For any extraction site, we can analyze what anatomical structures it collides with in the 3D reference organ and by how much."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "id": "8fe568bf",
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Get mesh-based collisions\n",
-        "collisions = api_instance.collisions(extraction_site)\n",
-        "\n",
-        "pprint(collisions[0:5])"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "id": "ee5d1ae3",
-      "metadata": {},
-      "source": [
-        "## Conclusion\n",
-        "This concludes this tutorial. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples. If you have any issues, problems, or questions, feel free to file an issue on the HRA API GitHub at <https://github.com/x-atlas-consortia/hra-api>."
-      ]
-    }
-  ],
-  "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.12"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 5
-}
+[
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## HRA API Usage\n",
+      "This notebook shows how to use the HRA API method calls provided by the `hra_api_client` package. We will show how to set up the client and make a few calls. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples."
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Install package\n",
+      "For this notebook, we'll install the `hra-api-client` and a set of HRA UI widgets called `hra-jupyter-widgets`."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "%pip install hra-api-client hra-jupyter-widgets"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "<a id='imports'></a>\n",
+      "### Imports \n",
+      "\n",
+      "We import the hra-api-client as follows:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import hra_api_client"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "Although we can use hra-api-client for all our tasks, it is easier if we have individual imports as follows:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "from hra_api_client.api import v1_api\n",
+      "from hra_api_client.api import hra_pop_api\n",
+      "from hra_api_client.api import ds_graph_api\n",
+      "from hra_api_client.models.aggregate_count import AggregateCount\n",
+      "from hra_api_client.models.database_status import DatabaseStatus\n",
+      "from hra_api_client.models.error_message import ErrorMessage\n",
+      "from hra_api_client.models.flat_spatial_placement import FlatSpatialPlacement\n",
+      "from hra_api_client.models.get_spatial_placement_request import GetSpatialPlacementRequest\n",
+      "from hra_api_client.models.min_max import MinMax\n",
+      "from hra_api_client.models.ontology_tree import OntologyTree\n",
+      "from hra_api_client.models.sparql_query_request import SparqlQueryRequest\n",
+      "from hra_api_client.models.spatial_entity import SpatialEntity\n",
+      "from hra_api_client.models.spatial_scene_node import SpatialSceneNode\n",
+      "from hra_api_client.models.spatial_search import SpatialSearch\n",
+      "from hra_api_client.models.tissue_block import TissueBlock"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "For the purposes of this demonstration we need some other libraries imported here: "
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import time\n",
+      "from pprint import pprint\n",
+      "from hra_jupyter_widgets import ModelViewer"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Creating the API Instance \n",
+      "We will now create an instance of the API client to use methods provided by the HRA API."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Client configuration, the default API endpoint is https://apps.humanatlas.io/api\n",
+      "configuration = hra_api_client.Configuration(\n",
+      "    host = \"https://apps.humanatlas.io/api\" \n",
+      ")\n",
+      "\n",
+      "# Base Client Object\n",
+      "api_client = hra_api_client.ApiClient(configuration)\n",
+      "\n",
+      "# Instance with which to call the primary /v1 routes from our API\n",
+      "api_instance = v1_api.V1Api(api_client)\n",
+      "\n",
+      "# Instance with which to call the /hra-pop routes\n",
+      "hra_pop_api_instance = hra_pop_api.HraPopApi(api_client)\n",
+      "\n",
+      "# Instance with which to call the /ds-graph routes\n",
+      "ds_graph_api_instance = ds_graph_api.DsGraphApi(api_client)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Aggregate statistics\n",
+      "To get a quick idea of what data is available in the HRA API, you can use the `aggregate_results` method. With no options, it returns various counts for all default (federated) data."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "api_response = api_instance.aggregate_results()\n",
+      "for x in api_response:\n",
+      "  print(x.count, x.label)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Get a session token for HuBMAP data\n",
+      "You can limit to certain sets of data by creating a session token. We will create a session for just HuBMAP data. Filters, discussed later, can also be used here to make a smaller set of data for more targeted studies.\n"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Session configuration. You can add your HuBMAP token after ?token= to get private data\n",
+      "session_configuration = { \"dataSources\": [\"https://apps.humanatlas.io/api/ds-graph/hubmap?token=\"] }\n",
+      "\n",
+      "# Get a session token for this configuration\n",
+      "api_response = api_instance.session_token(session_configuration)\n",
+      "token=api_response.token\n",
+      "print(token)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "After we get the session token, we wait to make sure the session is ready."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "db_ready = False\n",
+      "while not db_ready:\n",
+      "    api_response = api_instance.db_status(token)\n",
+      "    print(api_response)\n",
+      "    if api_response.status == 'Ready':\n",
+      "        db_ready = True\n",
+      "    else:\n",
+      "        print('Database not ready yet! Retrying...')\n",
+      "        time.sleep(2)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Examine the HuBMAP data\n",
+      "Now we can check the data available in the session we created"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# get aggregate statistics\n",
+      "api_response = api_instance.aggregate_results(token=token)\n",
+      "for x in api_response:\n",
+      "  print(x.count, x.label)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "Let's get all of the tissue blocks (with a RUI location) in HuBMAP"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# get all tissue blocks\n",
+      "api_response = api_instance.tissue_blocks(token=token)\n",
+      "\n",
+      "# print first five block links\n",
+      "for x in api_response[0:5]:\n",
+      "  print(x.link)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Filter the HuBMAP data"
+    ]
+  },
+  {
+    "attachments": {},
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "Certain parameters can be used to filter the data. Most methods that query the data have these filters to use:\n",
+      "<pre>\n",
+      "    age - (MinMax) (optional) (min = 1.0; max = 110.0)\n",
+      "    bmi - (MinMax) (optional) (min = 13.0; max = 83.0)\n",
+      "    sex - (string)  (optional) (male, female, both)\n",
+      "    technologies - (string) (optional) (List of technologies - api_instance.technology_names)\n",
+      "    providers - (string) (optional) \n",
+      "    ontology_terms - (string) (optional) (List of ontology terms)\n",
+      "    cell_type_terms - (string) (optional) (List of ontology tems)\n",
+      "    spatial - SpatialSearch(x, y, z, radius, target) (optional) \n",
+      "    token - (string) (optional) the session token, if not provided it will use the default dataset\n",
+      "</pre>\n",
+      "\n",
+      "Example instantantiations of the filters are below."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "age = MinMax(min=45.0, max=60.0)\n",
+      "bmi = MinMax(min=65.0, max=83.0)\n",
+      "sex = \"Female\"\n",
+      "technologies = []\n",
+      "providers = []\n",
+      "ontology_terms = [\"http://purl.obolibrary.org/obo/UBERON_0000955\",]\n",
+      "cell_type_terms = [\"http://purl.obolibrary.org/obo/CL_0000000\",] \n",
+      "spatial = [SpatialSearch(\n",
+      "            x=84.0,\n",
+      "            y=146.0,\n",
+      "            z=53.0,\n",
+      "            radius=12.0,\n",
+      "            target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
+      "        ),]\n",
+      "\n",
+      "# get filtered aggregate statistics\n",
+      "api_response = api_instance.aggregate_results(\n",
+      "                    age=age,\n",
+      "                    bmi=bmi, \n",
+      "                    ontology_terms=ontology_terms,\n",
+      "                    cell_type_terms=cell_type_terms, \n",
+      "                    providers=providers,\n",
+      "                    sex=sex,\n",
+      "                    spatial=spatial,\n",
+      "                    technologies=technologies,\n",
+      "                    token=token)\n",
+      "for x in api_response:\n",
+      "  print(x.count, x.label)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "Another way to manage these filters is to create a Dictionary and use python's `**kwargs` syntax to create and pass around a filter object. We'll use this filter object for several methods below."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "filter = {\n",
+      "  \"age\": MinMax(min=45.0, max=60.0),\n",
+      "  \"bmi\": MinMax(min=65.0, max=83.0),\n",
+      "  \"sex\": \"Female\",\n",
+      "  \"technologies\": [],\n",
+      "  \"providers\": [],\n",
+      "  \"ontology_terms\": [\"http://purl.obolibrary.org/obo/UBERON_0000955\"],\n",
+      "  \"cell_type_terms\": [\"http://purl.obolibrary.org/obo/CL_0000000\"],\n",
+      "  \"spatial\": [\n",
+      "    SpatialSearch(\n",
+      "      x=84.0,\n",
+      "      y=146.0,\n",
+      "      z=53.0,\n",
+      "      radius=12.0,\n",
+      "      target=\"https://purl.humanatlas.io/ref-organ/brain-female#primary\"\n",
+      "    )\n",
+      "  ]\n",
+      "}\n",
+      "\n",
+      "# get filtered aggregate statistics\n",
+      "api_response = api_instance.aggregate_results(token=token, **filter)\n",
+      "for x in api_response:\n",
+      "  print(x.count, x.label)"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# get anatomical structures that the tissue blocks collided with\n",
+      "api_response = api_instance.ontology_term_occurences(token=token, **filter)\n",
+      "\n",
+      "# Print the first 5 results\n",
+      "for (anatomical_structure, count) in list(api_response.items())[0:5]:\n",
+      "  print(anatomical_structure, count)"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# get cell types located in anatomical structures that the tissue blocks collided with\n",
+      "api_response = api_instance.cell_type_term_occurences(token=token, **filter)\n",
+      "\n",
+      "# Print the first 5 results\n",
+      "for (cell_type, count) in list(api_response.items())[0:5]:\n",
+      "  print(cell_type, count)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Query the HRA Knowledge Graph with SPARQL\n",
+      "The HRA API provides a SPARQL endpoint to query the HRA knowledge graph. This allows you to select out very specific data using advanced SPARQL querying. \n",
+      "\n",
+      "To demonstrate, let's get all the anatomical structures in the latest HRA release."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "query = '''\n",
+      "PREFIX ccf: <http://purl.org/ccf/>\n",
+      "SELECT ?as ?label\n",
+      "FROM <https://purl.humanatlas.io/collection/hra>\n",
+      "WHERE {\n",
+      "  ?as ccf:ccf_asctb_type ?type ;\n",
+      "    ccf:ccf_pref_label ?label .\n",
+      "  FILTER(?type = 'AS')\n",
+      "}\n",
+      "'''\n",
+      "api_response = api_instance.sparql(query=query)\n",
+      "rows = api_response['results']['bindings']\n",
+      "\n",
+      "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
+      "\n",
+      "# Print the first 5 results\n",
+      "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
+      "  print(anatomical_structure, label)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "If your SPARQL query is longer (thousands of characters), you can do a SPARQL POST which allows for sending more data."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "api_response = api_instance.sparql_post({'query': query})\n",
+      "rows = api_response['results']['bindings']\n",
+      "\n",
+      "as_lookup = dict([ (row['as']['value'], row['label']['value']) for row in rows ])\n",
+      "\n",
+      "# Print the first 5 results\n",
+      "for (anatomical_structure, label) in list(as_lookup.items())[0:5]:\n",
+      "  print(anatomical_structure, label)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Working with extraction sites (aka RUI locations)\n",
+      "After obtaining an extraction site either via the RUI or from queries like above, there are a few things you can do with this data."
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Generate a 3D corridor\n",
+      "\n",
+      "We can compute a corridor from any extraction site. A corridor shows where else an extraction site could go in the same organ and still maintain the same overlaps with anatomical structures. We will take an example extraction site and see what it's corridor looks like."
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "An example extraction site:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Provide a RUI location via the RUI at https://apps.humanatlas.io/rui/\n",
+      "extraction_site = {\n",
+      "    \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "    \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5\",\n",
+      "    \"@type\": \"SpatialEntity\",\n",
+      "    \"creator\": \"demo demo\",\n",
+      "    \"creator_first_name\": \"demo\",\n",
+      "    \"creator_last_name\": \"demo\",\n",
+      "    \"creation_date\": \"2024-08-20\",\n",
+      "    \"ccf_annotations\": [\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002015\",\n",
+      "        \"http://purl.obolibrary.org/obo/UBERON_0002189\"\n",
+      "    ],\n",
+      "    \"x_dimension\": 10,\n",
+      "    \"y_dimension\": 10,\n",
+      "    \"z_dimension\": 10,\n",
+      "    \"dimension_units\": \"millimeter\",\n",
+      "    \"placement\": {\n",
+      "        \"@context\": \"https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld\",\n",
+      "        \"@id\": \"http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement\",\n",
+      "        \"@type\": \"SpatialPlacement\",\n",
+      "        \"target\": \"https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary\",\n",
+      "        \"placement_date\": \"2024-08-20\",\n",
+      "        \"x_scaling\": 1,\n",
+      "        \"y_scaling\": 1,\n",
+      "        \"z_scaling\": 1,\n",
+      "        \"scaling_units\": \"ratio\",\n",
+      "        \"x_rotation\": 0,\n",
+      "        \"y_rotation\": 0,\n",
+      "        \"z_rotation\": 0,\n",
+      "        \"rotation_order\": \"XYZ\",\n",
+      "        \"rotation_units\": \"degree\",\n",
+      "        \"x_translation\": 72.366,\n",
+      "        \"y_translation\": 79.067,\n",
+      "        \"z_translation\": 34.77,\n",
+      "        \"translation_units\": \"millimeter\"\n",
+      "    }\n",
+      "}"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Generate a corridor for the extraction site\n",
+      "model = api_instance.corridor(extraction_site)\n",
+      "\n",
+      "# Display it in 3D\n",
+      "viewer = ModelViewer(data=model)\n",
+      "display(viewer)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Find anatomical structure collisions for an extraction site\n",
+      "For any extraction site, we can analyze what anatomical structures it collides with in the 3D reference organ and by how much."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Get mesh-based collisions\n",
+      "collisions = api_instance.collisions(extraction_site)\n",
+      "\n",
+      "pprint(collisions[0:5])"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Conclusion\n",
+      "This concludes this tutorial. Refer to the usage notebook [here](https://github.com/x-atlas-consortia/hra-api/blob/main/notebooks/hra-api-client-usage.ipynb) and to the API documentation on <https://apps.humanatlas.io/api/> for additional documentation, methods, and examples. If you have any issues, problems, or questions, feel free to file an issue on the HRA API GitHub at <https://github.com/x-atlas-consortia/hra-api>."
+    ]
+  }
+]
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
index f445872..90eeaeb 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/template.txt
@@ -1,223 +1,200 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## HRA UI Jupyter Widgets Usage\n",
-        "This notebook shows how to use the different widgets provided by the `hra-jupyter-widgets` package."
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Install package\n",
-        "For this notebook, we'll install the `hra-jupyter-widgets` and `ipywidgets` for displaying the widgets."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "%pip install hra-jupyter-widgets ipywidgets"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Imports"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "We import the Jupyter Widgets as follows:"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 17,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "from hra_jupyter_widgets import (\n",
-        "    EuiOrganInformation,\n",
-        "    FtuExplorerSmall,\n",
-        "    MedicalIllustration,\n",
-        "    ModelViewer\n",
-        ")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "For the purposes of this demonstration we need some other libraries imported here: "
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 18,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import ipywidgets as widgets"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Configure organ and illustration to use\n",
-        "Other options are available, but we will focus on Kidney and the renal corpuscle FTU in the widgets below."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 19,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Kidney uberon id\n",
-        "organ = \"http://purl.obolibrary.org/obo/UBERON_0002113\"\n",
-        "illustration = \"https://purl.humanatlas.io/2d-ftu/kidney-renal-corpuscle\""
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## Full example with FTU"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Create and use a medical illustration widget\n",
-        "Let's display a medical illustration of the kidney corpuscle."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "medical_illustration = MedicalIllustration(selected_illustration=illustration)\n",
-        "display(medical_illustration)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "We can listen to interaction events in the medical illustration and output them below."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Create an output widget\n",
-        "output = widgets.Output()\n",
-        "\n",
-        "# Create an event listener that prints to the output widget\n",
-        "# It takes a single argument - the event data\n",
-        "def cell_click(cell):\n",
-        "    with output:\n",
-        "        print(f\"Cell clicked: '{cell['label']}'\")\n",
-        "\n",
-        "# Register the listener\n",
-        "medical_illustration.on_cell_click(cell_click)\n",
-        "\n",
-        "# Listeners can be removed by calling on_cell_click with remove=True, i.e.\n",
-        "# medical_illustration.on_cell_click(cell_click, remove=True)\n",
-        "\n",
-        "display(output)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## Organ Information Widget\n",
-        "Let's create an organ information widget for the Kidney to see all data registered there."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "organ_info = EuiOrganInformation(organ_iri=organ)\n",
-        "display(organ_info)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## FTU explorer\n",
-        "Let's make an FTU explorer instance that shows the renal corpuscle by default."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "ftu_explorer_small = FtuExplorerSmall(selected_illustration=illustration)\n",
-        "display(ftu_explorer_small)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 3D Model Viewer\n",
-        "We have integrated Google's Model Viewer web component here as a jupyter widget. You can use it to view 3D models using the GLB format."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "model_viewer = ModelViewer(url=\"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\")\n",
-        "display(model_viewer)"
-      ]
-    }
-  ],
-  "metadata": {
-    "kernelspec": {
-      "display_name": ".venv",
-      "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.12"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 2
-}
+[
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## HRA UI Jupyter Widgets Usage\n",
+      "This notebook shows how to use the different widgets provided by the `hra-jupyter-widgets` package."
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Install package\n",
+      "For this notebook, we'll install the `hra-jupyter-widgets` and `ipywidgets` for displaying the widgets."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "%pip install hra-jupyter-widgets ipywidgets"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Imports"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "We import the Jupyter Widgets as follows:"
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "from hra_jupyter_widgets import (\n",
+      "    EuiOrganInformation,\n",
+      "    FtuExplorerSmall,\n",
+      "    MedicalIllustration,\n",
+      "    ModelViewer\n",
+      ")"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "For the purposes of this demonstration we need some other libraries imported here: "
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "import ipywidgets as widgets"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Configure organ and illustration to use\n",
+      "Other options are available, but we will focus on Kidney and the renal corpuscle FTU in the widgets below."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Kidney uberon id\n",
+      "organ = \"http://purl.obolibrary.org/obo/UBERON_0002113\"\n",
+      "illustration = \"https://purl.humanatlas.io/2d-ftu/kidney-renal-corpuscle\""
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Full example with FTU"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "### Create and use a medical illustration widget\n",
+      "Let's display a medical illustration of the kidney corpuscle."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "medical_illustration = MedicalIllustration(selected_illustration=illustration)\n",
+      "display(medical_illustration)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "We can listen to interaction events in the medical illustration and output them below."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "# Create an output widget\n",
+      "output = widgets.Output()\n",
+      "\n",
+      "# Create an event listener that prints to the output widget\n",
+      "# It takes a single argument - the event data\n",
+      "def cell_click(cell):\n",
+      "    with output:\n",
+      "        print(f\"Cell clicked: '{cell['label']}'\")\n",
+      "\n",
+      "# Register the listener\n",
+      "medical_illustration.on_cell_click(cell_click)\n",
+      "\n",
+      "# Listeners can be removed by calling on_cell_click with remove=True, i.e.\n",
+      "# medical_illustration.on_cell_click(cell_click, remove=True)\n",
+      "\n",
+      "display(output)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## Organ Information Widget\n",
+      "Let's create an organ information widget for the Kidney to see all data registered there."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "organ_info = EuiOrganInformation(organ_iri=organ)\n",
+      "display(organ_info)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## FTU explorer\n",
+      "Let's make an FTU explorer instance that shows the renal corpuscle by default."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "ftu_explorer_small = FtuExplorerSmall(selected_illustration=illustration)\n",
+      "display(ftu_explorer_small)"
+    ]
+  },
+  {
+    "cell_type": "markdown",
+    "metadata": {},
+    "source": [
+      "## 3D Model Viewer\n",
+      "We have integrated Google's Model Viewer web component here as a jupyter widget. You can use it to view 3D models using the GLB format."
+    ]
+  },
+  {
+    "cell_type": "code",
+    "execution_count": null,
+    "metadata": {},
+    "outputs": [],
+    "source": [
+      "model_viewer = ModelViewer(url=\"https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb\")\n",
+      "display(model_viewer)"
+    ]
+  }
+]

From 971e2118f1e592b6f43c84983b506eac03616fd7 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 09:50:34 -0400
Subject: [PATCH 13/27] remove examples for hra

---
 .../jupyter_lab/templates/hra_api_tutorial/metadata.json   | 7 -------
 .../templates/hra_ui_widgets_tutorial/metadata.json        | 7 -------
 2 files changed, 14 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
index 0d2feea..57cbd7a 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_api_tutorial/metadata.json
@@ -7,13 +7,6 @@
   ],
   "is_multi_dataset_template": true,
   "template_format": "jinja",
-  "examples": [
-    {
-      "title": "Working with the HRA API examples",
-      "description": "Retrieve aggregate statistics, query and filter and examine extraction sites.",
-      "datasets": []
-    }
-  ],
   "is_hidden": false,
   "last_modified_unix_timestamp": 1723749414
 }
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
index c5e1c63..0013af2 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/hra_ui_widgets_tutorial/metadata.json
@@ -7,13 +7,6 @@
   ],
   "is_multi_dataset_template": true,
   "template_format": "jinja",
-  "examples": [
-    {
-      "title": "Working with the HRA UI Jupyter Widgets",
-      "description": "Examine the organ widget, FTU explorer, and 3D model viewer.",
-      "datasets": []
-    }
-  ],
   "is_hidden": false,
   "last_modified_unix_timestamp": 1723749414
 }

From 8ceb83cc711216e3c206a60b85ed478f9c3cc538 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 14:52:00 -0400
Subject: [PATCH 14/27] add hra and sc tags

---
 src/tags.json | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/tags.json b/src/tags.json
index 5ca1e15..bcf38b9 100644
--- a/src/tags.json
+++ b/src/tags.json
@@ -9,5 +9,7 @@
   "salmon": "Spatial data analysed with Salmon",
   "codex": "CODEX data",
   "slide-seq": "Slide-seq data",
-  "files": "Work with HuBMAP data files"
+  "files": "Work with HuBMAP data files",
+  "hra": "Human Reference Atlas data",
+  "sc": "Single cell analysis"
 }
\ No newline at end of file

From 4c6584219512c24753e9fa68beb1b0e4189070a0 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 14:55:24 -0400
Subject: [PATCH 15/27] add id to convert notebook helper

---
 .../jupyter_lab/utils/convert-templates/convert-notebook.py     | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py b/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
index 1db62fe..73cf296 100644
--- a/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
+++ b/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
@@ -92,6 +92,8 @@ def notebookToTxt(file_folder):
             text_txt_list[i] = '   "execution_count": null,\n'
         if '"outputs":' in text_txt_list[i]:
             text_txt_list[i] = '   "outputs": [],\n'
+        if '"id":' in text_txt_list[i]:
+            text_txt_list[i] = ''
 
     # write to txt
     with open(file_name_txt, "w") as file:

From 5baac420459c6ed3b36e2fbe087d1e5967d9ab9c Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 14:58:40 -0400
Subject: [PATCH 16/27] add interpunction and update readme to add that
 datasets should be public and published

---
 .../templates/jupyter_lab/templates/blank_r/metadata.json       | 2 +-
 .../jupyter_lab/templates/codex_clustering/metadata.json        | 2 +-
 .../templates/jupyter_lab/templates/load_zarr/metadata.json     | 2 +-
 .../templates/jupyter_lab/templates/new_template/README.md      | 2 +-
 .../templates/jupyter_lab/templates/new_template/metadata.json  | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
index 416574b..c63dd16 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/blank_r/metadata.json
@@ -1,6 +1,6 @@
 {
   "title": "Blank Notebook",
-  "description": "Notebook only inserting UUIDs of added datasets",
+  "description": "Notebook only inserting UUIDs of added datasets.",
   "tags": [
   ], 
   "is_multi_dataset_template": true,
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/codex_clustering/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/codex_clustering/metadata.json
index be26cc8..284a0c5 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/codex_clustering/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/codex_clustering/metadata.json
@@ -1,6 +1,6 @@
 {
     "title": "Cluster SPRM output of CODEX data and visualize with Vitessce",
-    "description": "This template shows how to cluster CODEX data and load a new clustering into Vitessce",
+    "description": "This template shows how to cluster CODEX data and load a new clustering into Vitessce.",
     "tags": [
         "codex",
         "visualization", 
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/load_zarr/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/load_zarr/metadata.json
index 84414a8..b9bd699 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/load_zarr/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/load_zarr/metadata.json
@@ -1,6 +1,6 @@
 {
     "title": "Retrieve anndata from remote zarr storage",
-    "description": "This template shows how to work with the remote zarr stores for anndata in the HuBMAP Data Portal",
+    "description": "This template shows how to work with the remote zarr stores for anndata in the HuBMAP Data Portal.",
     "tags": [
         "zarr",
         "anndata"
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/new_template/README.md b/src/user_templates_api/templates/jupyter_lab/templates/new_template/README.md
index 17dec22..69f0ecd 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/new_template/README.md
+++ b/src/user_templates_api/templates/jupyter_lab/templates/new_template/README.md
@@ -20,7 +20,7 @@ The metadata.json is used to display the templates in the HuBMAP Data Portal. It
 - `tags`: a list of tags to describe the notebook. Potential tags can be found [here](https://github.com/hubmapconsortium/user-templates-api/tree/development/src/tags.json). New tags can be added if necessary. 
 - `is_multi_dataset_template`: boolean describing whether template can handle more than 1 dataset.
 - `template_format`: one of `python`/`json`/`jinja`. We recommend using `jinja`, and describe the insertion of cells for jinja below.
-- `examples`: array with examples that are shown in the template example pages. Each example has a `title` (string), a `description` (string), and `datasets` (array of strings). Optionally, it also has an `assay_display_name` (array) with the possible assay_display_names, and `required_filetypes` (array) with required filetypes.
+- `examples`: array with examples that are shown in the template example pages. Each example has a `title` (string), a `description` (string), and `datasets` (array of strings). These datasets are a list of uuids of [public, published datasets on the HuBMAP Data Portal](https://portal.hubmapconsortium.org/search?mapped_status_keyword-mapped_data_access_level_keyword[Published][0]=Public&entity_type[0]=Dataset). Optionally, it also has an `assay_display_name` (array) with the possible assay_display_names, and `required_filetypes` (array) with required filetypes.
 - `is_hidden`: Any template with this field set to `true` is not shown in the Portal.
 - `last_modified_unix_timestamp`: Don't set this, it is added automatically to keep track of changes.
 
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/new_template/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/new_template/metadata.json
index f7fcd30..3b9ed27 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/new_template/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/new_template/metadata.json
@@ -1,6 +1,6 @@
 {
   "title": "A descriptive title",
-  "description": "A description of the notebook",
+  "description": "A description of the notebook.",
   "tags": [
     "anndata",
     "visualization"

From 1b4b8d87a4007b5827eb15b778a653a2d415046d Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 15:00:29 -0400
Subject: [PATCH 17/27] add scfind template

---
 .../jupyter_lab/templates/scfind/README.md    |   0
 .../templates/scfind/metadata.json            |  18 +
 .../jupyter_lab/templates/scfind/render.py    |   6 +
 .../jupyter_lab/templates/scfind/template.txt | 470 ++++++++++++++++++
 4 files changed, 494 insertions(+)
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/scfind/README.md
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/scfind/render.py
 create mode 100644 src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/README.md b/src/user_templates_api/templates/jupyter_lab/templates/scfind/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
new file mode 100644
index 0000000..e5990ca
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
@@ -0,0 +1,18 @@
+{
+  "title": "Index and search single cell data with scfind",
+  "description": "This notebook shows how to do fast searches of large collections of single cell data with scfind.",
+  "tags": [
+    "anndata",
+    "sc"
+  ], 
+  "is_multi_dataset_template": true,
+  "template_format": "jinja",
+  "examples": [
+    {
+      "title": "Examine kidney datasets with scfind.",
+      "description": "Build an index for two groups of kidney datasets and examine genes and cells.",
+      "datasets": ["e7bdf34c4da9f1d880f2615226e9713d", "254801a318687281ba3e473569d89a45", "044b28971204366347e7ed0b7ef0c279", "4b5dc6d04aa30a6eb0b224a7ab7d03b3", "c14b104f9e44511ddf82697bce0d1901", "2639e9e8488edddde275491cdbaae662"]
+    }
+  ],
+  "is_hidden": true
+}
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/render.py b/src/user_templates_api/templates/jupyter_lab/templates/scfind/render.py
new file mode 100644
index 0000000..7fec3bd
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/render.py
@@ -0,0 +1,6 @@
+from user_templates_api.templates.jupyter_lab.render import JupyterLabRender
+
+
+class JupyterLabExampleJinjaRender(JupyterLabRender):
+    def __init__(self):
+        pass
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
new file mode 100644
index 0000000..e939203
--- /dev/null
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
@@ -0,0 +1,470 @@
+[
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Index and search single cell data with scfind\n",
+    "\n",
+    "> We recommend increasing the memory on the workspace settings as building the scfind index can be quite memory-consuming.\n",
+    "\n",
+    "This notebook shows how to do fast searches of large collections of single cell data with scfind.\n",
+    "scfind is an advanced single-cell analysis tool that facilitates fast search of biologically relevant marker genes in cell atlases. Utilizing an efficient compression strategy for sparse single-cell measurements, scfind builds a compact index to store the expression matrix, enabling fast queries at single-cell resolution. The central operation carried out by scfind is to identify the set of cells expressing user-specified gene combinations. This functionality supports multiple analytical applications, including marker gene identification and evaluation, in silico gating, and identifying both cell-type-specific and housekeeping genes. Furthermore, scfind incorporates a subquery optimization routine, ensuring that long and complex queries return biologically meaningful results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "!pip install pybind11 numpy==1.24.4 pandas scipy==1.10.1 anndata==0.9.2 gensim==4.3.2 statsmodels tqdm python-Levenshtein smart_open h5py requests hubmap-template-helper\n",
+    "!pip install -i https://test.pypi.org/simple/ scfind==2.3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import requests\n",
+    "import json\n",
+    "import warnings\n",
+    "import os\n",
+    "import math\n",
+    "\n",
+    "import anndata as ad\n",
+    "\n",
+    "import scfind\n",
+    "\n",
+    "from hubmap_template_helper import compatibility as hth_comp"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Linked datasets\n",
+    "The following datasets were symlinked to the workspace when this template was added:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# linked datasets\n",
+    "uuids = ['e7bdf34c4da9f1d880f2615226e9713d', '254801a318687281ba3e473569d89a45', '044b28971204366347e7ed0b7ef0c279', '4b5dc6d04aa30a6eb0b224a7ab7d03b3', 'c14b104f9e44511ddf82697bce0d1901', '2639e9e8488edddde275491cdbaae662', 'ccbad4ffd323265937b842ea36ada4ad', '0804a7a9e430e6adfbc56f339d787211']\n",
+    "\n",
+    "# accepted data_types\n",
+    "accepted_assay_display_names = [\"snRNAseq (SNAREseq2) [Salmon]\"]\n",
+    "\n",
+    "# search_api\n",
+    "search_api = 'https://search.api.hubmapconsortium.org/v3/portal/search'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following checks if the datasets are compatible with this template."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uuids = hth_comp.check_template_compatibility(uuids, accepted_assay_display_names=accepted_assay_display_names, search_api=search_api)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uuids"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Groupings\n",
+    "This notebook shows how to create two groupings and perform scfind on both."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For this we need at least two datasets."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if len(uuids) < 2: \n",
+    "    warnings.warn(\"Not enough datasets to run this analysis\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As an example, we will split the datasets into two groupings based on when they were published. Of course this can be changed to something more biologically meaningful."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hits = json.loads(\n",
+    "    requests.post(\n",
+    "        search_api,\n",
+    "        json={\n",
+    "            \"size\": 10000,  # To make sure the list is not truncted, set this high.\n",
+    "            \"query\": {\"ids\": {\"values\": uuids}},\n",
+    "        },\n",
+    "    ).text\n",
+    ")[\"hits\"][\"hits\"]\n",
+    "\n",
+    "list_ids_published = []\n",
+    "for hit in hits:\n",
+    "    list_ids_published.append([hit[\"_id\"], hit[\"_source\"][\"published_timestamp\"]])\n",
+    "list_ids_published.sort(key = lambda x: x[1])\n",
+    "\n",
+    "half = math.ceil(len(list_ids_published)/2)\n",
+    "\n",
+    "uuids_group_1 = [id[0] for id in list_ids_published[0:half]]\n",
+    "uuids_group_2 = [id[0] for id in list_ids_published[half:]]\n",
+    "\n",
+    "print(f\"Group 1: {uuids_group_1}\")\n",
+    "print(f\"Group 2: {uuids_group_2}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Reading in data and preprocessing, building scfind index\n",
+    "The initial step involves reading the anndata of the datasets of interest.\n",
+    "\n",
+    "Building the scfind index requires one or more nonnegative matrices as input. In these matrices, columns represent genes, peaks, or other features that serve as query terms, while rows represent individual cells. While there are no strict normalization requirements, a sparse matrix structure is advantageous for efficient processing.\n",
+    "\n",
+    "This example utilizes an annotated AnnData object loaded from _secondary_analysis.h5ad_, with cell annotations stored in AnnData.obs and feature names stored in AnnData.var. During index construction, a dataset_name parameter can be provided. This allows for differentiation of cell types from various datasets, potentially representing organ/tissue names, donor IDs, experimental conditions, or any other meaningful identifiers to distinguish cell groups from different datasets. In this example, we add the groupings based on the time of publishing as created above. Following this step, queries can be specified within the datasets of interest.\n",
+    "\n",
+    "The index building process begins with the initialization of the scfind object and building index using a single AnnData object. Subsequently, any remaining AnnData objects are merged into the existing index. This approach conserves memory when multiple large datasets are loaded. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "## Build scfind index for datasets for both groups\n",
+    "\n",
+    "cell_type_label = 'predicted_label'\n",
+    "feature_name = 'hugo_symbol'\n",
+    "layer_to_use = 'spliced'\n",
+    "\n",
+    "# initializing scfind object\n",
+    "scfind_index = scfind.SCFind()\n",
+    "\n",
+    "for i, uuid in enumerate(uuids):\n",
+    "    print(f\"Building index for dataset {i}: {uuid}.\")\n",
+    "\n",
+    "    # check which group this belongs to\n",
+    "    \n",
+    "    group = \"group-1\" if uuid in uuids_group_1 else \"group-2\"  \n",
+    "    print(f\"Dataset is part of group: {group}\")\n",
+    "    \n",
+    "    # read in data and preprocess\n",
+    "    adata = ad.read_h5ad(os.path.join('datasets', uuid, 'secondary_analysis.h5ad'))\n",
+    "    valid_genes = adata.var[feature_name].dropna().drop_duplicates()\n",
+    "    adata = adata[:, list(valid_genes.index)]\n",
+    "    adata = ad.AnnData(X=adata.layers[layer_to_use], obs=adata.obs, var=adata.var)\n",
+    "\n",
+    "    # create index\n",
+    "    # if this is the first dataset, we will add it to our intilized index\n",
+    "    if i == 0:\n",
+    "        scfind_index.buildCellTypeIndex(\n",
+    "            adata=adata, \n",
+    "            dataset_name=group,\n",
+    "            feature_name=feature_name,\n",
+    "            cell_type_label=cell_type_label\n",
+    "        )\n",
+    "\n",
+    "    # if this is not the first dataset, we will set it to a new scfind index, and merge it to our existing index\n",
+    "    else:\n",
+    "        scfind_index_new = scfind.SCFind()\n",
+    "        scfind_index_new.buildCellTypeIndex(\n",
+    "            adata=adata,\n",
+    "            dataset_name=group,\n",
+    "            feature_name=feature_name,\n",
+    "            cell_type_label=cell_type_label,\n",
+    "        )\n",
+    "        scfind_index.mergeDataset(scfind_index_new)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Index can be saved and reloaded for future use"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# save index \n",
+    "scfind_index.saveObject(\"scfind_index.bin\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Reload index \n",
+    "scfind_index = scfind.SCFind()\n",
+    "scfind_index.loadObject(\"scfind_index.bin\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now with the scfind index we can check the basic information, e.g., genes, cell types, and datasets contained in scfind index."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"Number of genes in index: {len(scfind_index.scfindGenes)}\")\n",
+    "print(scfind_index.scfindGenes[:10])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"Number of datasets: {len(scfind_index.datasets)}\")\n",
+    "print(scfind_index.datasets)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "datasets = [d for ds in scfind_index.datasets_map.values() for d in ds]\n",
+    "print(f\"Total number of cell in index: {scfind_index.index.getTotalCells(datasets)}\")\n",
+    "print(f\"Total number of cell types in index: {len(scfind_index.cellTypeNames())}\")\n",
+    "print(f\"{scfind_index.cellTypeNames()[0:6]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Use scfind index for fast query\n",
+    "\n",
+    "The central operation of scfind is to identify the set of cells that express a set of genes (query) specified by the user. With the basic operation scfind can be used to identify and evaluate marker genes, perform in silico gating and identify both cell-type-specific and housekeeping genes."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Identify cell type markers with index.cellTypeMarkers\n",
+    "The index.cellTypeMarkers function identifies marker genes for cell types of interest compared to specified background cell types. For each gene, four key metrics are defined:\n",
+    "1. tp (true positive): Number of cells with non-zero expression values of a specific gene in the given cell types.\n",
+    "2. fp (false positive): Number of cells with non-zero expression values of the gene outside the given cell types.\n",
+    "3. fn (false negative): Number of cells with zero expression values of the gene in the given cell types.\n",
+    "4. tn (true negative): Number of cells with zero expression values outside the given cell types (not shown in results table).\n",
+    "\n",
+    "Based on these metrics, scfind computes the following:\n",
+    "Precision = tp / (tp + fp)\n",
+    "Recall = tp / (tp + fn)\n",
+    "F1 score = 2 * (precision * recall) / (precision + recall)\n",
+    "\n",
+    "A higher F1 score indicates that the gene is more exclusively expressed in the cell types of interest. This measure provides a balanced assessment of a gene's specificity and sensitivity as a marker for the given cell types."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ct = scfind_index.cellTypeNames()[0]\n",
+    "bg_cts = scfind_index.cellTypeNames()[0:5]\n",
+    "scfind_index.cellTypeMarkers(cell_types=ct, background_cell_types = bg_cts, top_k=10) "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If background cell types are not specified, all cell types in index would be used as background."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "scfind_index.cellTypeMarkers(cell_types=ct)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Evaluate cell type markers with index.evaluateMarkers\n",
+    "The index.evaluateMarkers function assesses user-specified genes in designated cell type(s) of interest against background cell types. This evaluation employs the same metrics utilized in the index.cellTypeMarkers method, to evaluate the specified genes as markers for the cell types of interest.\n",
+    "\n",
+    "Upon evaluation of gene expression in T cell populations, the T cell-associated markers CCR7, CD4, and CD27 exhibites higher F1 scores compared to the epithelial-associated markers KRT18, CDH1, and CLDN3."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "genes = ['KRT18', 'CDH1', 'CLDN3', 'CCR7', 'CD4', 'CD27']\n",
+    "ct = 'group-1.T cell'\n",
+    "scfind_index.evaluateMarkers(gene_list=genes, cell_types=ct, background_cell_types=bg_cts)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Significant enrichment analysis of a list of genes by index.hyperQueryCellTypes\n",
+    "Scfind also supports hypergeometric test to identify the cell types that a query of interest is significantly enriched in. The output counts the number of cells expressing all genes in query (cell_hits) in each cell type and total number of cells in the cell type, as well as the p values by hypergeometric test and modified by multiple testing correction."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# scfind identifies the B cells with marker genes successfully\n",
+    "genes = ['PLEK', 'PRKCB']\n",
+    "datasets = scfind_index.datasets[0]\n",
+    "scfind_index.hyperQueryCellTypes(gene_list=genes, datasets=datasets)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The hyperQueryCellTypes method supports in silico gating, allowing the use of operators to refine the query:\n",
+    "\n",
+    "-gene: Exclude cells expressing \"gene.\"\n",
+    "*gene: Include cells if either \"gene\" is expressed.\n",
+    "*-gene: Exclude cells if either \"gene\" is expressed.\n",
+    "\n",
+    "For example, if we are interested in cell types that significantly express HLA-DRA and CD38, but not IGHA1, the input query would be: ['HLA-DRA', 'CD38', '-IGHA1']."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "genes = ['HLA-DRA', 'CD38', '-IGHA1']\n",
+    "datasets = scfind_index.datasets[0]\n",
+    "scfind_index.hyperQueryCellTypes(gene_list=genes, datasets=datasets)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Query optimization for long queries (>5) with index.markerGenes\n",
+    "For queries involving even a moderate number (>5) of terms for sparsely sequenced datasets, it is likely that an empty set of cells will be returned. To ensure that meaningful results are returned without requiring the user to manually modify the query, scfind features a query optimization routine to identify subqueries that are guaranteed to return nonempty sets of cells.\n",
+    "\n",
+    "The output of index.markerGenes consists of subqueries, and a score measuring the importance of the subqueries to given datasets, as well as the number of cells with non-zero values of each subquery."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "genes = scfind_index.scfindGenes[0:10]\n",
+    "scfind_index.markerGenes(gene_list=genes)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Identification of housekeeping genes by index.findHouseKeepingGenes\n",
+    "Of particular interest are those genes expressed across most or all cell types, also known as housekeeping genes. scfind supports the identification of housekeeping genes for given cell types."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# scfind allows to identify the cell-type-specific genes and housekeeping genes across cell types.\n",
+    "cts = scfind_index.cellTypeNames()[0:3]\n",
+    "scfind_index.findHouseKeepingGenes(cell_types=cts, )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Retrieve of gene expression data by index.getCellTypeExpression\n",
+    "scfind also approximates the original non-zero expression values by quantized expressione values. Given a cell type of interest, The quantized expression data would be returned in AnnData object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "ct = scfind_index.cellTypeNames()[0]\n",
+    "adata = scfind_index.getCellTypeExpression(cell_type=ct)\n",
+    "adata"
+   ]
+  }
+ ]

From fcee34dbf6f888d84127c84c7148d58674037645 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Tue, 17 Sep 2024 15:01:51 -0400
Subject: [PATCH 18/27] add uuid insertion

---
 .../templates/jupyter_lab/templates/scfind/template.txt       | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
index e939203..7105697 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
@@ -57,9 +57,9 @@
    "outputs": [],
    "source": [
     "# linked datasets\n",
-    "uuids = ['e7bdf34c4da9f1d880f2615226e9713d', '254801a318687281ba3e473569d89a45', '044b28971204366347e7ed0b7ef0c279', '4b5dc6d04aa30a6eb0b224a7ab7d03b3', 'c14b104f9e44511ddf82697bce0d1901', '2639e9e8488edddde275491cdbaae662', 'ccbad4ffd323265937b842ea36ada4ad', '0804a7a9e430e6adfbc56f339d787211']\n",
+    "uuids = {{ uuids | safe }}\n",
     "\n",
-    "# accepted data_types\n",
+    "# accepted assay_display_names\n",
     "accepted_assay_display_names = [\"snRNAseq (SNAREseq2) [Salmon]\"]\n",
     "\n",
     "# search_api\n",

From 9ef52b5c7168d06f1dd9331bbc713532efc8d10f Mon Sep 17 00:00:00 2001
From: "Thomas C. Smits" <90332819+thomcsmits@users.noreply.github.com>
Date: Tue, 17 Sep 2024 15:25:52 -0400
Subject: [PATCH 19/27] Update src/tags.json

Co-authored-by: John Conroy <62477388+john-conroy@users.noreply.github.com>
---
 src/tags.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/tags.json b/src/tags.json
index bcf38b9..8afb9b7 100644
--- a/src/tags.json
+++ b/src/tags.json
@@ -11,5 +11,6 @@
   "slide-seq": "Slide-seq data",
   "files": "Work with HuBMAP data files",
   "hra": "Human Reference Atlas data",
-  "sc": "Single cell analysis"
+  "sc": "Single cell analysis",
+  "R": "Template written in R"
 }
\ No newline at end of file

From 33bc8e1f58bfa8150ed5a3ba824967bd7280e1cf Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 18 Sep 2024 09:25:00 -0400
Subject: [PATCH 20/27] add error message about vector of zeros

---
 .../templates/jupyter_lab/templates/scfind/template.txt       | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
index 7105697..8f2bd03 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
@@ -164,7 +164,9 @@
     "\n",
     "This example utilizes an annotated AnnData object loaded from _secondary_analysis.h5ad_, with cell annotations stored in AnnData.obs and feature names stored in AnnData.var. During index construction, a dataset_name parameter can be provided. This allows for differentiation of cell types from various datasets, potentially representing organ/tissue names, donor IDs, experimental conditions, or any other meaningful identifiers to distinguish cell groups from different datasets. In this example, we add the groupings based on the time of publishing as created above. Following this step, queries can be specified within the datasets of interest.\n",
     "\n",
-    "The index building process begins with the initialization of the scfind object and building index using a single AnnData object. Subsequently, any remaining AnnData objects are merged into the existing index. This approach conserves memory when multiple large datasets are loaded. "
+    "The index building process begins with the initialization of the scfind object and building index using a single AnnData object. Subsequently, any remaining AnnData objects are merged into the existing index. This approach conserves memory when multiple large datasets are loaded. \n",
+    "\n",
+    "> This might show certain errors about detected vectors of zeros. This is to be expected."
    ]
   },
   {

From 8b431c1e0ba7c63fcaee9891b140e765e0d07a60 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 18 Sep 2024 09:28:51 -0400
Subject: [PATCH 21/27] run black linting

---
 .../jupyter_lab/utils/convert-templates/convert-notebook.py     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py b/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
index 73cf296..7339b69 100644
--- a/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
+++ b/src/user_templates_api/templates/jupyter_lab/utils/convert-templates/convert-notebook.py
@@ -93,7 +93,7 @@ def notebookToTxt(file_folder):
         if '"outputs":' in text_txt_list[i]:
             text_txt_list[i] = '   "outputs": [],\n'
         if '"id":' in text_txt_list[i]:
-            text_txt_list[i] = ''
+            text_txt_list[i] = ""
 
     # write to txt
     with open(file_name_txt, "w") as file:

From 787cd70e0dc4e7d5667a473e50858ddc1b34f326 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 18 Sep 2024 09:31:32 -0400
Subject: [PATCH 22/27] update status to non-hidden

---
 .../templates/jupyter_lab/templates/scfind/metadata.json        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
index e5990ca..4892969 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
@@ -14,5 +14,5 @@
       "datasets": ["e7bdf34c4da9f1d880f2615226e9713d", "254801a318687281ba3e473569d89a45", "044b28971204366347e7ed0b7ef0c279", "4b5dc6d04aa30a6eb0b224a7ab7d03b3", "c14b104f9e44511ddf82697bce0d1901", "2639e9e8488edddde275491cdbaae662"]
     }
   ],
-  "is_hidden": true
+  "is_hidden": false
 }

From c094e62f4cdad179b7c54ebc4a65a023e530337d Mon Sep 17 00:00:00 2001
From: "Thomas C. Smits" <90332819+thomcsmits@users.noreply.github.com>
Date: Wed, 18 Sep 2024 09:58:43 -0400
Subject: [PATCH 23/27] Update
 src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json

Co-authored-by: John Conroy <62477388+john-conroy@users.noreply.github.com>
---
 .../templates/jupyter_lab/templates/scfind/metadata.json       | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
index 4892969..f49b6d9 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
@@ -11,7 +11,8 @@
     {
       "title": "Examine kidney datasets with scfind.",
       "description": "Build an index for two groups of kidney datasets and examine genes and cells.",
-      "datasets": ["e7bdf34c4da9f1d880f2615226e9713d", "254801a318687281ba3e473569d89a45", "044b28971204366347e7ed0b7ef0c279", "4b5dc6d04aa30a6eb0b224a7ab7d03b3", "c14b104f9e44511ddf82697bce0d1901", "2639e9e8488edddde275491cdbaae662"]
+      "datasets": ["e7bdf34c4da9f1d880f2615226e9713d", "254801a318687281ba3e473569d89a45", "044b28971204366347e7ed0b7ef0c279", "4b5dc6d04aa30a6eb0b224a7ab7d03b3", "c14b104f9e44511ddf82697bce0d1901", "2639e9e8488edddde275491cdbaae662"],
+      "resource_options": { "memory_mb" : 32768 }
     }
   ],
   "is_hidden": false

From 6164098c1d46ad4aefd4dfb9323daf9d858e4de9 Mon Sep 17 00:00:00 2001
From: thomcsmits <thomcsmits@outlook.com>
Date: Wed, 18 Sep 2024 10:01:50 -0400
Subject: [PATCH 24/27] add last modified timestamp

---
 .../templates/jupyter_lab/templates/scfind/metadata.json       | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
index f49b6d9..32b6bd5 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
@@ -15,5 +15,6 @@
       "resource_options": { "memory_mb" : 32768 }
     }
   ],
-  "is_hidden": false
+  "is_hidden": false,
+  "last_modified_unix_timestamp": 1726668082
 }

From d21cbbf576e571aaf09d256a474063f28adc0f0f Mon Sep 17 00:00:00 2001
From: John Conroy <john-conroy@users.noreply.github.com>
Date: Wed, 18 Sep 2024 15:58:18 -0400
Subject: [PATCH 25/27] update scfind description

---
 .../templates/jupyter_lab/templates/scfind/metadata.json        | 2 +-
 .../templates/jupyter_lab/templates/scfind/template.txt         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
index 32b6bd5..1abb0ac 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/metadata.json
@@ -1,6 +1,6 @@
 {
   "title": "Index and search single cell data with scfind",
-  "description": "This notebook shows how to do fast searches of large collections of single cell data with scfind.",
+  "description": "This notebook shows how to do fast searches of large collections of single cell data with scfind. We recommend setting the memory on the workspace advanced configuration settings to at least 32GB since building the scfind index can be memory-consuming.",
   "tags": [
     "anndata",
     "sc"
diff --git a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
index 8f2bd03..13b3c13 100644
--- a/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
+++ b/src/user_templates_api/templates/jupyter_lab/templates/scfind/template.txt
@@ -5,7 +5,7 @@
    "source": [
     "# Index and search single cell data with scfind\n",
     "\n",
-    "> We recommend increasing the memory on the workspace settings as building the scfind index can be quite memory-consuming.\n",
+    "> We recommend setting the memory on the workspace advanced configuration settings to at least 32GB since building the scfind index can be memory-consuming.\n",
     "\n",
     "This notebook shows how to do fast searches of large collections of single cell data with scfind.\n",
     "scfind is an advanced single-cell analysis tool that facilitates fast search of biologically relevant marker genes in cell atlases. Utilizing an efficient compression strategy for sparse single-cell measurements, scfind builds a compact index to store the expression matrix, enabling fast queries at single-cell resolution. The central operation carried out by scfind is to identify the set of cells expressing user-specified gene combinations. This functionality supports multiple analytical applications, including marker gene identification and evaluation, in silico gating, and identifying both cell-type-specific and housekeeping genes. Furthermore, scfind incorporates a subquery optimization routine, ensuring that long and complex queries return biologically meaningful results."

From 5b577e7335ca45c16620e9f5267e318836d855de Mon Sep 17 00:00:00 2001
From: John Conroy <john-conroy@users.noreply.github.com>
Date: Thu, 19 Sep 2024 09:10:24 -0400
Subject: [PATCH 26/27] Add zarr tag

---
 src/tags.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/tags.json b/src/tags.json
index 8afb9b7..71c1cc6 100644
--- a/src/tags.json
+++ b/src/tags.json
@@ -12,5 +12,6 @@
   "files": "Work with HuBMAP data files",
   "hra": "Human Reference Atlas data",
   "sc": "Single cell analysis",
-  "R": "Template written in R"
+  "R": "Template written in R",
+  "zarr": "Using zarr file format"
 }
\ No newline at end of file

From debe80ff9b978f5962a5911d33aa5f856d75ea7c Mon Sep 17 00:00:00 2001
From: jpuerto-psc <68066250+jpuerto-psc@users.noreply.github.com>
Date: Thu, 19 Sep 2024 09:17:12 -0400
Subject: [PATCH 27/27] Update VERSION

---
 VERSION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/VERSION b/VERSION
index 27f9cd3..227cea2 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.8.0
+2.0.0