bioblend.objects_histories.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Interacting with histories in BioBlend.objects\n",
    "==============================================\n",
    "\n",
    "**You need to insert the API key for your Galaxy server in the cell below**:\n",
    "1. Open the Galaxy server in another browser tab\n",
    "2. Click on \"User\" on the top menu, then \"Preferences\"\n",
    "3. Click on \"Manage API key\"\n",
    "4. Generate an API key if needed, then copy the alphanumeric string and paste it as the value of the `api_key` variable below.\n",
    "\n",
    "The user interacts with a Galaxy server through a `GalaxyInstance` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pprint import pprint\n",
    "\n",
    "import bioblend.galaxy.objects\n",
    "\n",
    "server = 'https://usegalaxy.eu/'\n",
    "api_key = ''\n",
    "gi = bioblend.galaxy.objects.GalaxyInstance(url=server, api_key=api_key)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All `GalaxyInstance` method calls have the `client.method()` format, where `client` is the name of the resources you dealing with. There are 2 methods to get the list of resources:\n",
    "\n",
    "- `get_previews()`: lightweight (one GET request), retrieves basic resources' info, returns a list of **preview** objects\n",
    "- `list()`: one GET request for each resource, retrieves full resources' info, returns a list of **full** objects.\n",
    "\n",
    "For example, the call to retrieve previews of all histories owned by the current user is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[HistoryPreview({'url': '/api/histories/effec70bec8ba12c', 'published': False, 'model_class': 'History', 'name': 'New history', 'purged': False, 'update_time': '2021-06-14T17:37:39.244709', 'annotation': None, 'deleted': False, 'tags': [], 'id': 'effec70bec8ba12c'}),\n",
      " HistoryPreview({'url': '/api/histories/49e446c3d6585583', 'published': False, 'model_class': 'History', 'name': 'Unnamed history', 'purged': False, 'update_time': '2021-06-05T00:59:39.370164', 'annotation': None, 'deleted': False, 'tags': [], 'id': '49e446c3d6585583'})]\n"
     ]
    }
   ],
   "source": [
    "pprint(gi.histories.get_previews())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**New resources** are created with `create()` methods, e.g. to create a new history:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "History({'size': 0, 'username_and_slug': None, 'contents_url': '/api/histories/798421cbda432db0/contents', 'state_details': {'new': 0, 'upload': 0, 'queued': 0, 'running': 0, 'ok': 0, 'empty': 0, 'error': 0, 'discarded': 0, 'paused': 0, 'setting_metadata': 0, 'failed_metadata': 0}, 'importable': False, 'empty': True, 'id': '798421cbda432db0', 'published': False, 'genome_build': None, 'purged': False, 'user_id': 'bc81cbee8402ca0a', 'update_time': '2021-06-15T22:39:48.680088', 'name': 'BioBlend test', 'slug': None, 'tags': [], 'deleted': False, 'annotation': None, 'model_class': 'History', 'url': '/api/histories/798421cbda432db0', 'state': 'new', 'state_ids': {'new': [], 'upload': [], 'queued': [], 'running': [], 'ok': [], 'empty': [], 'error': [], 'discarded': [], 'paused': [], 'setting_metadata': [], 'failed_metadata': []}, 'create_time': '2021-06-15T22:39:48.689370'})"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_hist = gi.histories.create(name='BioBlend test')\n",
    "new_hist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the `create()` methods in BioBlend.objects returns an object, not a dictionary.\n",
    "\n",
    "Both `get_previews()` and `list()` methods usually have **filtering** capabilities, e.g. it is possible to filter histories **by name**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[History({'username_and_slug': None, 'state_ids': {'new': [], 'upload': [], 'queued': [], 'running': [], 'ok': [], 'empty': [], 'error': [], 'discarded': [], 'paused': [], 'setting_metadata': [], 'failed_metadata': []}, 'tags': [], 'size': 0, 'slug': None, 'contents_url': '/api/histories/798421cbda432db0/contents', 'importable': False, 'annotation': None, 'purged': False, 'create_time': '2021-06-15T22:39:48.689370', 'url': '/api/histories/798421cbda432db0', 'id': '798421cbda432db0', 'published': False, 'state': 'new', 'deleted': False, 'model_class': 'History', 'genome_build': None, 'empty': True, 'name': 'BioBlend test', 'state_details': {'new': 0, 'upload': 0, 'queued': 0, 'running': 0, 'ok': 0, 'empty': 0, 'error': 0, 'discarded': 0, 'paused': 0, 'setting_metadata': 0, 'failed_metadata': 0}, 'user_id': 'bc81cbee8402ca0a', 'update_time': '2021-06-15T22:39:48.680088'})]\n"
     ]
    }
   ],
   "source": [
    "hists = gi.histories.list(name='BioBlend test')\n",
    "pprint(hists)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both `HistoryPreview` and `History` objects have many of their properties available as **attributes**, e.g. the id.\n",
    "\n",
    "If you need to specify the unique **id** of the resource to retrieve, you can use the `get()` method, e.g. to get back the history we created before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "798421cbda432db0\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "History({'size': 0, 'username_and_slug': None, 'contents_url': '/api/histories/798421cbda432db0/contents', 'state_details': {'new': 0, 'upload': 0, 'queued': 0, 'running': 0, 'ok': 0, 'empty': 0, 'error': 0, 'discarded': 0, 'paused': 0, 'setting_metadata': 0, 'failed_metadata': 0}, 'importable': False, 'empty': True, 'id': '798421cbda432db0', 'published': False, 'genome_build': None, 'purged': False, 'user_id': 'bc81cbee8402ca0a', 'update_time': '2021-06-15T22:39:48.680088', 'name': 'BioBlend test', 'slug': None, 'tags': [], 'deleted': False, 'annotation': None, 'model_class': 'History', 'url': '/api/histories/798421cbda432db0', 'state': 'new', 'state_ids': {'new': [], 'upload': [], 'queued': [], 'running': [], 'ok': [], 'empty': [], 'error': [], 'discarded': [], 'paused': [], 'setting_metadata': [], 'failed_metadata': []}, 'create_time': '2021-06-15T22:39:48.689370'})"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hist0_id = hists[0].id\n",
    "print(hist0_id)\n",
    "h = gi.histories.get(hist0_id)\n",
    "h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To **upload** files to the new history, run the special upload tool by calling the `upload_file` method of the `History` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "HistoryDatasetAssociation({'file_size': 0, 'extension': 'auto', 'rerunnable': False, 'copied_from_ldda_id': None, 'file_name': '', 'type': 'file', 'display_apps': [], 'id': '11ac94870d0bb33a41b665e0f2cde8b3', 'visible': True, 'uuid': 'c1f6ef61-80f9-43c6-90b5-d65db8bb1131', 'genome_build': '?', 'validated_state': 'unknown', 'purged': False, 'update_time': '2021-06-15T22:55:06.241142', 'accessible': True, 'dataset_id': '11ac94870d0bb33aa1a95873375dcfcd', 'validated_state_message': None, 'history_id': '798421cbda432db0', 'created_from_basename': None, 'name': '1.txt', 'tags': [], 'deleted': False, 'meta_files': [], 'resubmitted': False, 'permissions': {'manage': ['6aee96f19774f31b'], 'access': ['6aee96f19774f31b']}, 'annotation': None, 'model_class': 'HistoryDatasetAssociation', 'data_type': 'galaxy.datatypes.data.Data', 'download_url': '/api/histories/798421cbda432db0/contents/11ac94870d0bb33a41b665e0f2cde8b3/display', 'url': '/api/histories/798421cbda432db0/contents/11ac94870d0bb33a41b665e0f2cde8b3', 'state': 'queued', 'file_ext': 'auto', 'peek': None, 'display_types': [], 'creating_job': '11ac94870d0bb33a045f66bced2ee6dc', 'history_content_type': 'dataset', 'hda_ldda': 'hda', 'visualizations': [{'name': 'editor', 'html': 'Editor', 'description': 'Manually edit text', 'logo': None, 'title': None, 'target': 'galaxy_main', 'embeddable': False, 'entry_point': {'type': 'mako', 'file': 'editor.mako', 'attr': {}}, 'settings': None, 'groups': None, 'specs': None, 'href': '/plugins/visualizations/editor/show'}], 'create_time': '2021-06-15T22:55:06.214404', 'api_type': 'file', 'hid': 1, 'type_id': 'dataset-11ac94870d0bb33a41b665e0f2cde8b3', 'misc_blurb': None, 'misc_info': None, 'metadata_dbkey': '?'})"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "h.upload_file('test-data/1.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get the list of **datasets contained** in a history, simply look at the `content_infos` attribute of the `History` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[HistoryContentInfo({'dataset_id': '11ac94870d0bb33aa1a95873375dcfcd', 'visible': True, 'tags': [], 'hid': 1, 'type': 'file', 'history_content_type': 'dataset', 'purged': False, 'url': '/api/histories/798421cbda432db0/contents/11ac94870d0bb33a41b665e0f2cde8b3', 'create_time': '2021-06-15T22:55:06.214404', 'name': '1.txt', 'extension': 'auto', 'state': 'queued', 'deleted': False, 'history_id': '798421cbda432db0', 'id': '11ac94870d0bb33a41b665e0f2cde8b3', 'type_id': 'dataset-11ac94870d0bb33a41b665e0f2cde8b3', 'update_time': '2021-06-15T22:55:06.241142'})]\n"
     ]
    }
   ],
   "source": [
    "hdas = h.content_infos\n",
    "pprint(hdas)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get the details about one dataset, you can use the `get_dataset()` method of the `History` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "11ac94870d0bb33a41b665e0f2cde8b3\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "HistoryDatasetAssociation({'file_size': 16, 'extension': 'txt', 'rerunnable': False, 'copied_from_ldda_id': None, 'file_name': '/data/dnb03/galaxy_db/files/c/1/f/dataset_c1f6ef61-80f9-43c6-90b5-d65db8bb1131.dat', 'type': 'file', 'display_apps': [], 'id': '11ac94870d0bb33a41b665e0f2cde8b3', 'visible': True, 'uuid': 'c1f6ef61-80f9-43c6-90b5-d65db8bb1131', 'genome_build': '?', 'validated_state': 'unknown', 'purged': False, 'update_time': '2021-06-15T22:56:52.442295', 'accessible': True, 'dataset_id': '11ac94870d0bb33aa1a95873375dcfcd', 'validated_state_message': None, 'history_id': '798421cbda432db0', 'created_from_basename': None, 'name': '1.txt', 'tags': [], 'deleted': False, 'meta_files': [], 'resubmitted': False, 'permissions': {'manage': ['6aee96f19774f31b'], 'access': ['6aee96f19774f31b']}, 'annotation': None, 'model_class': 'HistoryDatasetAssociation', 'data_type': 'galaxy.datatypes.data.Text', 'download_url': '/api/histories/798421cbda432db0/contents/11ac94870d0bb33a41b665e0f2cde8b3/display', 'url': '/api/histories/798421cbda432db0/contents/11ac94870d0bb33a41b665e0f2cde8b3', 'state': 'ok', 'file_ext': 'txt', 'peek': '<table cellspacing=\"0\" cellpadding=\"3\"><tr><td>1 a</td></tr><tr><td>2 b</td></tr><tr><td>3 c</td></tr><tr><td>4 d</td></tr></table>', 'display_types': [], 'creating_job': '11ac94870d0bb33a045f66bced2ee6dc', 'history_content_type': 'dataset', 'hda_ldda': 'hda', 'visualizations': [{'name': 'editor', 'html': 'Editor', 'description': 'Manually edit text', 'logo': None, 'title': None, 'target': 'galaxy_main', 'embeddable': False, 'entry_point': {'type': 'mako', 'file': 'editor.mako', 'attr': {}}, 'settings': None, 'groups': None, 'specs': None, 'href': '/plugins/visualizations/editor/show'}, {'name': 'graphviz', 'html': 'Graph Visualization', 'description': 'Cytoscape-based graph visualization plugin.', 'logo': None, 'title': None, 'target': 'galaxy_main', 'embeddable': True, 'entry_point': {'type': 'mako', 'file': 'graphviz.mako', 'attr': {}}, 'settings': None, 'groups': None, 'specs': None, 'href': '/plugins/visualizations/graphviz/show'}, {'name': 'msa', 'html': 'Multiple Sequence Alignment', 'description': 'The MSA viewer is a modular, reusable component to visualize large MSAs interactively on the web.', 'logo': './static/plugins/visualizations/msa/static/logo.png', 'title': None, 'target': 'galaxy_main', 'embeddable': True, 'entry_point': {'type': 'chart', 'file': None, 'attr': {'src': 'script.js'}}, 'settings': [{'label': 'Show conservation', 'name': 'conserv', 'help': 'Do you want to display a bar diagram indicating sequence conservation?', 'type': 'boolean', 'value': 'true'}, {'label': 'Show overview box', 'name': 'overviewbox', 'help': 'Do you want to display the overview box below the sequence alignments?', 'type': 'boolean', 'value': 'true'}, {'label': 'Show interactive menu', 'name': 'menu', 'help': 'Do you want to show a menu for interactive configuration?', 'type': 'boolean', 'value': 'true'}], 'groups': None, 'specs': None, 'href': '/plugins/visualizations/msa/show'}], 'create_time': '2021-06-15T22:55:06.214404', 'api_type': 'file', 'hid': 1, 'type_id': 'dataset-11ac94870d0bb33a41b665e0f2cde8b3', 'misc_blurb': '4 lines', 'misc_info': 'uploaded txt file', 'metadata_dbkey': '?', 'metadata_data_lines': 4})"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hda0_id = hdas[0].id\n",
    "print(hda0_id)\n",
    "h.get_dataset(hda0_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also filter history datasets by name using the `get_datasets()` method of `History` objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To **update** a resource, use the `update()` method of its object, e.g. to change the history name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "History({'size': 16, 'username_and_slug': None, 'contents_url': '/api/histories/798421cbda432db0/contents', 'state_details': {'new': 0, 'upload': 0, 'queued': 0, 'running': 0, 'ok': 1, 'empty': 0, 'error': 0, 'discarded': 0, 'paused': 0, 'setting_metadata': 0, 'failed_metadata': 0}, 'importable': False, 'empty': False, 'id': '798421cbda432db0', 'published': False, 'genome_build': None, 'purged': False, 'user_id': 'bc81cbee8402ca0a', 'update_time': '2021-06-15T23:01:22.380256', 'name': 'Updated history', 'slug': None, 'tags': [], 'deleted': False, 'annotation': None, 'model_class': 'History', 'url': '/api/histories/798421cbda432db0', 'state': 'ok', 'state_ids': {'new': [], 'upload': [], 'queued': [], 'running': [], 'ok': ['11ac94870d0bb33a41b665e0f2cde8b3'], 'empty': [], 'error': [], 'discarded': [], 'paused': [], 'setting_metadata': [], 'failed_metadata': []}, 'create_time': '2021-06-15T22:39:48.689370'})"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_hist.update(name='Updated history')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The return value of `update()` methods is the updated object.\n",
    "\n",
    "Finally to **delete** a resource, you can use the `delete()` method of the object, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_hist.delete()"
   ]
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}