Merge pull request #9 from BiAPoL/added-notebooks-for-tagging

Added notebooks for tagging

docs/_toc.yml

@@ -8,6 +8,7 @@ chapters:
     - file: notebooks/metadata/01_key_value_pairs
     - file: notebooks/metadata/02_setting_pixel_sizes
     - file: notebooks/metadata/03_setting_channel_names
-    - file: notebooks/metadata/04_synchronize_tags
+    - file: notebooks/metadata/04_tagging_data
+    - file: notebooks/metadata/05_synchronize_tags
   - file: instructions/transfer_dataset
 

docs/notebooks/metadata/01_key_value_pairs.ipynb

@@ -4,6 +4,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "(omero-tools:key-value-pairs)=\n",
+    "\n",
     "# Reading, writing and editing key-value pairs\n",
     "\n",
     "Key value pairs are a key (pun intended) part of annotating data in OMERO in a very flexible way. In essence, they provide a way of adding Python dictionaries to an image, a project or a dataset - and a Python dictionary is fit for data of virtually any form. Here are a few ways of interacting with data in this form through Python."

docs/notebooks/metadata/04_tagging_data.ipynb

@@ -0,0 +1,184 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How to tag and retrieve tags from data\n",
+    "\n",
+    "Another key concept of organizing data on OMERO (besides [key-value pairs](omero-tools:key-value-pairs)) is given by *tags*. Can be used to group data in a more flexible way than the hierarchy of projects, datasets and images. For a more in-depth explanation of some of the underlying concepts, see [these excellent training materials](https://zenodo.org/records/8323588) regarding OMERO in general."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ezomero"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "host = 'omero-int.biotec.tu-dresden.de'\n",
+    "user = ''  # replace this with your username\n",
+    "secure = True\n",
+    "port = 4064\n",
+    "group = 'default'\n",
+    "\n",
+    "conn = ezomero.connect(host=host, user=user, secure=secure, port=port, group=group)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tagging data\n",
+    "\n",
+    "The easiest and most straightforward way to tag your data is arguably to simply do this through the web interface of your OMERO servers. Omero extensions such as the excellent [autotag](https://pypi.org/project/omero-autotag/) extension make setting meaningful tags on your data a breeze. The question then becomes - how do you retrieve tags that have already been added to your data?\n",
+    "\n",
+    "## Reading tags from OMERO\n",
+    "\n",
+    "Let's use [ezomero](https://thejacksonlaboratory.github.io/ezomero/) again to retrieve tags that have been added to an image. This will return a list of tags (indicated by their respective ids) that have been added to the image. This is an important concept to grasp: Just like an image, a tag is an object in the OMERO database, and it has a unique identifier (id). This id is what is returned when you retrieve tags from an image."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[1088]\n"
+     ]
+    }
+   ],
+   "source": [
+    "tag_ids = ezomero.get_tag_ids(conn, object_type='Image', object_id=330, ns=None)\n",
+    "print(tag_ids)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we want to see the \"value\" of the tag, we can use the `get_tag` function to introspect the ids we just retrieved:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'Fluorescence'"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "ezomero.get_tag(conn, tag_id=tag_ids[0])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Adding a tag to data\n",
+    "\n",
+    "Adding a tag to an image is a little less straightforward. For once, it makes more sense to create and organize the tags through the web interface. The [following tutorial](omero-tools:synchronize-tags) introduces a way to set tags and tag groups from a yaml file, but this is a bit more complicated. For simplicity, let's assume we already created some tags and we know their ids from the web interface:\n",
+    "\n",
+    "![new tag list](./imgs/new_tag0.PNG)\n",
+    "![new tag](./imgs/new_tag1.PNG)\n",
+    "\n",
+    "To add this newly created tag to our image, we need to first retrieve both the tag and the image objects from the remote server:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tag_object = conn.getObject('Annotation', 8354)\n",
+    "image_object = conn.getObject('Image', 330)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the next step, we link the tag to the image:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "image_object.linkAnnotation(tag_object)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's check whether this worked:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Fluorescence   (Tag id: 1088)\n",
+      "Raw data   (Tag id: 8354)\n"
+     ]
+    }
+   ],
+   "source": [
+    "tag_ids = ezomero.get_tag_ids(conn, object_type='Image', object_id=330, ns=None)\n",
+    "\n",
+    "for tag_id in tag_ids:\n",
+    "    print(ezomero.get_tag(conn, tag_id=tag_id), ' ', f'(Tag id: {tag_id})')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "stress",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.19"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/notebooks/metadata/04_synchronize_tags.ipynb → docs/notebooks/metadata/05_synchronize_tags.ipynb

@@ -4,6 +4,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "(omero-tools:synchronize-tags)=\n",
+    "\n",
     "# Synchronize tags across groups\n",
     "\n",
     "To make sure that there is some standardization across projects with regard to how data is tagged and annotated, we need to synchronize tags across groups. The goal is to make sure that the tags used in the data are consistent across groups. This will make it easier to search for data and to use the data in the future. The defined tags themselves are based off of the [REMBI metadata schema](https://www.nature.com/articles/s41592-021-01166-8). More specifically, we orient ourselves on the tags used in the [provided spreadsheet](https://docs.google.com/spreadsheets/d/1Ck1NeLp-ZN4eMGdNYo2nV6KLEdSfN6oQBKnnWU6Npeo/edit).\n",