Fetch_analyses_Mgnify.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "c77864f8-222e-4907-94f7-dc6711e2f7a6",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "title: \"Fetch Analyses metadata for a MGnify Study\"\n",
    "author:\n",
    "  - name: Sandy Rogers\n",
    "    affiliation:\n",
    "      - id: ebi-emg\n",
    "        name: MGnify team at EMBL-EBI\n",
    "  - editor: Sebastian Ayala\n",
    "categories: [R]\n",
    "execute: \n",
    "  eval: true\n",
    "---"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "7a3bebb3-f8e6-4a1b-adbf-46dd1f0f4791",
   "metadata": {},
   "source": [
    "# Fetch a Study using MGnifyR; download the metadata for all of its Analyses\n",
    "\n",
    "The [MGnify API](https://www.ebi.ac.uk/metagenomics/api/v1) returns data and relationships as JSON. \n",
    "[MGnifyR](https://github.com/beadyallen/MGnifyR) is a package to help you read MGnify data into your R analyses.\n",
    "\n",
    "**This example shows you how fetch the Analyses for a Study into a Phyloseq object**\n",
    "\n",
    "You can find all of the other \"API endpoints\" using the [Browsable API interface in your web browser](https://www.ebi.ac.uk/metagenomics/api/v1).\n",
    "\n",
    "This is an interactive code notebook (a Jupyter Notebook).\n",
    "To run this code, click into each cell and press the ▶ button in the top toolbar, or press `shift+enter`.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f1e0d181-f8cf-44e6-ad85-d1199cf8cf5e",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "source(\"lib/variable_utils.r\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "dc08608b-fa6d-4e33-b50c-c484985d664d",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Loading required package: permute\n",
      "\n",
      "Loading required package: lattice\n",
      "\n",
      "This is vegan 2.6-4\n",
      "\n"
     ]
    }
   ],
   "source": [
    "library(vegan)\n",
    "library(ggplot2)\n",
    "library(phyloseq)\n",
    "\n",
    "library(MGnifyR)\n",
    "\n",
    "mg <- mgnify_client(usecache = T, cache_dir = '/home/jovyan/.mgnify_cache')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9ab120a0-a52b-4743-b7bd-330ef8b86c08",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1] ‘0.1.0’"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "packageVersion('MGnifyR')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "908b1c3a-0c06-456c-8d5b-af3dddd020ca",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "# Help with MGnifyR\n",
       "\n",
       "MGnifyR is an R package that provides a convenient way for R users to access data from [the MGnify API](https://www.ebi.ac.uk/metagenomics/api/).\n",
       "\n",
       "Detailed help for each function is available in R using the standard `?function_name` command (i.e. typing `?mgnify_query` will bring up built-in help for the mgnify_query command). \n",
       "\n",
       "A vignette is available containing a reasonably verbose overview of the main functionality. \n",
       "This can be read either within R with the `vignette(\"MGnifyR\")` command, or [in the development repository](https://htmlpreview.github.io/?https://github.com/beadyallen/MGnifyR/blob/master/doc/MGnifyR.html)\n",
       "\n",
       "## MGnifyR Command cheat sheet\n",
       "\n",
       "The following list of key functions should give a starting point for finding relevent documentation.\n",
       "\n",
       "- `mgnify_client()` : Create the client object required for all other functions.\n",
       "- `mgnify_query()` : Search the whole MGnify database.\n",
       "- `mgnify_analyses_from_xxx()` : Convert xxx accessions to analyses accessions. xxx is either samples or studies.\n",
       "- `mgnify_get_analyses_metadata()` : Retrieve all study, sample and analysis metadata for given analyses.\n",
       "- `mgnify_get_analyses_phyloseq()` : Convert abundance, taxonomic, and sample metadata into a single phyloseq object.\n",
       "- `mgnify_get_analyses_results()` : Get functional annotation results for a set of analyses.\n",
       "- `mgnify_download()` : Download raw results files from MGnify.\n",
       "- `mgnify_retrieve_json()` : Low level API access helper function.\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "library(IRdisplay)\n",
    "display_markdown(file = '../_resources/mgnifyr_help.md')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "4f550128-14f7-4073-9477-0a8f97ac2129",
   "metadata": {
    "tags": [],
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Set the study accesion\n",
    "mgnify_study_accession <- \"MGYS00005779\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc11eea1-73ed-4751-92e9-aa0ba4b265a5",
   "metadata": {},
   "source": [
    "## Fetch a list of the Analyses for the Study"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cba3d4ff-d90d-4388-9466-1c3f2f8f9b7c",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "analyses_accessions <- mgnify_analyses_from_studies(mg, mgnify_study_accession)\n",
    "analyses_accessions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ecbc81f-92e0-49c9-8228-286e12102ff1",
   "metadata": {},
   "source": [
    "## Download metadata for the first all the analyses\n",
    "...and put it into a dataframe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "76681960-a132-4809-ab20-fe322f86113c",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "analyses_metadata_df <- mgnify_get_analyses_metadata(mg, head(analyses_accessions));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b701c68-84c7-4ccb-bb17-aeec07b91543",
   "metadata": {},
   "source": [
    "## Display metadata\n",
    "The table could be big, so let's look at a sample of it (`head`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6ba3ec9b-2b82-4706-9da7-a2f1300ddbc0",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "t(head(analyses_metadata_df))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16d68d53-584a-422b-ad26-a4c1e0fd4b6b",
   "metadata": {},
   "source": [
    "## Convert to [phyloseq](https://joey711.github.io/phyloseq/)\n",
    "> The phyloseq package is a tool to import, store, analyze, and graphically display complex phylogenetic sequencing data that has already been clustered into Operational Taxonomic Units (OTUs), especially when there is associated sample data, phylogenetic tree, and/or taxonomic assignment of the OTUs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "991c1f1e-1780-45a1-aab0-e990439848fa",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "Colomb_forest_metag_phy <- mgnify_get_analyses_phyloseq(mg, analyses_metadata_df$analysis_accession, tax_SU = \"SSU\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22ba24f3-f94b-45f0-bc9f-d2a300a78645",
   "metadata": {},
   "source": [
    "You can now use any of the `phyloseq` methods to explore this Study's Analyses (run `?phyloseq` in a code cell to learn more). \n",
    "\n",
    "You could also use further `MGnifyR` features, e.g. to download data. Check the Cheat Sheet at the top for more.\n",
    "\n",
    "Example of Phyloseq usage:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7313ccae-1fdd-4660-927d-c31f971efcd8",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Export the phyloseq object \n",
    "saveRDS(Colomb_forest_metag_phy, file = \"Colomb_forest_metag_phy.rds\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "R (mgnify-r-env)",
   "language": "R",
   "name": "conda-env-mgnify-r-env-r"
  },
  "language_info": {
   "codemirror_mode": "r",
   "file_extension": ".r",
   "mimetype": "text/x-r-source",
   "name": "R",
   "pygments_lexer": "r",
   "version": "4.2.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}