final pass

NeurodataWithoutBorders · Jul 24, 2023 · b9c7775 · b9c7775
1 parent dba6ee6
commit b9c7775
Show file tree

Hide file tree

Showing 7 changed files with 439 additions and 407 deletions.
diff --git a/docs/notebooks/NERD_TermSet_How_to_Guide.ipynb b/docs/notebooks/NERD_TermSet_How_to_Guide.ipynb
diff --git a/docs/notebooks/NERD_TermSet_Quickstart.ipynb b/docs/notebooks/NERD_TermSet_Quickstart.ipynb
@@ -3,7 +3,7 @@
   {
    "cell_type": "code",
    "execution_count": 43,
-   "id": "cfc4af3b",
+   "id": "32bc4725",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -22,15 +22,31 @@
   },
   {
    "cell_type": "markdown",
-   "id": "54c9ebdc",
+   "id": "2deb3104",
+   "metadata": {},
+   "source": [
+    "## Dev Days Note:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cf3fa9ad",
+   "metadata": {},
+   "source": [
+    "To run this notebook please download the nwb files under the \"DynamicTermset and ExternalResources\" project in the \"Materials\" subsection marked \"NWB Files for Tutorials\"."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10177e66",
    "metadata": {},
    "source": [
     "# NERD and TermSet QuickStart"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "a413f0a7",
+   "id": "41126052",
    "metadata": {},
    "source": [
     "The NWB External Resources Data (NERD) data structure supports annotation of NWB data files by linking terms used in the data to external resources, such as ontologies, brain atlases, and persistent digital identifiers. NERD files are external to NWB files, enabling annotation of both new and existing data without requiring modification of existing data. \n",
@@ -42,23 +58,23 @@
   {
    "attachments": {},
    "cell_type": "markdown",
-   "id": "a85754fd",
+   "id": "45b95fb5",
    "metadata": {},
    "source": [
     "![er_img.png](er_img.png)"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "8ac17e24",
+   "id": "dfd0d382",
    "metadata": {},
    "source": [
     "## NERD Example"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "7808b248",
+   "id": "2e29d242",
    "metadata": {},
    "source": [
     "In the following example, we will highlight the fact `NERD` is written separately to the `NWBFile`. This is to allow users to add metadata references to existing files. Loading in the file, we can see multiple cases where contextual metadata will be important in regards to creating and sharing FAIR data. We can map the experimenter to a digital identifier (e.g., ORCID), the electrode group location can be mapped to a brain atlas, and the `Subject` species attribute can be mapped to the NCBI Taxonomy.\n",
@@ -69,7 +85,7 @@
   {
    "cell_type": "code",
    "execution_count": 18,
-   "id": "f5665ab6",
+   "id": "020ae1d7",
    "metadata": {},
    "outputs": [
     {
@@ -165,7 +181,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "bcc0c961",
+   "id": "20cafe20",
    "metadata": {},
    "source": [
     "First we are going to link the ExternalResources class to the file we want to annotate to ensure we can track correctly the location of all the data objects that contain terms we want to describe via external references. This can also be accomplished by setting the `file` field as we will see later on."
@@ -174,7 +190,7 @@
   {
    "cell_type": "code",
    "execution_count": 35,
-   "id": "abff1a3f",
+   "id": "10e7e96d",
    "metadata": {},
    "outputs": [
     {
@@ -193,7 +209,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "9c83c00c",
+   "id": "cacf036b",
    "metadata": {},
    "source": [
     "To create the metadata linkage from the experimenter, electrode group location, and subject species to their respective external references, the user can use the `add_ref` method from `ExternalResources`. The user provides:\n",
@@ -207,7 +223,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "4c44c7d3",
+   "id": "eb76d1a2",
    "metadata": {},
    "source": [
     "### NWBFile Experimenter"
@@ -216,7 +232,7 @@
   {
    "cell_type": "code",
    "execution_count": 36,
-   "id": "ac2d677d",
+   "id": "d6c9605e",
    "metadata": {},
    "outputs": [
     {
@@ -242,7 +258,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "63e3bd6e",
+   "id": "9a1cfad9",
    "metadata": {},
    "source": [
     "### ElectrodeGroup Location"
@@ -251,7 +267,7 @@
   {
    "cell_type": "code",
    "execution_count": 37,
-   "id": "3e6284d8",
+   "id": "32607806",
    "metadata": {},
    "outputs": [
     {
@@ -277,7 +293,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "4bbfdb46",
+   "id": "ba3e7005",
    "metadata": {},
    "source": [
     "### Subject Species"
@@ -286,7 +302,7 @@
   {
    "cell_type": "code",
    "execution_count": 38,
-   "id": "341c1218",
+   "id": "b54e25be",
    "metadata": {},
    "outputs": [
     {
@@ -312,7 +328,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "06b1d373",
+   "id": "05027a31",
    "metadata": {},
    "source": [
     "We can see that the linked `ExternalResources` instance has been populated."
@@ -321,7 +337,7 @@
   {
    "cell_type": "code",
    "execution_count": 39,
-   "id": "41545809",
+   "id": "87a19bff",
    "metadata": {},
    "outputs": [
     {
@@ -387,7 +403,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "8582b2bd",
+   "id": "4c70082b",
    "metadata": {},
    "source": [
     "We can visualize `ExternalResources` as a single table:"
@@ -396,7 +412,7 @@
   {
    "cell_type": "code",
    "execution_count": 40,
-   "id": "fa9efe78",
+   "id": "c8135f23",
    "metadata": {},
    "outputs": [
     {
@@ -523,7 +539,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "c43849c1",
+   "id": "75f3788d",
    "metadata": {},
    "source": [
     "As mentioned prior, `NERD` and the `NWBFile` are written separately."
@@ -532,7 +548,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "2960be64",
+   "id": "8f9646c0",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -543,7 +559,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "16930128",
+   "id": "f116cad5",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -552,23 +568,23 @@
   },
   {
    "cell_type": "markdown",
-   "id": "d0ea331b",
+   "id": "04039654",
    "metadata": {},
    "source": [
     "To see the various query methods and the explicit set of rules within `NERD`, please refer to the [NERD guide](NERD_TermSet_How_to_Guide.ipynb)."
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "e50e520c",
+   "id": "13ad1bb8",
    "metadata": {},
    "source": [
     "## NERD Example with TermSet"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "44597e74",
+   "id": "26d44e1f",
    "metadata": {},
    "source": [
     "`TermSet` allows users to create their own subset of terms with ontological references and is built upon the resources from LinkML.\n",
@@ -582,15 +598,15 @@
   },
   {
    "cell_type": "markdown",
-   "id": "93058645",
+   "id": "9752a049",
    "metadata": {},
    "source": [
-    "<img src=\"exp1.png\" width=600 align='left'>"
+    "<img src=\"experimenters_schema.png\" width=600 align='left'>"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "b22d72a6",
+   "id": "34713157",
    "metadata": {},
    "source": [
     "In this example, we will create a brand new `NWBFile` that stores a `DynamicTable` of species data. We create a new column, i.e a new instance of `VectorData`, that uses the optional `term_set` field. When provided a `TermSet`, the data will be validated according to that set of terms.\n",
@@ -601,7 +617,7 @@
   {
    "cell_type": "code",
    "execution_count": 44,
-   "id": "3774187b",
+   "id": "385854b9",
    "metadata": {},
    "outputs": [
     {
@@ -621,7 +637,7 @@
   {
    "cell_type": "code",
    "execution_count": 45,
-   "id": "a9981b41",
+   "id": "d10c672d",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -649,7 +665,7 @@
   {
    "cell_type": "code",
    "execution_count": 46,
-   "id": "de4cf928",
+   "id": "166293b5",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -658,7 +674,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "a7a64d60",
+   "id": "aa6ffcdc",
    "metadata": {},
    "source": [
     "As mentioned prior, the `add_ref_term_set` method streamlines the original `add_ref` method. The `key` field is removed as the data values themselves will be used as keys, the `entity_id` and `entity_uri` fields will be populated from the values within the `TermSet`. If the user linked the `NWBFile` to the `ExternalResources` instance as in the prior example, then it is further streamlined, requiring only the `container` and possibly an `attribute`."
@@ -667,7 +683,7 @@
   {
    "cell_type": "code",
    "execution_count": 47,
-   "id": "41a882eb",
+   "id": "ed8be94f",
    "metadata": {},
    "outputs": [
     {
@@ -691,7 +707,7 @@
   {
    "cell_type": "code",
    "execution_count": 48,
-   "id": "0503347b",
+   "id": "1ea2f16d",
    "metadata": {},
    "outputs": [
     {
@@ -794,7 +810,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "d9fab152",
+   "id": "484dbaa2",
    "metadata": {},
    "outputs": [],
    "source": []

diff --git a/docs/notebooks/exp1.png b/docs/notebooks/exp1.png
diff --git a/docs/notebooks/experimenters_schema.png b/docs/notebooks/experimenters_schema.png
diff --git a/docs/notebooks/species_schema.png b/docs/notebooks/species_schema.png
diff --git a/docs/notebooks/species_term_set.yaml b/docs/notebooks/species_term_set.yaml
@@ -1,7 +1,7 @@
 id: noteeooks/species_example
 name: Species
 prefixes:
-  NCBI_TAXON: https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Info&id= # update uri to remove ?/cgi
+  NCBI_TAXON: https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Info&id=
   Ensemble: https://rest.ensembl.org/taxonomy/id/
 imports:
   - linkml:types

diff --git a/docs/notebooks/taxon.png b/docs/notebooks/taxon.png