{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ONE REST queries\n",
    "\n",
    "While the basic `one.search` command allows us to filter experimental sessions by date, lab,\n",
    "subject etc., you may quickly find that you want to apply more complex queries to restrict your\n",
    "search output. This can be achieved using the `one.alyx.rest` command. This has access to a range\n",
    "of tables stored in the database and gives us more flexibility when forming our queries.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "Note.\n",
    "\n",
    "REST queries can only be made while ONE is in online mode.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `one.search` vs `one.alyx.rest`\n",
    "We will get started by importing ONE"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:17.820349Z",
     "iopub.status.busy": "2021-09-07T19:18:17.818785Z",
     "iopub.status.idle": "2021-09-07T19:18:25.367158Z",
     "shell.execute_reply": "2021-09-07T19:18:25.368189Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.735396500Z",
     "start_time": "2023-08-31T12:59:40.597624800Z"
    }
   },
   "outputs": [],
   "source": [
    "from one.api import ONE\n",
    "one = ONE(base_url='https://openalyx.internationalbrainlab.org')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can list the possible tables that we have access to, by typing the following command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:25.374778Z",
     "iopub.status.busy": "2021-09-07T19:18:25.373781Z",
     "iopub.status.idle": "2021-09-07T19:18:25.497210Z",
     "shell.execute_reply": "2021-09-07T19:18:25.499365Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.827407Z",
     "start_time": "2023-08-31T12:59:42.740384400Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "['brain-regions',\n 'cache',\n 'cache.zip',\n 'channels',\n 'chronic-insertions',\n 'data-formats',\n 'data-repository',\n 'data-repository-type',\n 'dataset-types',\n 'datasets',\n 'downloads',\n 'fields-of-view',\n 'files',\n 'fov-location',\n 'imaging-stack',\n 'insertions',\n 'labs',\n 'locations',\n 'new-download',\n 'notes',\n 'procedures',\n 'projects',\n 'register-file',\n 'revisions',\n 'sessions',\n 'subjects',\n 'surgeries',\n 'sync-file-status',\n 'tags',\n 'tasks',\n 'trajectories',\n 'uploaded',\n 'users',\n 'water-administrations',\n 'water-requirement',\n 'water-restricted-subjects',\n 'water-restriction',\n 'water-type',\n 'weighings']"
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "one.alyx.list_endpoints()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's first look at `sessions` table. The information about what filters can be applied to this\n",
    "table are available under FILTERS\n",
    "[here](https://openalyx.internationalbrainlab.org/docs/#sessions-list). Let's apply a filter based\n",
    "on `performance_qte` and `task_protocol`. We can do this using the following expression,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:25.508848Z",
     "iopub.status.busy": "2021-09-07T19:18:25.507851Z",
     "iopub.status.idle": "2021-09-07T19:18:25.787152Z",
     "shell.execute_reply": "2021-09-07T19:18:25.788140Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.834965700Z",
     "start_time": "2023-08-31T12:59:42.772721400Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "{'id': 'ae8787b1-4229-4d56-b0c2-566b61a25b77',\n 'subject': 'NR_0027',\n 'start_time': '2022-08-23T09:26:09',\n 'number': 1,\n 'lab': 'steinmetzlab',\n 'projects': ['ibl_neuropixel_brainwide_01'],\n 'url': 'https://openalyx.internationalbrainlab.org/sessions/ae8787b1-4229-4d56-b0c2-566b61a25b77',\n 'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.6.2'}"
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sess_info = one.alyx.rest('sessions', 'list', performance_gte=70, task_protocol='ephys')\n",
    "sess_info[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how this command doesn't just return the session eID but a dictionary containing information\n",
    "about each session. We can extract the set of eIDs using the `to_eid` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:25.858699Z",
     "iopub.status.busy": "2021-09-07T19:18:25.857504Z",
     "iopub.status.idle": "2021-09-07T19:18:25.867806Z",
     "shell.execute_reply": "2021-09-07T19:18:25.870206Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.905711Z",
     "start_time": "2023-08-31T12:59:42.815966200Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "'ae8787b1-4229-4d56-b0c2-566b61a25b77'"
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "one.to_eid(sess_info[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might have noticed that this same query could have been achieved using the `one.search` method\n",
    "with the [remote query flag](../one_modes/one_modes.html),"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:25.935903Z",
     "iopub.status.busy": "2021-09-07T19:18:25.934805Z",
     "iopub.status.idle": "2021-09-07T19:18:25.973269Z",
     "shell.execute_reply": "2021-09-07T19:18:25.975314Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.922632100Z",
     "start_time": "2023-08-31T12:59:42.864517700Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "<one.util.LazyId at 0x25ff516fc40>"
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "eids = one.search(performance_gte=70, task_protocol='ephys', query_type='remote')\n",
    "eids"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing other Alyx tables\n",
    "\n",
    "With the `one.alyx.rest` command we are not only limited to the `sessions` table, but can formulate\n",
    "queries based on other tables to find session eIDs of interest. Consider the case where we want to\n",
    "find all sessions that have probe insertions that target a specific ML and AP coordinate. For this\n",
    "we can formulate our query based on the\n",
    "[trajectories table](https://openalyx.internationalbrainlab.org/docs/#trajectories-list).\n",
    "Let's see if there are any probe insertions at the coordinates ML(x) = -2225, and AP(y) = -1894\n",
    "from bregma."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:26.386286Z",
     "iopub.status.busy": "2021-09-07T19:18:26.386286Z",
     "iopub.status.idle": "2021-09-07T19:18:26.667246Z",
     "shell.execute_reply": "2021-09-07T19:18:26.667836Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:42.991300500Z",
     "start_time": "2023-08-31T12:59:42.912658600Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "{'id': '05588582-01c9-4201-880a-8fb73ea8acea',\n 'probe_insertion': '6d3b68e0-3efd-4b03-b747-16e44118a0a9',\n 'x': 953.7,\n 'y': -1533.4,\n 'z': -211.1,\n 'depth': 6683.4,\n 'theta': 17.0,\n 'phi': 0.0,\n 'roll': 0.0,\n 'provenance': 'Micro-manipulator',\n 'session': {'subject': 'CSH_ZAD_001',\n  'start_time': '2020-01-16T15:53:21.500926',\n  'number': 1,\n  'lab': 'zadorlab',\n  'id': '3e7ae7c0-fe8b-487c-9354-036236fa1010',\n  'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'},\n 'probe_name': 'probe00',\n 'coordinate_system': None,\n 'datetime': '2020-06-09T07:59:14.315700',\n 'json': None,\n 'chronic_insertion': None}"
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trajs = one.alyx.rest('trajectories', 'list', x=953.7, y=-1533.4)\n",
    "trajs[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can find the session eID associated with this trajectory by looking at the `id` of the `session`\n",
    "field in the returned dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:26.675849Z",
     "iopub.status.busy": "2021-09-07T19:18:26.674849Z",
     "iopub.status.idle": "2021-09-07T19:18:26.690301Z",
     "shell.execute_reply": "2021-09-07T19:18:26.691190Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:43.010341900Z",
     "start_time": "2023-08-31T12:59:42.962729300Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "'3e7ae7c0-fe8b-487c-9354-036236fa1010'"
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "eid = trajs[0]['session']['id']\n",
    "eid"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note.\n",
    "\n",
    "It is not just sessions that have unique IDs associated with them! Every object stored in Alyx has\n",
    "a unique UUID, whether it is a trajectory, a subject, a user or a dataset. For example in the above\n",
    "example we can access the unique ID of the trajectory by typing `traj_id = trajs[0]['id']`\n",
    "\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Searching with `one.alyx.rest`\n",
    "The `one.alyx.rest` command is also provides an alternative method to `one.list` for searching\n",
    "the database for possible keywords that you can use to restrict your queries. For example, if we\n",
    " want to find the names of female subjects in the Witten lab that are alive, we can use the\n",
    " [subjects table](https://openalyx.internationalbrainlab.org/docs/#subjects-list) to write,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-09-07T19:18:26.700767Z",
     "iopub.status.busy": "2021-09-07T19:18:26.699330Z",
     "iopub.status.idle": "2021-09-07T19:18:27.214906Z",
     "shell.execute_reply": "2021-09-07T19:18:27.213232Z"
    },
    "ExecuteTime": {
     "end_time": "2023-08-31T12:59:43.091770600Z",
     "start_time": "2023-08-31T12:59:43.005264600Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "['KS004', 'KS005', 'KS017', 'KS018', 'KS019', 'KS023', 'KS024', 'KS025']"
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "subj_info = one.alyx.rest('subjects', 'list', lab='cortexlab', sex='F', alive=True)\n",
    "subj_nickname = [subj['nickname'] for subj in subj_info]\n",
    "subj_nickname"
   ]
  }
 ],
 "metadata": {
  "docs_executed": "executed",
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}