FlyWireAnnotationTutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The CAVEclient\n",
    "\n",
    "The CAVEclient is a client side library to allow easy interaction with the services within CAVE (connectome annotation versioning engine, also known as Dynamic Annotation Framework), eg. the annotations, stateserver. The github repository is public:\n",
    "https://github.com/seung-lab/CAVEclient\n",
    "\n",
    "The library can be installed directly from the github repository or from the prebuilt versions using pip:\n",
    "```\n",
    "pip install caveclient\n",
    "```\n",
    "\n",
    "\n",
    "## Tutorials\n",
    "\n",
    "This tutorial mainly covers the interactions with the materialized annotation tables. More information and better explanations of the other functionalities of the client can be found in the following tutorial. Please be advised that depending on your permission level you may not be able to execute all queries in this tutorial with the preset parameters as it was written with defaults for iarpa's microns project:\n",
    "https://github.com/seung-lab/CAVEclient/blob/master/CAVEclientExamples.ipynb\n",
    "\n",
    "\n",
    "## Authentication & Authorization\n",
    "\n",
    "If this is your first time to interact with any part of CAVE, chances are you need to setup your local credentials for your FlyWire account first. Please follow the section \"Setting up your credentials\" at the beginning of the tutorial above to do so.\n",
    "\n",
    "You will need to have access to the FlyWire's production dataset to retrieve annotations. Otherwise you will see\n",
    "\n",
    "```HTTPError: 403 Client Error: FORBIDDEN for url```\n",
    "\n",
    "errors upon querying the materialization server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initializing the CAVEclient\n",
    "\n",
    "The FrameworkClient is instantiated with a datastack name. A datastack is a set of segmentation, and annotation tables and lives within an aligned volume (the coordinate space). FlyWire's main datastack is `flywire_fafb_production`, the aligned volume is `fafb_seung_alignment_v0` (v14.1). For convenience, there are other defaults set on the datastack level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import datetime\n",
    "import pandas as pd\n",
    "from caveclient import CAVEclient"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "datastack_name = \"flywire_fafb_production\"\n",
    "client = CAVEclient(datastack_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Annotation tables\n",
    "\n",
    "Annotations are represented by points in space and parameters (such as size, type). At specific timepoints, annotations are combined with the (proofread) segmentation to create a materialized version of the annotation table. The AnnotationEngine (`client.annotation`) owns the raw annotations and the Materialization Service (`client.materialize`) owns the materialized versions of these tables. \n",
    "\n",
    "To check what annotation tables are visible to you run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "https://prod.flywire-daf.com/annotation/api/v2/aligned_volume/fafb_seung_alignment_v0/table\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "['synapses_nt_v1', 'nuclei_v1']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "client.annotation.get_tables()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a table"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All users with permissions to proofread in FlyWire can create annotation tables and upload annotations. Currently, only the user who created a table can upload annotations to it; all other users have read access to the table.\\\n",
    "\n",
    "Creating a table requires a unique `table_name`, a `schema`, a `description` and a `voxel_resolution`. The `voxel_resolution` defines the resolution with which annotations are uploaded. For instance, `[1, 1, 1]` would mean that annotations in this table will be uploaded in nanometer space. \n",
    "\n",
    "Schemas are managed in a separate [repository](https://github.com/seung-lab/EMAnnotationSchemas). Schemas can freely be chosen from [there](https://globalv1.daf-apis.com/schema/views/). If no applicable schema is available, we encourage users to create a new schema and submit a pull-request. \n",
    "\n",
    "In the example below, we are going to use the [`bound_tag`](https://globalv1.daf-apis.com/schema/views/type/bound_tag/view) schema which is an annotation with one coordinate and a text field. All annotations in a table follow the same schema."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To avoid the creation of a large list of test tables, the following code is embedded in markdown. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "\n",
    "table_name = \"my_table\"\n",
    "\n",
    "description = \"\"\"\n",
    "This is a test table to demonstrate table creation and annotation upload.\n",
    "The data in this table is random and should not be used for analysis.\n",
    "\n",
    "This table was create by ...\"\"\"\n",
    "\n",
    "client.annotation.create_table(table_name=random_table_name,\n",
    "                               schema_name=\"bound_tag\",\n",
    "                               description=description,\n",
    "                               voxel_resolution=[1, 1, 1])\n",
    "                               \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All tables are listed here: https://prod.flywire-daf.com/annotation/views/aligned_volume/fafb_seung_alignment_v0\n",
    "\n",
    "A specific table can be viewed here: https://prod.flywire-daf.com/annotation/views/aligned_volume/fafb_seung_alignment_v0/table/table_name (with table_name replaced)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Uploading and updating annotations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we generate some annotations to be uploaded to the new table. Tables can be uploaded from pandas DataFrames with columns according to the schema. One can include an `id` column to specify specific annotation, otherwise `id`s are assigned by the backend. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "random_locations_nm = np.random.randint([448000, 185000,  87000], [588000, 292000,  90000], size=[100, 3], dtype=int)\n",
    "random_tags = [f\"tag {i}\" for i in range(100)]\n",
    "\n",
    "random_annotation_data = pd.DataFrame.from_dict({\"pt_position\": list(random_locations_nm), \n",
    "                                                 \"tag\": random_tags,\n",
    "                                                 \"id\": np.arange(100, 200)})\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Annotations can be uploaded using `client.annotation.post_annotation` or `client.annotation.post_annotation_df`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "client.annotation.post_annotation_df(table_name=random_table_name,\n",
    "                                     df=random_annotation_data,\n",
    "                                     position_columns=[\"pt_position\"])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Updating annotations works similarly to uploading them in the first place. Updating requires `id`s to be defined."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "random_locations_nm = np.random.randint([448000, 185000,  87000], [588000, 292000,  90000], size=[10, 3], dtype=int)\n",
    "random_tags = [f\"tag {i}\" for i in range(10)]\n",
    "\n",
    "random_annotation_data = pd.DataFrame.from_dict({\"pt_position\": list(random_locations_nm), \n",
    "                                                 \"tag\": random_tags,\n",
    "                                                 \"id\": np.arange(100, 110)})\n",
    "                                                 \n",
    "client.annotation.update_annotation_df(table_name=random_table_name,\n",
    "                                       df=random_annotation_data,\n",
    "                                       position_columns=[\"pt_position\"])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reading annotations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Annotations can be read directly from the annotation service. Annotations can be read by ID. Here, we use the nucleus table (`nuclei_v1`, see it online [here](https://prod.flywire-daf.com/annotation/views/aligned_volume/fafb_seung_alignment_v0/table/nuclei_v1)) as example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'volume': 6.65092096,\n",
       "  'bb_start_position': [718496, 261792, 114640],\n",
       "  'valid': True,\n",
       "  'bb_end_position': [722016, 265120, 116200],\n",
       "  'pt_position': [720000, 263360, 115520],\n",
       "  'superceded_id': None,\n",
       "  'created': '2021-06-23 19:55:35.166396',\n",
       "  'deleted': 'None',\n",
       "  'id': 7415718},\n",
       " {'volume': 11.52339968,\n",
       "  'bb_start_position': [708800, 262112, 128200],\n",
       "  'valid': True,\n",
       "  'bb_end_position': [712064, 264832, 131080],\n",
       "  'pt_position': [710592, 263392, 129800],\n",
       "  'superceded_id': None,\n",
       "  'created': '2021-06-23 19:55:35.160196',\n",
       "  'deleted': 'None',\n",
       "  'id': 7416439}]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "client.annotation.get_annotation(table_name=\"nuclei_v1\",\n",
    "                                 annotation_ids=[7416439, 7415718])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No segment IDs will be assigned to the annotations through this interface. To access annotations with segment IDs assigned, one must use the [materialization interface](https://github.com/seung-lab/CAVEclient/blob/master/FlyWireSynapseTutorial.ipynb).\n",
    "\n",
    "For this to work, at least one materialization run has to complete after the upload. Currently, materialization happen every to every second date."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}