posts/2024-04-02-n5-attribute-paths.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "97d1b8f0",
   "metadata": {},
   "source": [
    "---\n",
    "aliases:\n",
    "- /imglib2/n5/hdf5/zarr/jupyter/notebook/2022/09/27/n5-imglib2\n",
    "author: \n",
    "    - name: John Bogovic\n",
    "    - name: Caleb Hulbert\n",
    "image: 2024-04-02-n5-attribute-paths-thumbnail.png\n",
    "badges: true\n",
    "branch: master\n",
    "categories:\n",
    "- n5\n",
    "- attributes\n",
    "- metadata\n",
    "- tutorial\n",
    "date: '2024-04-02'\n",
    "description: Learn to get and set arbitrary parts of an attribute hierarchy with the N5 API.\n",
    "output-file: 2024-04-02-n5-attribute-paths.html\n",
    "title: N5 attribute paths\n",
    "toc: true\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ef2f3d2c",
   "metadata": {},
   "outputs": [],
   "source": [
    "//| code-fold: true\n",
    "\n",
    "%mavenRepo scijava.public https://maven.scijava.org/content/groups/public\n",
    "%maven org.scijava:scijava-common:2.97.0\n",
    "%maven net.imglib2:imglib2:6.2.0\n",
    "%maven org.janelia.saalfeldlab:n5:3.1.2\n",
    "%maven org.janelia.saalfeldlab:n5-imglib2:7.0.0\n",
    "%maven org.janelia.saalfeldlab:n5-universe:1.3.1\n",
    "    \n",
    "import java.nio.file.*;\n",
    "import java.util.*;\n",
    "import java.util.stream.*;\n",
    "import java.util.concurrent.*;\n",
    "\n",
    "import com.google.gson.*;\n",
    "\n",
    "import net.imglib2.*;\n",
    "import net.imglib2.img.array.*;\n",
    "import net.imglib2.type.numeric.real.*;\n",
    "import net.imglib2.view.*;\n",
    "import net.imglib2.util.*;\n",
    "\n",
    "import org.janelia.saalfeldlab.n5.*;\n",
    "import org.janelia.saalfeldlab.n5.imglib2.*;\n",
    "import org.janelia.saalfeldlab.n5.universe.*;\n",
    "\n",
    "public static void pathInfo(Path p) {\n",
    "    try {\n",
    "        System.out.println(String.format(\"%s is %d bytes\", p, Files.size(p))); \n",
    "    } catch(IOException e ){}\n",
    "}\n",
    "\n",
    "public static void printBlocks(String path) throws IOException {\n",
    "\n",
    "    try (Stream<Path> stream = Files.walk(Paths.get(path))) {\n",
    "        stream.filter(Files::isRegularFile)\n",
    "            .filter( p -> p.getFileName().toString().matches(\"[0-9]\"))\n",
    "                .forEach( x -> { pathInfo(x); });\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07eca28c",
   "metadata": {},
   "source": [
    "Recall that structured metadata attributes can be written to a container using\n",
    "\n",
    "`N5Writer.setAttribute(String group, String key, Object value)` \n",
    "\n",
    "and read using \n",
    "\n",
    "`N5Reader.getAttribute(String group, String key, Class class)`.\n",
    "\n",
    "These basics are described in the [N5 API Basics Tutorial](https://imglib.github.io/imglib2-blog/posts/2024-02-27-n5-tutorial-basic/#metadata). In this tutorial, we will show that methods accept more sophisticated expressions for the key that we call \"attribute paths.\" These enable you to set and access any part of the attribute hierarchy.\n",
    "\n",
    "## Arrays\n",
    "\n",
    "We'll start by discussing array attribute indexing. First make some array attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "fe91009f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5.0, 6.0, 7.0, 8.0]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var n5 = new N5Factory().openWriter(\"attribute-demo.n5\");\n",
    "var group = \"arrayDemo\";\n",
    "n5.createGroup(group);\n",
    "\n",
    "n5.setAttribute(group, \"array\", new double[]{ 5, 6, 7, 8 });\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", double[].class));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3cc542e7",
   "metadata": {},
   "source": [
    "Individual elements of the array can be retrieved by adding `[i]` after the key, where `i` is an integer (zero-based indexing). N5 will return null for indexes outside the bounds of the array, including for negative values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9026d5f6",
   "metadata": {},
   "outputs": [],
   "source": [
    "n5.getAttribute(group, \"array[0]\", double.class);  // returns 5.0\n",
    "n5.getAttribute(group, \"array[2]\", double.class);  // returns 7.0\n",
    "n5.getAttribute(group, \"array[9]\", double.class);  // returns null\n",
    "n5.getAttribute(group, \"array[-1]\", double.class); // returns null"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd34efc8",
   "metadata": {},
   "source": [
    "This syntax lets you set individual array elements as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "1b68a54e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5.0, 0.6, 7.0, 8.0]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"array[1]\", 0.6);\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", double[].class));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7b70d56",
   "metadata": {},
   "source": [
    "The array will grow if we set a value outside the range of an array. The array will be filled with zeros if the array is numeric."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "99c9f81a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5.0, 0.6, 7.0, 8.0, 0.0, 0.0, 99.99]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"array[6]\", 99.99);\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", double[].class));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "288baf9b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5.0, 0.6, 7.0, 8.0, 0.0, 0.0, 99.99]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"array[-5]\", -5); // does nothing\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", double[].class));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "7d8ed446",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[2,0,0,0],[0,4,0,0],[0,0,6,0],[0,0,0,8]]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "IntStream.range(0, 4).forEach( i -> {\n",
    "    n5.setAttribute(group, \"matrix[\"+i+\"][3]\", 0);\n",
    "    n5.setAttribute(group, \"matrix[\"+i+\"][\"+i+\"]\", 2*(i+1));\n",
    "});\n",
    "\n",
    "n5.getAttribute(group, \"matrix\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db808b74",
   "metadata": {},
   "source": [
    "An array that is not numeric that needs to grown will be filled with `null`s."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "2822f20b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[a, b, null, null, null, null, g]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"stringArray\", new String[]{\"a\", \"b\"});\n",
    "n5.setAttribute(group, \"stringArray[6]\", \"g\");\n",
    "\n",
    "Arrays.toString(n5.getAttribute(group, \"stringArray\", String[].class));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b7ea1de",
   "metadata": {},
   "source": [
    "N5's `setAttribute` will always do what is requested when possible, even if it will overwrite data. If safety is necessary, developers should manually check if an attribute key is present. Use of the type `JsonElement` type is the most safe, because a non-null `JsonElement` will be returned if data of any type is present at the requested key."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "5a9f3e0a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[destroy]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "// overwrite the previous array\n",
    "n5.setAttribute(group, \"array\", new String[]{\"destroy\"});  // array is now [ \"destroy\" ]\n",
    "\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", String[].class));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "d06a2ba4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[destroy]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "if( n5.getAttribute( group, \"array\", JsonElement.class ) == null )\n",
    "    n5.setAttribute(group, \"array\", new String[]{});   // array is still [ \"destroy\" ]\n",
    "\n",
    "Arrays.toString(n5.getAttribute(group, \"array\", String[].class));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7422f926",
   "metadata": {},
   "source": [
    "## Objects\n",
    "\n",
    "JSON objects are structures with \"fields\" that can be referenced by their String name. One way to set objects is by using a `Map`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "61c8141c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{a=A}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var group = \"objectDemo\";\n",
    "n5.createGroup(group);\n",
    "\n",
    "var a = Collections.singletonMap(\"a\", \"A\");\n",
    "\n",
    "n5.setAttribute(group, \"obj\", a ); \n",
    "n5.getAttribute(group, \"obj\", Map.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4472cf0a",
   "metadata": {},
   "source": [
    "The value for an object's field can be any type, even another object. Individual fields for an object can be accessed by appending `/<field-name>` to the attribute name. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "1e7f51b1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{a={b=B}}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var b = Collections.singletonMap(\"b\", \"B\");\n",
    "\n",
    "// set the value of obj/a to {b=B}\n",
    "n5.setAttribute(group, \"obj/a\", b);\n",
    "n5.getAttribute(group, \"obj\", Map.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "ac0fe5e3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{b=B}"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"obj/a\", Map.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aed4cc5d",
   "metadata": {},
   "source": [
    "Notice that it is possible to repeatedly access subfields of nested objects. In fact, the set of all attributes in an N5 group is usually itself an object! We call it the \"root object\" and access it with the the key `\"/\"`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "2a74223e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{obj={a={b=B}}}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"/\", Map.class); "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23ba21d7",
   "metadata": {},
   "source": [
    "For the following examples, we'll use the class `Pet` defined here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "8299262b",
   "metadata": {},
   "outputs": [],
   "source": [
    "//| code-fold: true\n",
    "\n",
    "class Pet {\n",
    "    String name;\n",
    "    int age;\n",
    "\n",
    "    public Pet(String name, int age) {\n",
    "        this.name = name;\n",
    "        this.age = age;\n",
    "    }\n",
    "\n",
    "    public String toString() {\n",
    "        return String.format(\"pet %s is %d\", name, age);\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "e95d2f5b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pet Pluto is 93"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"pet\", new Pet(\"Pluto\", 93));\n",
    "Pet pet = n5.getAttribute(group, \"pet\", Pet.class);\n",
    "pet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "14933745",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{name=Pluto, age=93.0}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"pet\", Map.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "d0d3dab7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{name=Pluto, age=93.0, likes=[Micky]}"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"pet/likes\", new String[]{\"Micky\"});\n",
    "n5.getAttribute(group, \"pet\", Map.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f2e8cab",
   "metadata": {},
   "source": [
    "## Mixing object and array indexing\n",
    "\n",
    "This example sets the value of an integer inside several nested arrays and objects.\n",
    "\n",
    "Note: When indexing an array, the path separators `/` before and after the index operator `[ ]` are optional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "ab8448d6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"one\":[null,null,{\"three\":[12,0,0,0,5]}]}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "// remove all attributes \n",
    "n5.removeAttribute(group, \"/\");\n",
    "\n",
    "n5.setAttribute(group, \"one/[2]/three/[4]\", 5);\n",
    "n5.setAttribute(group, \"one[2]three[0]\", 12);\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6ed97ea",
   "metadata": {},
   "source": [
    "## Removing attributes and dealing with nulls\n",
    "\n",
    "We saw about that `removeAttribute` can be used to remove attributes. The first variant takes the group and attribute key as arguments, and returns nothing after removal. The second variant also takes a Class<T> argument and will return the removed object of type T if possible. If the value of the attribute cannot be parsed into the requested type, the attribute will not be removed, even if the key exists."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "a4665211",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"cow\":\"moo\",\"dog\":\"woof\",\"sheep\":\"baa\"}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var group = \"animals\";\n",
    "n5.createGroup(group);\n",
    "\n",
    "n5.setAttribute(group, \"cow\", \"moo\");\n",
    "n5.setAttribute(group, \"dog\", \"woof\");\n",
    "n5.setAttribute(group, \"sheep\", \"baa\");\n",
    "\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "c13c8a45",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"dog\":\"woof\",\"sheep\":\"baa\"}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.removeAttribute(group, \"cow\"); // void method\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "47f04352",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The doggie says: woof\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{\"sheep\":\"baa\"}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "System.out.println( \"The doggie says: \" + \n",
    "    n5.removeAttribute(group, \"dog\", String.class)\n",
    ");\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "11a10567",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "An exception was thrown\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{\"sheep\":\"baa\"}"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "// throws an exception because the value of \"sheep\" is not an int\n",
    "try {\n",
    "    n5.removeAttribute(group, \"sheep\", int.class);\n",
    "}catch(N5Exception e ){\n",
    "    System.err.println(\"An exception was thrown\");\n",
    "}\n",
    "\n",
    "// observe that the attribute was not removed\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "241cd1c8",
   "metadata": {},
   "source": [
    "::: {.callout-warning}\n",
    "\n",
    "In the default implemenation, setting the value of an attribute to `null` will remove that attribute (i.e. the attribute's key will be removed).\n",
    "\n",
    "However, we strongly recommended using the `removeAttribute` methods when removing attributes, since setting an attribute to `null` can lead to inconsistent behaviour, depending on how the `N5Writer` was created (see below).\n",
    "\n",
    "Setting an attribute path to `null` can even result in creating attributes along the path, regardless of whether `serializeNulls` is enabled or not.\n",
    ":::\n",
    "\n",
    "In cases where it is useful to write the value `null` into the attributes, you must create an `N5Writer` using a `GsonBuilder` with `serializeNulls` enabled. This example writes a `null` value to the key `\"attr\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "dd347c77",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"sheep\":\"baa\",\"attr\":null}"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var n5WithNulls = new N5Factory()\n",
    "    .gsonBuilder(new GsonBuilder().serializeNulls())\n",
    "    .openWriter(\"attribute-demo.n5\");\n",
    "\n",
    "n5WithNulls.setAttribute(group, \"attr\", null);\n",
    "n5WithNulls.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8b61016",
   "metadata": {},
   "source": [
    "## Keys are paths\n",
    "\n",
    "Think about keys as paths into a hierarchy, where `/` separates levels of the hierarchy. Attribute methods support relative paths, where `.` refers to \"this\" path, and `..` refers to the parent path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "c87e7b93",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"a\":{\"b\":{\"c\":\"tutorial\"}}}"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var group = \"details\";\n",
    "n5.createGroup(group);\n",
    "\n",
    "n5.setAttribute(group, \"a/b/c\", \"tutorial\");\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "504caafa",
   "metadata": {},
   "source": [
    "The key `a/.` is equivalent to `a`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "f0ef62a2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"b\":{\"c\":\"tutorial\"}}"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"a/.\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "fb4da1da",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"a\":{\"b\":{\"c\":\"tutorial\"}}}"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"a/..\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad30eb53",
   "metadata": {},
   "source": [
    "The parent of an array element refers to the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "81ad6d5a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[\"Alice\",\"Bob\"]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.setAttribute(group, \"array\", new String[]{\"Alice\", \"Bob\"});\n",
    "n5.getAttribute(group, \"array[0]/..\", JsonElement.class);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e645a51d",
   "metadata": {},
   "source": [
    " Getting the parent attribute relative to the root will return `null`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "d5ae2181",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "true"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n5.getAttribute(group, \"..\", JsonElement.class) == null;"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4212a2c",
   "metadata": {},
   "source": [
    "## Warnings and caveats\n",
    "\n",
    "\n",
    "::: {.callout-warning}\n",
    "\n",
    "We strongly recommend against using `/` or `\\` in key names. Similarly, `.` or `..` should not be \n",
    "used in between forward slashes, i.e. avoid (`/../` or `/./` in key names).\n",
    "\n",
    ":::\n",
    "\n",
    "While we recommend against it, is it possible to use forward slash (`/`) or backslash (`\\`) as field names for attributes. Since `/` is reserved to refer to the root attribute, it must be escaped with a backslash to refer to the literal string `\"/\"`.\n",
    "\n",
    "The code below is not suitable for children, or anyone."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "7b4a6b73",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\"/\":\"Please don't do this\",\"\\\\\":\"UGH\",\".\":\"what does this mean!?\",\"../.\":\"...pain...\"}"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var group = \"warnings\";\n",
    "n5.createGroup(group);\n",
    "\n",
    "n5.setAttribute(group, \"\\\\/\", \"Please don't do this\");\n",
    "n5.setAttribute(group, \"\\\\\", \"UGH\");\n",
    "n5.setAttribute(group, \".\", \"what does this mean!?\");\n",
    "n5.setAttribute(group, \"..\\\\/.\", \"...pain...\");\n",
    "\n",
    "n5.getAttribute(group, \"/\", JsonElement.class);"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Java",
   "language": "java",
   "name": "java"
  },
  "language_info": {
   "codemirror_mode": "java",
   "file_extension": ".jshell",
   "mimetype": "text/x-java-source",
   "name": "Java",
   "pygments_lexer": "java",
   "version": "19.0.2+7-Ubuntu-0ubuntu322.04"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}