function_r.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "086b9b6f-1276-4649-a8ad-1d3cd6cec2cf",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Function getGeneNames()\n",
    "---\n",
    "This function takes a character vector of Ensembl IDs of one kind (gene, transcript, protein or exon stable IDs, also ID versions), and returns a vector with gene names (HGNC symbols) associated with those IDs:\n",
    "\n",
    "```R\n",
    "getGeneNames(ids, biomart.dt, strip.version=TRUE, gene.symbols=FALSE)\n",
    "```\n",
    "\n",
    "This function accepts 4 arguments:\n",
    "- `ids` - the input vector of Ensembl IDs\n",
    "- `biomart.dt` - the input Ensembl BioMart data on Ensembl IDs, must be provided as a data table\n",
    "- `strip.version=TRUE` - by default IDs are stripped off versions, change to _FLASE_ in the case ID versions are meant to be used\n",
    "- `gene.symbols=FALSE` - by default the input vector is interpreted as a vector of valid Ensembl IDs, for which HGNC symbols (gene symbols) are returned, change to _TRUE_ to use this function in an opposite way, i.e. to obtain Gene stable IDs for input gene symbols\n",
    "\n",
    "This function output ia a vector as described below:\n",
    "- The vector is of the same length as the input vector, and subsequent values of both vectors correspond to each other.\n",
    "- If a given ID exists but is not linked to any gene symbol, empty character value is returned.\n",
    "- If a given ID does not exist in the reference data, NA value is returned.\n",
    "- For every NA value in the input vector, NA value is returned.\n",
    "\n",
    "Data on IDs and HGNC symbols (BioMart data) must be obtained via [Ensembl BioMart](https://www.ensembl.org/biomart/martview) (see the enxt section) and provided as a data frame with unchanged column names.\n",
    "\n",
    "Examples:\n",
    "```R\n",
    "getGeneNames(\"ENSP00000354687\", biomart_dt)\n",
    "# Output: 'MT-ND1'\n",
    "\n",
    "getGeneNames(c(\"RAVER2\", \"MT-RNR1\"), biomart_dt, gene.symbols=TRUE)\n",
    "# Output: 'ENSG00000162437' 'ENSG00000211459'\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "The data on IDs is already saved in the input directory as _`mart_export_ids.tsv.gz`_. It can be redownloaded in the following way:\n",
    "- go to https://www.ensembl.org/biomart/martview\n",
    "- as `-CHOOSE DATABASE-` select `Ensembl Genes 109`\n",
    "- as `-CHOOSE DATASET-` select `Human Genes (GRCh38.p13)`\n",
    "- go to `Attributes` and in the section `GENES:` select:\n",
    "    - Gene stable ID\n",
    "    - Gene stable ID version\n",
    "    - Transcript stable ID\n",
    "    - Transcript stable ID version\n",
    "    - Protein stable ID\n",
    "    - Protein stable ID version\n",
    "    - Exon stable ID\n",
    "- and in the section `EXTERNALS:` (subsection _External References_) select:\n",
    "    - HGNC symbol\n",
    "- unselect other then listed above attributes in all sections if such were preselected\n",
    "- click the `Results` button\n",
    "- in `Export all results to` choose `Compressed file (.gz)`, `TSV`\n",
    "- check the option `Unique results only`\n",
    "- click the `Go` button\n",
    "- save the file in a location of your choosing\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "567c62f0-ef9f-4c4c-b089-b06877c61938",
   "metadata": {},
   "source": [
    "- Do the necessary imports:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "065e5ee1-375b-4f69-9b34-16d434aa6946",
   "metadata": {},
   "outputs": [],
   "source": [
    "library(\"data.table\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c9052b3-9507-4dfe-9e63-3f42e9f2d96c",
   "metadata": {},
   "source": [
    "- Define `getGeneNames()` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "bef064ea-2cf7-4625-b414-ee628c340836",
   "metadata": {},
   "outputs": [],
   "source": [
    "#' Get gene names (HGNC symbols) for Esembl IDs\n",
    "#'\n",
    "#' This function takes a character vector of Ensembl IDs of one kind\n",
    "#' (gene, transcript, protein or exon stable IDs, also ID versions),\n",
    "#' and returns a vector with gene names (HGNC symbols) associated with those IDs.\n",
    "#'\n",
    "#' @param ids The input vector of Ensembl IDs\n",
    "#' @param biomart.dt The input Ensembl BioMart data on Ensembl IDs, must be provided as a data table.\n",
    "#' @param strip.version=TRUE By default IDs are stripped off versions, change to FLASE in the case\n",
    "#'                          ID versions are meant to be used\n",
    "#' @param gene.symbols=FALSE By default the input vector is interpreted as a vector of valid Ensembl IDs,\n",
    "#'                         for which HGNC symbols (gene symbols) are returned, change to TRUE to use\n",
    "#'                         this function in an opposite way, i.e. to obtain Gene stable IDs\n",
    "#'                         for input gene symbols.\n",
    "#' @return The vector of corresponding gene names (HGNC symbols):\n",
    "#' The vector is of the same length as the input vector, and subsequent values of both vectors correspond to each other.\n",
    "#' If a given ID exists but is not linked to any gene symbol, empty character value is returned.\n",
    "#' If a given ID does not exist in the reference data, NA value is returned.\n",
    "#' For every NA value in the input vector, NA value is returned.\n",
    "#' @examples\n",
    "#' getGeneNames(\"ENSP00000354687\", biomart_dt)\n",
    "#' # Output: 'MT-ND1'\n",
    "#' getGeneNames(c(\"RAVER2\", \"MT-RNR1\"), biomart_dt, gene.symbols=True)\n",
    "#' # Output: 'ENSG00000162437' 'ENSG00000211459'\n",
    "getGeneNames <- function(ids, biomart.dt, strip.version=TRUE, gene.symbols=FALSE) {\n",
    "    # If ids in not a vector, throw en error.\n",
    "    if (!is.vector(ids)){\n",
    "        stop(\"Input data 'ids' is not a vector!\")\n",
    "    }\n",
    "\n",
    "    # Create a copy of ids input vector.\n",
    "    ids <- copy(ids)\n",
    "\n",
    "    # If strip.version is set to TRUE (default), version suffixes\n",
    "    # will be stripped, if present, from IDs (ids) values.\n",
    "    if (strip.version)\n",
    "        ids <- sub(\"\\\\.[^.]*$\", \"\", ids)\n",
    "\n",
    "    # The src_col is a column in biomart.dt that corresponds\n",
    "    # to the type of provided ids.\n",
    "    # Set the source column for biomart.dt to 'HGNC symbol'.\n",
    "    # It is preliminarily assumed that provided ids are gene symbols.\n",
    "    src_col <- \"HGNC symbol\"\n",
    "\n",
    "    # If gene.symbols is FALSE, valid Ensembl IDs are expected.\n",
    "    # Check the number of unique prefixes for ids.\n",
    "    # If there is only one, find out of which kind or throw an error.\n",
    "    # If there is more than one, throw an error.\n",
    "    if (!gene.symbols) {\n",
    "        id_types = unique( substr(ids[!is.na(ids)], 1, 4) )\n",
    "        if (length(id_types) == 1) {\n",
    "            src_col <- switch(id_types,\n",
    "                \"ENSG\" = \"Gene stable ID\",\n",
    "                \"ENST\" = \"Transcript stable ID\",\n",
    "                \"ENSP\" = \"Protein stable ID\",\n",
    "                \"ENSE\" = \"Exon stable ID\",\n",
    "                NA\n",
    "            )\n",
    "\n",
    "            if (is.na(src_col)) {\n",
    "                stop( paste(\"Unknown Ensembl ID prefix:\", paste(id_types, collapse=\", \")) )\n",
    "            }\n",
    "        }\n",
    "        else {\n",
    "            stop( paste(\"Mixed Ensembl ID types:\", paste(id_types, collapse=\", \"), \".\",\n",
    "                        \"Please provide IDs of the same type or\",\n",
    "                        \"set geneSymbols to TRUE in order to use gene symbols.\") )\n",
    "        }\n",
    "    }\n",
    "\n",
    "    # The out_col is a column in biomart.dt, values of which that\n",
    "    # correspond to provided ids will be placed in the output vector.\n",
    "    # By default it is 'HGNC symbol', unless gene.symbols is set to TRUE,\n",
    "    # then it is 'Gene stable ID'.\n",
    "    out_col <- if (!gene.symbols) \"HGNC symbol\" else \"Gene stable ID\"\n",
    "\n",
    "    # If versions are allowed, check whether all ids have versions.\n",
    "    # If everything is ok, add proper suffix to src_col, unless\n",
    "    # it is 'Exon stable ID', which does not have version,\n",
    "    # then again, throw an error.\n",
    "    if (!strip.version) {\n",
    "        contains_dot = grepl(\"\\\\.\", ids)\n",
    "        if ( any(contains_dot) ) {\n",
    "            if ( all(contains_dot) ) {\n",
    "                if (src_col != \"Exon stable ID\") {\n",
    "                    src_col <- paste(src_col, \"version\")\n",
    "                } else {\n",
    "                    stop(\"Exon stable IDs cannot be used with version designation.\")\n",
    "                }\n",
    "            } else {\n",
    "                stop( paste(\"Input data contains Ensembl IDs mixed with IDs with versions.\",\n",
    "                            \"Use only one or another, or set stripVersions to TRUE.\") )\n",
    "            }\n",
    "        }\n",
    "    }\n",
    "\n",
    "    # Convert ids into a data.table,\n",
    "    # give it the name src_col.\n",
    "    ids_dt <- data.table(col=ids)\n",
    "    setnames(ids_dt, \"col\", src_col)\n",
    "\n",
    "    # Create a copy of unique biomart.dt rows for src_col and out_col,\n",
    "    # and convert them in into a data.table\n",
    "    col_names <- c(src_col, out_col)\n",
    "    sub_dt <- data.table( copy( unique( biomart.dt[, ..col_names] ) ) )\n",
    "\n",
    "    # Group the resutling data.table by the column src_col,\n",
    "    # take unique of the groupped values from the column out_col,\n",
    "    # and finally paste them into one string.\n",
    "    # In short, when one ID is mapped to more than one gene symbol\n",
    "    # that ID will be mapped now to one character value of catenated symbols.\n",
    "\n",
    "    groupped_dt <- sub_dt[, .(col = paste( unique( get(out_col) ), collapse = \", \")), by=get(src_col)]\n",
    "    setnames(groupped_dt, \"get\", src_col)\n",
    "    setnames(groupped_dt, \"col\", out_col)\n",
    "\n",
    "    # Join groupped_dt with ids_dt on src_col.\n",
    "    # That should preserve the order of IDs as\n",
    "    # it is provided in the input vector ids.\n",
    "    merged_dt <- groupped_dt[ids_dt, on=src_col]\n",
    "\n",
    "    # Pick up and return the vector of gene names.\n",
    "    gene_names <- merged_dt[[out_col]]\n",
    "    return(gene_names)\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77530d99-c203-47d0-ab3a-8df17e47e73d",
   "metadata": {},
   "source": [
    "---\n",
    "# Test getGeneNames() function\n",
    "___\n",
    "- Load the BioMart data to a data frame, look up the dimensions and the first 5 rows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "290bbd29-7ad2-43e8-b882-46ffece12e29",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>1773418</li><li>8</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 1773418\n",
       "\\item 8\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 1773418\n",
       "2. 8\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "[1] 1773418       8"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<table class=\"dataframe\">\n",
       "<caption>A data.table: 6 × 8</caption>\n",
       "<thead>\n",
       "\t<tr><th scope=col>Gene stable ID</th><th scope=col>Gene stable ID version</th><th scope=col>Transcript stable ID</th><th scope=col>Transcript stable ID version</th><th scope=col>Protein stable ID</th><th scope=col>Protein stable ID version</th><th scope=col>Exon stable ID</th><th scope=col>HGNC symbol</th></tr>\n",
       "\t<tr><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th></tr>\n",
       "</thead>\n",
       "<tbody>\n",
       "\t<tr><td>ENSG00000210049</td><td>ENSG00000210049.1</td><td>ENST00000387314</td><td>ENST00000387314.1</td><td>               </td><td>                 </td><td>ENSE00001544501</td><td>MT-TF  </td></tr>\n",
       "\t<tr><td>ENSG00000211459</td><td>ENSG00000211459.2</td><td>ENST00000389680</td><td>ENST00000389680.2</td><td>               </td><td>                 </td><td>ENSE00001544499</td><td>MT-RNR1</td></tr>\n",
       "\t<tr><td>ENSG00000210077</td><td>ENSG00000210077.1</td><td>ENST00000387342</td><td>ENST00000387342.1</td><td>               </td><td>                 </td><td>ENSE00001544498</td><td>MT-TV  </td></tr>\n",
       "\t<tr><td>ENSG00000210082</td><td>ENSG00000210082.2</td><td>ENST00000387347</td><td>ENST00000387347.2</td><td>               </td><td>                 </td><td>ENSE00001544497</td><td>MT-RNR2</td></tr>\n",
       "\t<tr><td>ENSG00000209082</td><td>ENSG00000209082.1</td><td>ENST00000386347</td><td>ENST00000386347.1</td><td>               </td><td>                 </td><td>ENSE00002006242</td><td>MT-TL1 </td></tr>\n",
       "\t<tr><td>ENSG00000198888</td><td>ENSG00000198888.2</td><td>ENST00000361390</td><td>ENST00000361390.2</td><td>ENSP00000354687</td><td>ENSP00000354687.2</td><td>ENSE00001435714</td><td>MT-ND1 </td></tr>\n",
       "</tbody>\n",
       "</table>\n"
      ],
      "text/latex": [
       "A data.table: 6 × 8\n",
       "\\begin{tabular}{llllllll}\n",
       " Gene stable ID & Gene stable ID version & Transcript stable ID & Transcript stable ID version & Protein stable ID & Protein stable ID version & Exon stable ID & HGNC symbol\\\\\n",
       " <chr> & <chr> & <chr> & <chr> & <chr> & <chr> & <chr> & <chr>\\\\\n",
       "\\hline\n",
       "\t ENSG00000210049 & ENSG00000210049.1 & ENST00000387314 & ENST00000387314.1 &                 &                   & ENSE00001544501 & MT-TF  \\\\\n",
       "\t ENSG00000211459 & ENSG00000211459.2 & ENST00000389680 & ENST00000389680.2 &                 &                   & ENSE00001544499 & MT-RNR1\\\\\n",
       "\t ENSG00000210077 & ENSG00000210077.1 & ENST00000387342 & ENST00000387342.1 &                 &                   & ENSE00001544498 & MT-TV  \\\\\n",
       "\t ENSG00000210082 & ENSG00000210082.2 & ENST00000387347 & ENST00000387347.2 &                 &                   & ENSE00001544497 & MT-RNR2\\\\\n",
       "\t ENSG00000209082 & ENSG00000209082.1 & ENST00000386347 & ENST00000386347.1 &                 &                   & ENSE00002006242 & MT-TL1 \\\\\n",
       "\t ENSG00000198888 & ENSG00000198888.2 & ENST00000361390 & ENST00000361390.2 & ENSP00000354687 & ENSP00000354687.2 & ENSE00001435714 & MT-ND1 \\\\\n",
       "\\end{tabular}\n"
      ],
      "text/markdown": [
       "\n",
       "A data.table: 6 × 8\n",
       "\n",
       "| Gene stable ID &lt;chr&gt; | Gene stable ID version &lt;chr&gt; | Transcript stable ID &lt;chr&gt; | Transcript stable ID version &lt;chr&gt; | Protein stable ID &lt;chr&gt; | Protein stable ID version &lt;chr&gt; | Exon stable ID &lt;chr&gt; | HGNC symbol &lt;chr&gt; |\n",
       "|---|---|---|---|---|---|---|---|\n",
       "| ENSG00000210049 | ENSG00000210049.1 | ENST00000387314 | ENST00000387314.1 | <!----> | <!----> | ENSE00001544501 | MT-TF   |\n",
       "| ENSG00000211459 | ENSG00000211459.2 | ENST00000389680 | ENST00000389680.2 | <!----> | <!----> | ENSE00001544499 | MT-RNR1 |\n",
       "| ENSG00000210077 | ENSG00000210077.1 | ENST00000387342 | ENST00000387342.1 | <!----> | <!----> | ENSE00001544498 | MT-TV   |\n",
       "| ENSG00000210082 | ENSG00000210082.2 | ENST00000387347 | ENST00000387347.2 | <!----> | <!----> | ENSE00001544497 | MT-RNR2 |\n",
       "| ENSG00000209082 | ENSG00000209082.1 | ENST00000386347 | ENST00000386347.1 | <!----> | <!----> | ENSE00002006242 | MT-TL1  |\n",
       "| ENSG00000198888 | ENSG00000198888.2 | ENST00000361390 | ENST00000361390.2 | ENSP00000354687 | ENSP00000354687.2 | ENSE00001435714 | MT-ND1  |\n",
       "\n"
      ],
      "text/plain": [
       "  Gene stable ID  Gene stable ID version Transcript stable ID\n",
       "1 ENSG00000210049 ENSG00000210049.1      ENST00000387314     \n",
       "2 ENSG00000211459 ENSG00000211459.2      ENST00000389680     \n",
       "3 ENSG00000210077 ENSG00000210077.1      ENST00000387342     \n",
       "4 ENSG00000210082 ENSG00000210082.2      ENST00000387347     \n",
       "5 ENSG00000209082 ENSG00000209082.1      ENST00000386347     \n",
       "6 ENSG00000198888 ENSG00000198888.2      ENST00000361390     \n",
       "  Transcript stable ID version Protein stable ID Protein stable ID version\n",
       "1 ENST00000387314.1                                                       \n",
       "2 ENST00000389680.2                                                       \n",
       "3 ENST00000387342.1                                                       \n",
       "4 ENST00000387347.2                                                       \n",
       "5 ENST00000386347.1                                                       \n",
       "6 ENST00000361390.2            ENSP00000354687   ENSP00000354687.2        \n",
       "  Exon stable ID  HGNC symbol\n",
       "1 ENSE00001544501 MT-TF      \n",
       "2 ENSE00001544499 MT-RNR1    \n",
       "3 ENSE00001544498 MT-TV      \n",
       "4 ENSE00001544497 MT-RNR2    \n",
       "5 ENSE00002006242 MT-TL1     \n",
       "6 ENSE00001435714 MT-ND1     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "biomart_dt <- fread(\n",
    "    file=\"input/mart_export_ids.tsv.gz\", sep=\"\\t\",\n",
    "    header=TRUE, check.names=FALSE, stringsAsFactors=FALSE\n",
    ")\n",
    "\n",
    "dim(biomart_dt)\n",
    "head(biomart_dt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc41ed85-6b0a-452e-b339-8587840ca746",
   "metadata": {},
   "source": [
    "---\n",
    "### Use getGeneNames() function using an exemplary vector of several values\n",
    "\n",
    "---\n",
    "- A vector of exemplary Ensembl IDs (gene stable IDs). It contains also one NA value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "11657781-083b-4f38-801b-9238b6a4df25",
   "metadata": {},
   "outputs": [],
   "source": [
    "exmpl_ids <- c(\"ENSG00000211459\", NA, \"ENSG00000179546\", \"ENSG00000210049\",\n",
    "               \"ENSG00000289881\", \"ENSG00000276085\", \"ENSG00000277336\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee416838-0da5-479e-a7dc-ec2acfa6ed00",
   "metadata": {},
   "source": [
    "- Pass a single value only:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "23f2a002-ac16-43f3-94b5-e797860b376b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "'MT-RNR1'"
      ],
      "text/latex": [
       "'MT-RNR1'"
      ],
      "text/markdown": [
       "'MT-RNR1'"
      ],
      "text/plain": [
       "[1] \"MT-RNR1\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "getGeneNames(exmpl_ids[1], biomart_dt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03c42965-5b71-4415-8a41-c5fa0cf58b8d",
   "metadata": {},
   "source": [
    "- Pass the whole vector:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "3feb73d7-924d-48ff-99b6-099eed200a2e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>'MT-RNR1'</li><li>NA</li><li>'HTR1D'</li><li>'MT-TF'</li><li>''</li><li>'CCL3L1, CCL3L3'</li><li>'CCL3L1, CCL3L3'</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 'MT-RNR1'\n",
       "\\item NA\n",
       "\\item 'HTR1D'\n",
       "\\item 'MT-TF'\n",
       "\\item ''\n",
       "\\item 'CCL3L1, CCL3L3'\n",
       "\\item 'CCL3L1, CCL3L3'\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 'MT-RNR1'\n",
       "2. NA\n",
       "3. 'HTR1D'\n",
       "4. 'MT-TF'\n",
       "5. ''\n",
       "6. 'CCL3L1, CCL3L3'\n",
       "7. 'CCL3L1, CCL3L3'\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "[1] \"MT-RNR1\"        NA               \"HTR1D\"          \"MT-TF\"         \n",
       "[5] \"\"               \"CCL3L1, CCL3L3\" \"CCL3L1, CCL3L3\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "getGeneNames(exmpl_ids, biomart_dt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db2eb11e-a599-4955-96cc-2480bd032042",
   "metadata": {},
   "source": [
    "- A test for a vector of exemplary HGNC symols. It contains also one NA value, and one incorrect value _HEYHEY_. If Gene symbols are used, it must be indicated explicite (by `gene.symbols=TRUE`). It turns off automatic Ensembl ID type detection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "a31ee6d0-a082-4d2d-a43a-18f9b8fcff50",
   "metadata": {},
   "outputs": [],
   "source": [
    "gene_symbols <- c(\"MT-RNR1\", NA, \"HEYHEY\", \"CCL3L1\", \"CCL3L3\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "ceddcd84-7df6-4f5f-8230-9048d3aa9862",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>'ENSG00000211459'</li><li>NA</li><li>NA</li><li>'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'</li><li>'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 'ENSG00000211459'\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item 'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'\n",
       "\\item 'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 'ENSG00000211459'\n",
       "2. NA\n",
       "3. NA\n",
       "4. 'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'\n",
       "5. 'ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085'\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "[1] \"ENSG00000211459\"                                                   \n",
       "[2] NA                                                                  \n",
       "[3] NA                                                                  \n",
       "[4] \"ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085\"\n",
       "[5] \"ENSG00000277796, ENSG00000277768, ENSG00000277336, ENSG00000276085\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "getGeneNames(gene_symbols, biomart_dt, gene.symbols=TRUE)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca46c384-2642-4daf-bbfd-1000201915c6",
   "metadata": {},
   "source": [
    "---\n",
    "### Use getGeneNames() function using a larger dataset\n",
    "\n",
    "---\n",
    "- Load the dataset to a data frame, look up the dimensions and the first two rows"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "4416d1e6-9c3f-4a69-bf6c-964a1c4eea32",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>196520</li><li>2</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 196520\n",
       "\\item 2\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 196520\n",
       "2. 2\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "[1] 196520      2"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<table class=\"dataframe\">\n",
       "<caption>A data.frame: 2 × 2</caption>\n",
       "<thead>\n",
       "\t<tr><th></th><th scope=col>gene_id</th><th scope=col>transcript_id</th></tr>\n",
       "\t<tr><th></th><th scope=col>&lt;chr&gt;</th><th scope=col>&lt;chr&gt;</th></tr>\n",
       "</thead>\n",
       "<tbody>\n",
       "\t<tr><th scope=row>1</th><td>ENSG00000000003.10</td><td>ENST00000373020.4</td></tr>\n",
       "\t<tr><th scope=row>2</th><td>ENSG00000000003.10</td><td>ENST00000494424.1</td></tr>\n",
       "</tbody>\n",
       "</table>\n"
      ],
      "text/latex": [
       "A data.frame: 2 × 2\n",
       "\\begin{tabular}{r|ll}\n",
       "  & gene\\_id & transcript\\_id\\\\\n",
       "  & <chr> & <chr>\\\\\n",
       "\\hline\n",
       "\t1 & ENSG00000000003.10 & ENST00000373020.4\\\\\n",
       "\t2 & ENSG00000000003.10 & ENST00000494424.1\\\\\n",
       "\\end{tabular}\n"
      ],
      "text/markdown": [
       "\n",
       "A data.frame: 2 × 2\n",
       "\n",
       "| <!--/--> | gene_id &lt;chr&gt; | transcript_id &lt;chr&gt; |\n",
       "|---|---|---|\n",
       "| 1 | ENSG00000000003.10 | ENST00000373020.4 |\n",
       "| 2 | ENSG00000000003.10 | ENST00000494424.1 |\n",
       "\n"
      ],
      "text/plain": [
       "  gene_id            transcript_id    \n",
       "1 ENSG00000000003.10 ENST00000373020.4\n",
       "2 ENSG00000000003.10 ENST00000494424.1"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ids_df <- read.table(\n",
    "    gzfile(\"input/test_ids.tsv.gz\"), sep=\"\\t\", header=TRUE,\n",
    "    check.names=FALSE, stringsAsFactors=FALSE\n",
    ")\n",
    "\n",
    "dim(ids_df)\n",
    "head(ids_df, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17239ed5-7557-4873-ab97-33bb8697c5c5",
   "metadata": {},
   "source": [
    "---\n",
    "- Test the function for **10** random `gene_ids` and corresponding `transcript_ids` as well as different values of `strip.version` argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "a4954eb3-cf5c-4f1a-99e9-8aa5656bfe93",
   "metadata": {},
   "outputs": [],
   "source": [
    "set.seed(1)\n",
    "smpl_rows <- sample(which(complete.cases(ids_df)), 10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "ad325ab0-7a04-43d2-b5c6-fb99e8e72a49",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>'NFATC4'</li><li>'MIR5700'</li><li>'ACTG1'</li><li>'USP17L22'</li><li>'FRMD6'</li><li>'SERF1B'</li><li>'ZNF516'</li><li>'ELAVL2'</li><li>'CLN3'</li><li>'LINC02910'</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 'NFATC4'\n",
       "\\item 'MIR5700'\n",
       "\\item 'ACTG1'\n",
       "\\item 'USP17L22'\n",
       "\\item 'FRMD6'\n",
       "\\item 'SERF1B'\n",
       "\\item 'ZNF516'\n",
       "\\item 'ELAVL2'\n",
       "\\item 'CLN3'\n",
       "\\item 'LINC02910'\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 'NFATC4'\n",
       "2. 'MIR5700'\n",
       "3. 'ACTG1'\n",
       "4. 'USP17L22'\n",
       "5. 'FRMD6'\n",
       "6. 'SERF1B'\n",
       "7. 'ZNF516'\n",
       "8. 'ELAVL2'\n",
       "9. 'CLN3'\n",
       "10. 'LINC02910'\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       " [1] \"NFATC4\"    \"MIR5700\"   \"ACTG1\"     \"USP17L22\"  \"FRMD6\"     \"SERF1B\"   \n",
       " [7] \"ZNF516\"    \"ELAVL2\"    \"CLN3\"      \"LINC02910\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ids <- ids_df[smpl_rows, \"gene_id\"]\n",
    "names <- getGeneNames(ids, biomart_dt)\n",
    "names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "7891e838-ed74-474f-8e0e-2c09cf519f81",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>'NFATC4'</li><li>'MIR5700'</li><li>'ACTG1'</li><li>'USP17L22'</li><li>'FRMD6'</li><li>'SERF1B'</li><li>'ZNF516'</li><li>'ELAVL2'</li><li>'CLN3'</li><li>NA</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item 'NFATC4'\n",
       "\\item 'MIR5700'\n",
       "\\item 'ACTG1'\n",
       "\\item 'USP17L22'\n",
       "\\item 'FRMD6'\n",
       "\\item 'SERF1B'\n",
       "\\item 'ZNF516'\n",
       "\\item 'ELAVL2'\n",
       "\\item 'CLN3'\n",
       "\\item NA\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. 'NFATC4'\n",
       "2. 'MIR5700'\n",
       "3. 'ACTG1'\n",
       "4. 'USP17L22'\n",
       "5. 'FRMD6'\n",
       "6. 'SERF1B'\n",
       "7. 'ZNF516'\n",
       "8. 'ELAVL2'\n",
       "9. 'CLN3'\n",
       "10. NA\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       " [1] \"NFATC4\"   \"MIR5700\"  \"ACTG1\"    \"USP17L22\" \"FRMD6\"    \"SERF1B\"  \n",
       " [7] \"ZNF516\"   \"ELAVL2\"   \"CLN3\"     NA        "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ids <- ids_df[smpl_rows, \"transcript_id\"]\n",
    "names <- getGeneNames(ids, biomart_dt)\n",
    "names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "9dec593e-5cf4-406e-82c1-9dde94662c4c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>NA</li><li>'MIR5700'</li><li>NA</li><li>NA</li><li>NA</li><li>NA</li><li>NA</li><li>NA</li><li>NA</li><li>NA</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item NA\n",
       "\\item 'MIR5700'\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\item NA\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. NA\n",
       "2. 'MIR5700'\n",
       "3. NA\n",
       "4. NA\n",
       "5. NA\n",
       "6. NA\n",
       "7. NA\n",
       "8. NA\n",
       "9. NA\n",
       "10. NA\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       " [1] NA        \"MIR5700\" NA        NA        NA        NA        NA       \n",
       " [8] NA        NA        NA       "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ids <- ids_df[smpl_rows, \"gene_id\"]\n",
    "names <- getGeneNames(ids, biomart_dt, strip.version=FALSE)\n",
    "names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "cf5f54c3-2eb9-4326-9ccf-99a615f8e683",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       ".list-inline {list-style: none; margin:0; padding: 0}\n",
       ".list-inline>li {display: inline-block}\n",
       ".list-inline>li:not(:last-child)::after {content: \"\\00b7\"; padding: 0 .5ex}\n",
       "</style>\n",
       "<ol class=list-inline><li>NA</li><li>'MIR5700'</li><li>NA</li><li>'USP17L22'</li><li>NA</li><li>'SERF1B'</li><li>'ZNF516'</li><li>NA</li><li>'CLN3'</li><li>NA</li></ol>\n"
      ],
      "text/latex": [
       "\\begin{enumerate*}\n",
       "\\item NA\n",
       "\\item 'MIR5700'\n",
       "\\item NA\n",
       "\\item 'USP17L22'\n",
       "\\item NA\n",
       "\\item 'SERF1B'\n",
       "\\item 'ZNF516'\n",
       "\\item NA\n",
       "\\item 'CLN3'\n",
       "\\item NA\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "1. NA\n",
       "2. 'MIR5700'\n",
       "3. NA\n",
       "4. 'USP17L22'\n",
       "5. NA\n",
       "6. 'SERF1B'\n",
       "7. 'ZNF516'\n",
       "8. NA\n",
       "9. 'CLN3'\n",
       "10. NA\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       " [1] NA         \"MIR5700\"  NA         \"USP17L22\" NA         \"SERF1B\"  \n",
       " [7] \"ZNF516\"   NA         \"CLN3\"     NA        "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ids <- ids_df[smpl_rows, \"transcript_id\"]\n",
    "names <- getGeneNames(ids, biomart_dt, strip.version=FALSE)\n",
    "names"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e27f299-9b1c-40d4-91ba-8af068d08fd8",
   "metadata": {},
   "source": [
    "---\n",
    "- Define a helper function `printResStats()` that calculates some basic stats, and among all shows how many IDs cannot be found in the provided BioMart data.\n",
    "- Test `getGeneNames()` function for **all** `gene_ids` and corresponding `transcript_ids` (~200k) using the default `strip.version` argument value (_TRUE_):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "155f9218-1c3e-4a8f-92d7-36ace942c291",
   "metadata": {},
   "outputs": [],
   "source": [
    "printResStats <- function(ids, names) {\n",
    "    in_na  <- sum( is.na(ids) )\n",
    "    out_na <- sum( is.na(names) )\n",
    "    print( paste(\"Input vector length:\", length(ids)) )\n",
    "    print( paste(\"Output vector length:\", length(names)) )\n",
    "    print( paste(\"Input NA count:\", in_na) )\n",
    "    print( paste(\"Output NA count:\", out_na) )\n",
    "    print( paste(\"IDs not found:\", out_na-in_na) )\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "6be62d97-07c9-4757-b9f5-f780697879ec",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] \"Input vector length: 196520\"\n",
      "[1] \"Output vector length: 196520\"\n",
      "[1] \"Input NA count: 0\"\n",
      "[1] \"Output NA count: 7714\"\n",
      "[1] \"IDs not found: 7714\"\n"
     ]
    }
   ],
   "source": [
    "ids <- ids_df[[\"gene_id\"]]\n",
    "names <- getGeneNames(ids, biomart_dt)\n",
    "\n",
    "printResStats(ids, names)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "4955ccc1-f544-4e41-b689-4daf8cfe97dd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] \"Input vector length: 196520\"\n",
      "[1] \"Output vector length: 196520\"\n",
      "[1] \"Input NA count: 0\"\n",
      "[1] \"Output NA count: 17043\"\n",
      "[1] \"IDs not found: 17043\"\n"
     ]
    }
   ],
   "source": [
    "ids <- ids_df[[\"transcript_id\"]]\n",
    "names <- getGeneNames(ids, biomart_dt)\n",
    "\n",
    "printResStats(ids, names)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39709d0a-9507-4542-b06f-8c1bb3a17cf5",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "R",
   "language": "R",
   "name": "ir"
  },
  "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
}