4. NeuroHub Tools and Tasks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# NeuroHub Tools and Tasks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0. Set up boilerplate\n",
    "\n",
    "Make sure the optional package is installed then import the packages we'll use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install requests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import json"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All API requests are done with respect to the `base_url` and with the API token from [NeuroHub New API Token](https://portal.neurohub.ca/nh_users/new_token)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "base_url = 'https://portal.cbrain.mcgill.ca'\n",
    "cbrain_api_token = \"PASTE_NEUROHUB_API_TOKEN_HERE\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Session\n",
    "\n",
    "Do we have a valid session?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session_response = requests.post(\n",
    "    url = '/'.join([base_url, 'session']),\n",
    "    data = {'cbrain_api_token': cbrain_api_token},\n",
    "    headers = {'Accept': 'application/json'}\n",
    ")\n",
    "\n",
    "if session_response.status_code != requests.codes.ok:\n",
    "    print('Session is not valid.')\n",
    "    print(json.dumps(session_response.json(), indent=4))\n",
    "else:\n",
    "    print('Session is valid.')\n",
    "    session_info = session_response.json()\n",
    "    user_id = str(session_info['user_id'])\n",
    "    print(\"User ID:\", user_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Tool Configs / Pipelines\n",
    "\n",
    "List all possible pipelines.  That is, list all tool configurations where a particular tool can run on a particular bourreau."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tool_configs = []\n",
    "tool_configs_request = {\n",
    "    'cbrain_api_token': cbrain_api_token,\n",
    "    'page': 1,\n",
    "    'per_page': 1000\n",
    "}\n",
    "\n",
    "while True:\n",
    "\n",
    "    tool_configs_response = requests.get(\n",
    "        url = '/'.join([base_url, 'tool_configs']),\n",
    "        data = tool_configs_request,\n",
    "        headers = {'Accept': 'application/json'}\n",
    "    )\n",
    "\n",
    "    if tool_configs_response.status_code != requests.codes.ok:\n",
    "        print('Tools request failed.')\n",
    "        print(tool_configs_response)\n",
    "        break\n",
    "\n",
    "    tool_configs += tool_configs_response.json()\n",
    "    tool_configs_request['page'] += 1\n",
    "    \n",
    "    if len(tool_configs_response.json()) < tool_configs_request['per_page']:\n",
    "        break \n",
    "    \n",
    "print(\"{} tool configs found\\n\".format(str(len(tool_configs))))\n",
    "print(json.dumps(tool_configs, indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we did before with user files, we can now filter the tools by words in their description. Let's filter to find all tools with the word `FSL` in the description. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tool_configs_filtered = list(filter(lambda f: 'FSL' in f['description'], tool_configs))\n",
    "print(json.dumps(tool_configs_filtered, indent=4))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tool_config_721 = list(filter(lambda f: f['id'] == 721, tool_configs))\n",
    "print(json.dumps(tool_config_721, indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use the `tool_id` and `bourreau_id` to get information about these and verify this is the correct pipeline you wish to use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tools_response = requests.get(\n",
    "    url = '/'.join([base_url, 'tools']),\n",
    "    data = {'cbrain_api_token': cbrain_api_token},\n",
    "    headers = {'Accept': 'application/json'}\n",
    ")\n",
    "tool_51 = list(filter(lambda f: f['id'] == 51, tools_response.json()))\n",
    "print(json.dumps(tool_51, indent=4))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bourreaux_response = requests.get(\n",
    "    url = '/'.join([base_url, 'bourreaux', str(39)]),\n",
    "    data = {'cbrain_api_token': cbrain_api_token},\n",
    "    headers = {'Accept': 'application/json'}\n",
    ")\n",
    "print(json.dumps(bourreaux_response.json(), indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Submit a task"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's submit a task as ourselves (`user_id`) using the tool config we looked at above (`721`) with an example file as input and then output the results to MainStore."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user_id = PASTE_YOUR_USER_ID_HERE\n",
    "tool_config_id = 721\n",
    "file_id = 3319815  # An example T1 weighted NIfTI file\n",
    "data_provider_id = 27  # MainStore\n",
    "\n",
    "task_headers = {\n",
    "    'Content-Type': 'application/json',\n",
    "    'Accept': 'application/json',\n",
    "}\n",
    "task_params = (\n",
    "    ('cbrain_api_token', cbrain_api_token),\n",
    ")\n",
    "\n",
    "# Specify the parameters of the task in a dictionary.\n",
    "# We are running FSLFirst to register the brain scan.\n",
    "task_data = {\n",
    "  \"cbrain_task\": {\n",
    "    'type': 'CbrainTask::FslFirst', \n",
    "    'user_id': user_id,\n",
    "    'tool_config_id': tool_config_id,\n",
    "    'params': { \n",
    "      # These parameters depend on the tool used\n",
    "      'interface_userfile_ids': [file_id], \n",
    "      'input_file': file_id, \n",
    "      'prefix': 'output', \n",
    "      'brain_extracted': False, \n",
    "      'three_stage': False, \n",
    "      'verbose': False       \n",
    "    }, \n",
    "    'run_number': None, \n",
    "    'results_data_provider_id': data_provider_id, \n",
    "    'cluster_workdir_size': None, \n",
    "    'workdir_archived': True, \n",
    "    'description': 'My test task!'}\n",
    "}\n",
    "\n",
    "task_response = requests.post(\n",
    "    url = '/'.join([base_url, 'tasks']),\n",
    "    headers = task_headers, \n",
    "    params = task_params,\n",
    "    data = json.dumps(task_data)\n",
    ")\n",
    "\n",
    "if task_response.status_code == 200:\n",
    "    task_info = task_response.json()\n",
    "    print(json.dumps(task_info, indent=4))\n",
    "else:\n",
    "    print(\"Task posting failed.\")\n",
    "    print(task_response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's track the completion of the task."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "taskID = task_info[0][\"id\"]\n",
    "\n",
    "task_status = requests.get(\n",
    "    url = '/'.join([base_url, 'tasks', str(taskID)]),\n",
    "    data = {'cbrain_api_token': cbrain_api_token},\n",
    "    headers = {'Accept': 'application/json'}\n",
    ")\n",
    "\n",
    "if task_status.status_code == 200:\n",
    "    print(json.dumps(task_status.json(), indent=4))\n",
    "else:\n",
    "    print(\"Task status retrieval failed.\")\n",
    "    print(task_status.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Destroy the session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session_destroy_response = requests.delete(\n",
    "    url= '/'.join([base_url, 'session']),\n",
    "    data = {'cbrain_api_token': cbrain_api_token},\n",
    "    headers = {'Accept': 'application/json'}\n",
    ")\n",
    "\n",
    "if session_destroy_response.status_code == requests.codes.ok:\n",
    "    print(\"Session ended.\")\n",
    "else:\n",
    "    print(\"Session failure.\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.1 64-bit",
   "metadata": {
    "interpreter": {
     "hash": "ac2eaa0ea0ebeafcc7822e65e46aa9d4f966f30b695406963e145ea4a91cd4fc"
    }
   },
   "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.1-final"
  },
  "orig_nbformat": 2
 },
 "nbformat": 4,
 "nbformat_minor": 2
}