LORIS-API_Part2-Python-script.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# LORIS API Tour 2/2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "import getpass  # For input prompt not to show what is entered\n",
    "import json     # Provide convinent functions to handle json objects \n",
    "import re       # For regular expression\n",
    "import requests # To handle http requests\n",
    "\n",
    "import warnings\n",
    "warnings.simplefilter('ignore') # Because I am using unverified ssl certificates \n",
    "\n",
    "baseurl = 'https://demo.loris.ca/api/v0.0.3-dev' # Pick yours\n",
    "\n",
    "def prettyPrint(string):\n",
    "    print(json.dumps(string, indent=2, sort_keys=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 1. Login\n",
    "\n",
    "This is a POST request to the `/login` endpoint that requires 2 parameters: `username` and `password`  \n",
    "The expected response is a json string that contains a token property.  \n",
    "\n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#11-authentication"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "payload = {\n",
    "    'username': input('username: '), \n",
    "    'password': getpass.getpass('password: ')\n",
    "}\n",
    "\n",
    "response = requests.post(\n",
    "    url = baseurl + '/login',\n",
    "    json = payload,\n",
    "    verify = False\n",
    ")\n",
    "\n",
    "text = response.content.decode('ascii')\n",
    "\n",
    "data = json.loads(text)\n",
    "\n",
    "prettyPrint(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Store the token in a variable for later*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "token = data['token']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2. Get all candid\n",
    "\n",
    "This is a GET request to /candidates  \n",
    "\n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#30-candidate-api"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "response = json.loads(requests.get(\n",
    "    url = baseurl + '/candidates',\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "prettyPrint(response)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Using a for loop, print the candids\n",
    "candidates = response['Candidates']\n",
    "for candidate in candidates:\n",
    "    print(candidate['CandID'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 3. Create a candidate\n",
    " - Send a **POST** request to /candidates with a payload containing an object with a candidate property\n",
    " ```json\n",
    "    \"Candidate\" : {\n",
    "        \"Project\" : ProjectName,\n",
    "        \"PSCID\"   : PSCID, # only if config is set to prompt \n",
    "        \"EDC\"     : \"YYYY-MM-DD\", # if useEDC config is true (bug: always required)\n",
    "        \"DoB\"     : \"YYYY-MM-DD\",\n",
    "        \"Gender\"  : \"Male|Female\",\n",
    "        \"Site\"    : SiteName,\n",
    "    }\n",
    " ```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Find the project name and site name.\n",
    "projects = json.loads(requests.get(\n",
    "    url = baseurl + '/projects',\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))\n",
    "\n",
    "prettyPrint(projects)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "projectname = list(projects['Projects'])[0]\n",
    "\n",
    "# TODO:: There is no way to know the existing sites of a LORIS instance with the API\n",
    "sitename = 'Montreal'\n",
    "\n",
    "json_data = {\n",
    "    'Candidate' : {\n",
    "        'Project' : projectname,\n",
    "        'DoB'     : \"2015-09-10\",\n",
    "        'EDC'     : \"2015-09-10\", #EDC seems to be always required even when useEDC is false...\n",
    "        'Gender'  : \"Female\",\n",
    "        'Site'    : sitename,\n",
    "    }\n",
    "}\n",
    "\n",
    "r = requests.post(\n",
    "    url = baseurl + '/candidates/',\n",
    "    json = json_data,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ")\n",
    "print(r)\n",
    "print(r.headers)\n",
    "print(r.content.decode('ascii'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Get the new candidate\n",
    "candid = json.loads(r.content.decode('ascii'))['CandID']\n",
    "\n",
    "newcandidate = json.loads(requests.get(\n",
    "    url = baseurl + '/candidates/' + str(candid),\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))\n",
    "\n",
    "prettyPrint(newcandidate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 4. Add a timepoint to the new candidate\n",
    " - **PUT** request to /candidates/\\$candid/\\$visit_label\n",
    "```json\n",
    "{\n",
    "    \"Meta\" : {\n",
    "        \"CandID\" : CandID,\n",
    "        \"Visit\"  : VisitLabel,\n",
    "        \"Site\"   : SiteName,\n",
    "        \"Battery\": \"NameOfSubproject\"\n",
    "}\n",
    "```\n",
    "\n",
    " - VisitLabel can be found using /projects/\\$projectname (not realy; in fact, it is only every existing visit_labels...)\n",
    " - Battery (NameOfSubproject) must be guessed... "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "\n",
    "visitlabel = json.loads(requests.get(\n",
    "    url = baseurl + '/projects/' + projectname,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))['Visits'][0]\n",
    "\n",
    "print(visitlabel)\n",
    "\n",
    "json_data = {\n",
    "    'Meta' : {\n",
    "        'CandID' : candid,\n",
    "        'Visit'  : visitlabel,\n",
    "        'Site'   : sitename,\n",
    "        'Battery': \"Control\"\n",
    "    }\n",
    "}\n",
    "\n",
    "r = requests.put(\n",
    "    url = baseurl + '/candidates/' + str(candid) + '/' + visitlabel,\n",
    "    json = json_data,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ")\n",
    "print(r)\n",
    "print(r.content.decode('ascii'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "r = requests.get(\n",
    "    url = baseurl + '/candidates/' + str(candid) + '/' + visitlabel,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ")\n",
    "print(r)\n",
    "prettyPrint(json.loads(r.content.decode('ascii')))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*There is no way to start the visit ... *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 5. Input instrument data for a candidate\n",
    "  \n",
    "PUT or PATCH request to /candidates/$CandID/$VisitLabel/instruments/$InstrumentName  \n",
    "\n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#33-the-candidate-instrument-data\n",
    "\n",
    "data format:\n",
    "```json\n",
    "{\n",
    "  \"Meta\": {\n",
    "    \"Candidate\": string,\n",
    "    \"DDE\": true|false,\n",
    "    \"Instrument\": string,\n",
    "    \"Visit\": string\n",
    "  },\n",
    "  <instrument_name>: {\n",
    "    <field1_name>: <value1>,\n",
    "    <field2_name>: <value2>,\n",
    "    ...\n",
    "  }\n",
    "}\n",
    "```\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def getInstrumentData(candid, visit_label, instrument):\n",
    "    return json.loads(requests.get(\n",
    "        url = baseurl + '/candidates/' + candid + '/' + visit_label + '/instruments/' + instrument,\n",
    "        verify = False,\n",
    "        headers = {'Authorization': 'Bearer %s' % token}\n",
    "    ).content.decode('ascii'))\n",
    "    \n",
    "instrument = 'test_all_fields'\n",
    "candid = '279656'\n",
    "visit_label = 'V01'\n",
    "\n",
    "prettyPrint(getInstrumentData(candid, visit_label, instrument))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### PUT request containing all the fields"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Get all the fields an meta data\n",
    "json_input = getInstrumentData(candid, visit_label, instrument)\n",
    "\n",
    "# Update one field\n",
    "json_input[instrument]['numeric_1'] = 3\n",
    "\n",
    "r = requests.put(\n",
    "    url = baseurl + '/candidates/' + candid + '/' + visit_label + '/instruments/' + instrument,\n",
    "    json = json_input,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ")\n",
    "print(r.status_code) # <Response [500]> demo.loris.ca do not handle that on LORIS 16...\n",
    "\n",
    "prettyPrint(getInstrumentData(candid, visit_label, instrument))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "#### PATCH request containing some of the fields"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Get all the meta data\n",
    "old_values = getInstrumentData(candid, visit_label, instrument)\n",
    "new_values = {}\n",
    "new_values['Meta'] = old_values['Meta']\n",
    "\n",
    "# Add fields in the instrument object\n",
    "new_values[instrument] = {}\n",
    "new_values[instrument]['score_field_1'] = 42\n",
    "new_values[instrument]['textbox_1'] = 'One Ring to rule them all'\n",
    "\n",
    "prettyPrint(new_values)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "r = requests.patch(\n",
    "    url = baseurl + '/candidates/' + candid + '/' + visit_label + '/instruments/' + instrument,\n",
    "    json = new_values,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ")\n",
    "print(r.status_code) # <Response [500]> demo.loris.ca do not handle that on LORIS 16...\n",
    "\n",
    "prettyPrint(getInstrumentData(candid, visit_label, instrument))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 6. Find new images"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# This gets all the images\n",
    "r = json.loads(requests.get(\n",
    "    url = baseurl + '/projects/loris/images' ,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))\n",
    "prettyPrint(r)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This gets all the images inserted since 2018-12-13T10:20:18-05:00\n",
    "r = json.loads(requests.get(\n",
    "    url = baseurl + '/projects/loris/images?since=2018-12-13T10:20:18-05:00' ,\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))\n",
    "prettyPrint(r)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Exercise 7. Download minc files"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "candid = '279656'\n",
    "visit_label = 'V01'\n",
    "\n",
    "# Get all images from that candidate\n",
    "r = json.loads(requests.get(\n",
    "    url = baseurl + '/candidates/' + candid + '/' + visit_label + '/dicoms',\n",
    "    verify = False,\n",
    "    headers = {'Authorization': 'Bearer %s' % token}\n",
    ").content.decode('ascii'))\n",
    "\n",
    "prettyPrint(r)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for file in r['Files']:\n",
    "    filename = file['Filename']\n",
    "    image = requests.get(\n",
    "        url = baseurl + '/candidates/' + candid + '/' + visit_label + '/images/' + filename,\n",
    "        verify = False,\n",
    "        headers = {'Authorization': 'Bearer %s' % token}\n",
    "    )\n",
    "    mincfile = open(filename, \"w+b\")\n",
    "    mincfile.write(bytes(image.content))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 8. Find all candidates and session with a given instruments\n",
    "\n",
    "This is a series of GET request  \n",
    "\n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#31-specific-candidate  \n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#33-candidate-instruments   \n",
    "https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#33-the-candidate-instrument-data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "instrument = 'test_all_fields'\n",
    "request_count = 0\n",
    "\n",
    "for candidate in candidates:\n",
    "    candid = candidate['CandID']\n",
    "    response = json.loads(requests.get(\n",
    "        url = baseurl + '/candidates/' + candid,\n",
    "        verify = False,\n",
    "        headers = {'Authorization': 'Bearer %s' % token}\n",
    "    ).content.decode('ascii'))\n",
    "    request_count += 1\n",
    "    visit_labels = response['Visits']\n",
    "    for visit_label in visit_labels:\n",
    "        response = json.loads(requests.get(\n",
    "            url = baseurl + '/candidates/' + candid + '/' + visit_label + '/instruments',\n",
    "            verify = False,\n",
    "            headers = {'Authorization': 'Bearer %s' % token}\n",
    "        ).content.decode('ascii'))\n",
    "        request_count += 1\n",
    "        if instrument in response['Instruments']:\n",
    "            response = json.loads(requests.get(\n",
    "                url = baseurl + '/candidates/' + candid + '/' + visit_label + '/instruments/' + instrument,\n",
    "                verify = False,\n",
    "                headers = {'Authorization': 'Bearer %s' % token}\n",
    "            ).content.decode('ascii'))\n",
    "            request_count += 1\n",
    "            print(json.dumps(response, indent=2, sort_keys=True))\n",
    "            \n",
    "print(request_count)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "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.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}