docs/source/notebooks/prior_knowledge.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Prior Knowledge"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "LIANA+ typically relies heavily on prior knowledge to infer intercellular communication and the intracellular signaling pathways that are activated in response to communication. This notebook provides a brief overview of the prior knowledge typically used by LIANA+. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/dbdimitrov/anaconda3/envs/spiana/lib/python3.10/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
      "Downloading data from `https://omnipathdb.org/queries/enzsub?format=json`\n",
      "Downloading data from `https://omnipathdb.org/queries/interactions?format=json`\n",
      "Downloading data from `https://omnipathdb.org/queries/complexes?format=json`\n",
      "Downloading data from `https://omnipathdb.org/queries/annotations?format=json`\n",
      "Downloading data from `https://omnipathdb.org/queries/intercell?format=json`\n",
      "Downloading data from `https://omnipathdb.org/about?format=text`\n"
     ]
    }
   ],
   "source": [
    "import liana as li\n",
    "import omnipath as op\n",
    "import decoupler as dc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ligand-Receptor Interactions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the simplest case, for reproducibility purposes, LIANA+ provides a frozen set of interactions across resources. These are accessible through the `select_resource` function in the `resource` module. The resources that are currently supported are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['baccin2019',\n",
       " 'cellcall',\n",
       " 'cellchatdb',\n",
       " 'cellinker',\n",
       " 'cellphonedb',\n",
       " 'celltalkdb',\n",
       " 'connectomedb2020',\n",
       " 'consensus',\n",
       " 'embrace',\n",
       " 'guide2pharma',\n",
       " 'hpmr',\n",
       " 'icellnet',\n",
       " 'italk',\n",
       " 'kirouac2010',\n",
       " 'lrdb',\n",
       " 'mouseconsensus',\n",
       " 'ramilowski2015']"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "li.resource.show_resources()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    \n",
    "By default, `liana` uses the `consensus` resource, which is composed by multiple expert-curated ligand-receptor resources, including CellPhoneDB, CellChat, ICELLNET, connectomeDB2020, and CellTalkDB.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ligand</th>\n",
       "      <th>receptor</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>LGALS9</td>\n",
       "      <td>PTPRC</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>LGALS9</td>\n",
       "      <td>MET</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>LGALS9</td>\n",
       "      <td>CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>LGALS9</td>\n",
       "      <td>LRP1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>LGALS9</td>\n",
       "      <td>CD47</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   ligand receptor\n",
       "0  LGALS9    PTPRC\n",
       "1  LGALS9      MET\n",
       "2  LGALS9     CD44\n",
       "3  LGALS9     LRP1\n",
       "4  LGALS9     CD47"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "resource = li.rs.select_resource('consensus')\n",
    "resource.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All of the ligand-receptor resource in LIANA+ were pre-generated using the [OmniPath](https://github.com/saezlab/omnipath) meta-database. Though any custom resource can also be passed, including those provided by the user or generated using the `omnipath` client package. \n",
    "\n",
    "Via this client, in addition to ligand-receptor interactions, users can obtain the PubMed IDs of the references (`references`) that were used support each interaction, as well as the database that reported the interaction in the first place. \n",
    "\n",
    "Users can also modify the resource according to their preferences, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ligand</th>\n",
       "      <th>receptor</th>\n",
       "      <th>references</th>\n",
       "      <th>source</th>\n",
       "      <th>target</th>\n",
       "      <th>is_stimulation</th>\n",
       "      <th>is_inhibition</th>\n",
       "      <th>consensus_direction</th>\n",
       "      <th>consensus_stimulation</th>\n",
       "      <th>consensus_inhibition</th>\n",
       "      <th>...</th>\n",
       "      <th>aspect_intercell_target</th>\n",
       "      <th>category_source_intercell_target</th>\n",
       "      <th>uniprot_intercell_target</th>\n",
       "      <th>entity_type_intercell_target</th>\n",
       "      <th>consensus_score_intercell_target</th>\n",
       "      <th>transmitter_intercell_target</th>\n",
       "      <th>receiver_intercell_target</th>\n",
       "      <th>secreted_intercell_target</th>\n",
       "      <th>plasma_membrane_transmembrane_intercell_target</th>\n",
       "      <th>plasma_membrane_peripheral_intercell_target</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>LCK</td>\n",
       "      <td>CTLA4</td>\n",
       "      <td>ProtMapper:9973379;SIGNOR:9973379;SPIKE:939833...</td>\n",
       "      <td>P06239</td>\n",
       "      <td>P16410</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>...</td>\n",
       "      <td>functional</td>\n",
       "      <td>resource_specific</td>\n",
       "      <td>P16410</td>\n",
       "      <td>protein</td>\n",
       "      <td>8</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>CD86</td>\n",
       "      <td>CTLA4</td>\n",
       "      <td>BioGRID:11279501;CellChatDB:23954143;CellTalkD...</td>\n",
       "      <td>P42081</td>\n",
       "      <td>P16410</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>...</td>\n",
       "      <td>functional</td>\n",
       "      <td>resource_specific</td>\n",
       "      <td>P16410</td>\n",
       "      <td>protein</td>\n",
       "      <td>8</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>CD80</td>\n",
       "      <td>CTLA4</td>\n",
       "      <td>BioGRID:11279502;CellChatDB:23954143;ICELLNET:...</td>\n",
       "      <td>P33681</td>\n",
       "      <td>P16410</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>...</td>\n",
       "      <td>functional</td>\n",
       "      <td>resource_specific</td>\n",
       "      <td>P16410</td>\n",
       "      <td>protein</td>\n",
       "      <td>8</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>ICOSLG</td>\n",
       "      <td>CTLA4</td>\n",
       "      <td>ICELLNET:21530327;connectomeDB2020:21530327</td>\n",
       "      <td>O75144</td>\n",
       "      <td>P16410</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>...</td>\n",
       "      <td>functional</td>\n",
       "      <td>resource_specific</td>\n",
       "      <td>P16410</td>\n",
       "      <td>protein</td>\n",
       "      <td>8</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>LCK</td>\n",
       "      <td>CD8A</td>\n",
       "      <td>NetPath:8814252;SPIKE:16818755;SPIKE_LC:16818755</td>\n",
       "      <td>P06239</td>\n",
       "      <td>P01732</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>False</td>\n",
       "      <td>...</td>\n",
       "      <td>functional</td>\n",
       "      <td>resource_specific</td>\n",
       "      <td>P01732</td>\n",
       "      <td>protein</td>\n",
       "      <td>6</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 45 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   ligand receptor                                         references  source  \\\n",
       "0     LCK    CTLA4  ProtMapper:9973379;SIGNOR:9973379;SPIKE:939833...  P06239   \n",
       "1    CD86    CTLA4  BioGRID:11279501;CellChatDB:23954143;CellTalkD...  P42081   \n",
       "2    CD80    CTLA4  BioGRID:11279502;CellChatDB:23954143;ICELLNET:...  P33681   \n",
       "3  ICOSLG    CTLA4        ICELLNET:21530327;connectomeDB2020:21530327  O75144   \n",
       "4     LCK     CD8A   NetPath:8814252;SPIKE:16818755;SPIKE_LC:16818755  P06239   \n",
       "\n",
       "   target  is_stimulation  is_inhibition  consensus_direction  \\\n",
       "0  P16410            True           True                 True   \n",
       "1  P16410            True          False                 True   \n",
       "2  P16410            True          False                 True   \n",
       "3  P16410           False          False                False   \n",
       "4  P01732           False          False                False   \n",
       "\n",
       "   consensus_stimulation  consensus_inhibition  ...  aspect_intercell_target  \\\n",
       "0                  False                  True  ...               functional   \n",
       "1                   True                 False  ...               functional   \n",
       "2                   True                 False  ...               functional   \n",
       "3                  False                 False  ...               functional   \n",
       "4                  False                 False  ...               functional   \n",
       "\n",
       "  category_source_intercell_target uniprot_intercell_target  \\\n",
       "0                resource_specific                   P16410   \n",
       "1                resource_specific                   P16410   \n",
       "2                resource_specific                   P16410   \n",
       "3                resource_specific                   P16410   \n",
       "4                resource_specific                   P01732   \n",
       "\n",
       "   entity_type_intercell_target  consensus_score_intercell_target  \\\n",
       "0                       protein                                 8   \n",
       "1                       protein                                 8   \n",
       "2                       protein                                 8   \n",
       "3                       protein                                 8   \n",
       "4                       protein                                 6   \n",
       "\n",
       "  transmitter_intercell_target receiver_intercell_target  \\\n",
       "0                        False                      True   \n",
       "1                        False                      True   \n",
       "2                        False                      True   \n",
       "3                        False                      True   \n",
       "4                        False                      True   \n",
       "\n",
       "  secreted_intercell_target plasma_membrane_transmembrane_intercell_target  \\\n",
       "0                     False                                           True   \n",
       "1                     False                                           True   \n",
       "2                     False                                           True   \n",
       "3                     False                                           True   \n",
       "4                      True                                           True   \n",
       "\n",
       "  plasma_membrane_peripheral_intercell_target  \n",
       "0                                       False  \n",
       "1                                       False  \n",
       "2                                       False  \n",
       "3                                       False  \n",
       "4                                       False  \n",
       "\n",
       "[5 rows x 45 columns]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ligrec = op.interactions.import_intercell_network(\n",
    "    interactions_params = {'license':'commercial'},\n",
    "    transmitter_params = {'database':'CellChatDB'},\n",
    "    receiver_params = {'database':'CellChatDB'},\n",
    "    )\n",
    "ligrec.head()\n",
    "\n",
    "ligrec = ligrec.rename(columns={'genesymbol_intercell_source':'ligand', 'genesymbol_intercell_target':'receptor'})\n",
    "ligrec = ligrec[['ligand', 'receptor', 'references'] + [col for col in ligrec.columns if col not in ['ligand', 'receptor', 'references']]]\n",
    "ligrec.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This function provides a rich list of annotations, such as the modes of action,inhibition or stimulation, the curation effort, types of signalling, etc.\n",
    "For a more comprehensive overview of the information that is available, please refer to the [OmniPath documentation](https://omnipathdb.org/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Homology Mapping\n",
    "\n",
    "Similarly, LIANA+ provides on demand homology mapping beyond mouse symbols. It utilises the [HCOP database](https://www.genenames.org/help/hcop/) to obtain homologous genes across species. Specifically, we download the resource from the frequently-updated Bulk Download FTP section of the HCOP database: https://ftp.ebi.ac.uk/pub/databases/genenames/hcop/.\n",
    "\n",
    "The homology mapping is accessible through the `resource` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/dbdimitrov/anaconda3/envs/spiana/lib/python3.10/site-packages/liana/resource/_orthology.py:193: DtypeWarning: Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>source</th>\n",
       "      <th>target</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>132672</th>\n",
       "      <td>ZYG11B</td>\n",
       "      <td>zyg11</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>132673</th>\n",
       "      <td>ZYG11B</td>\n",
       "      <td>zyg11l</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>132674</th>\n",
       "      <td>ZYX</td>\n",
       "      <td>zyx</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>132676</th>\n",
       "      <td>ZZEF1</td>\n",
       "      <td>zzef1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>132677</th>\n",
       "      <td>ZZZ3</td>\n",
       "      <td>zzz3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "        source  target\n",
       "132672  ZYG11B   zyg11\n",
       "132673  ZYG11B  zyg11l\n",
       "132674     ZYX     zyx\n",
       "132676   ZZEF1   zzef1\n",
       "132677    ZZZ3    zzz3"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# let's say we are interested in zebrafish homologs of human genes\n",
    "map_df = li.rs.get_hcop_orthologs(url='https://ftp.ebi.ac.uk/pub/databases/genenames/hcop/human_zebrafish_hcop_fifteen_column.txt.gz',\n",
    "                                   columns=['human_symbol', 'zebrafish_symbol'],\n",
    "                                   # NOTE: HCOP integrates multiple resource, so we can filter out mappings in at least 3 of them for confidence\n",
    "                                   min_evidence=3\n",
    "                                   )\n",
    "# rename the columns to source and target, respectively for the original organism and the target organism\n",
    "map_df = map_df.rename(columns={'human_symbol':'source', 'zebrafish_symbol':'target'})\n",
    "map_df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we've obtained the homologous genes, let's convert the resource to those genes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "zfish = li.rs.translate_resource(resource,\n",
    "                                 map_df=map_df,\n",
    "                                 columns=['ligand', 'receptor'],\n",
    "                                 replace=True,\n",
    "                                 # NOTE that we need to define the threshold of redundancies for the mapping\n",
    "                                 # in this case, we would keep mappings as long as they don't map to more than 2 zebrafish genes\n",
    "                                 one_to_many=3\n",
    "                                 )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Obtain Mouse Homologs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/dbdimitrov/anaconda3/envs/spiana/lib/python3.10/site-packages/liana/resource/_orthology.py:193: DtypeWarning: Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ligand</th>\n",
       "      <th>receptor</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Lgals9</td>\n",
       "      <td>Ptprc</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Lgals9</td>\n",
       "      <td>Met</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Lgals9</td>\n",
       "      <td>Cd44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Lgals9</td>\n",
       "      <td>Lrp1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Lgals9</td>\n",
       "      <td>Cd47</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4619</th>\n",
       "      <td>Bmp2</td>\n",
       "      <td>Actr2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4620</th>\n",
       "      <td>Bmp15</td>\n",
       "      <td>Actr2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4621</th>\n",
       "      <td>Csf1</td>\n",
       "      <td>Csf3r</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4622</th>\n",
       "      <td>Il36g</td>\n",
       "      <td>Ifnar1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4623</th>\n",
       "      <td>Il36g</td>\n",
       "      <td>Ifnar2</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>4055 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "      ligand receptor\n",
       "0     Lgals9    Ptprc\n",
       "1     Lgals9      Met\n",
       "2     Lgals9     Cd44\n",
       "3     Lgals9     Lrp1\n",
       "4     Lgals9     Cd47\n",
       "...      ...      ...\n",
       "4619    Bmp2    Actr2\n",
       "4620   Bmp15    Actr2\n",
       "4621    Csf1    Csf3r\n",
       "4622   Il36g   Ifnar1\n",
       "4623   Il36g   Ifnar2\n",
       "\n",
       "[4055 rows x 2 columns]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "map_df = li.rs.get_hcop_orthologs(url='https://ftp.ebi.ac.uk/pub/databases/genenames/hcop/human_mouse_hcop_fifteen_column.txt.gz',\n",
    "                                  columns=['human_symbol', 'mouse_symbol'],\n",
    "                                   # NOTE: HCOP integrates multiple resource, so we can filter out mappings in at least 3 of them for confidence\n",
    "                                   min_evidence=3\n",
    "                                   )\n",
    "# rename the columns to source and target, respectively for the original organism and the target organism\n",
    "map_df = map_df.rename(columns={'human_symbol':'source', 'mouse_symbol':'target'})\n",
    "\n",
    "# We will then translate\n",
    "mouse = li.rs.translate_resource(resource,\n",
    "                                 map_df=map_df,\n",
    "                                 columns=['ligand', 'receptor'],\n",
    "                                 replace=True,\n",
    "                                 # Here, we will be harsher and only keep mappings that don't map to more than 1 mouse gene\n",
    "                                 one_to_many=1\n",
    "                                 )\n",
    "mouse"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you use HCOP function, please reference the original HCOP papers:\n",
    "- Eyre, T.A., Wright, M.W., Lush, M.J. and Bruford, E.A., 2007. HCOP: a searchable database of human orthology predictions. Briefings in bioinformatics, 8(1), pp.2-5.\n",
    "- Yates, B., Gray, K.A., Jones, T.E. and Bruford, E.A., 2021. Updates to HCOP: the HGNC comparison of orthology predictions tool. Briefings in Bioinformatics, 22(6), p.bbab155."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "All methods of LIANA+ accept a ``resource`` parameter that can be used to pass any custom resource, beyond such from homology conversion.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Annotating Ligand-Receptors\n",
    "\n",
    "In addition to ligand-receptors, we can also obtain other annotations via [OmniPath](https://github.com/saezlab/omnipath). While these can be tissue locations, TF regulons, cytokine signatures, or other types of annotations, the most common use case is to obtain the pathways that are associated with each ligand-receptor interaction.\n",
    "\n",
    "### Pathway Annotations\n",
    "\n",
    "We use commonly [PROGENy](https://www.nature.com/articles/s41467-017-02391-6) pathway weights to assign interactions to certain canonical pathways, such that all members of the interactions (i.e. incl. complex subunits) are present in the same pathway with the same weight sign. This is done to ensure that the interaction is not only present in the same pathway, but also that it is likely to be active in the same direction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Downloading annotations for all proteins from the following resources: `['PROGENy']`\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>source</th>\n",
       "      <th>target</th>\n",
       "      <th>weight</th>\n",
       "      <th>p_value</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>TMPRSS2</td>\n",
       "      <td>11.490631</td>\n",
       "      <td>0.000000e+00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>NKX3-1</td>\n",
       "      <td>10.622551</td>\n",
       "      <td>2.242078e-44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>MBOAT2</td>\n",
       "      <td>10.472733</td>\n",
       "      <td>4.624285e-44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>KLK2</td>\n",
       "      <td>10.176186</td>\n",
       "      <td>1.944414e-40</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>SARG</td>\n",
       "      <td>11.386852</td>\n",
       "      <td>2.790209e-40</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     source   target     weight       p_value\n",
       "0  Androgen  TMPRSS2  11.490631  0.000000e+00\n",
       "1  Androgen   NKX3-1  10.622551  2.242078e-44\n",
       "2  Androgen   MBOAT2  10.472733  4.624285e-44\n",
       "3  Androgen     KLK2  10.176186  1.944414e-40\n",
       "4  Androgen     SARG  11.386852  2.790209e-40"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# load PROGENy pathways, we use decoupler as a proxy as it formats the data in a more convenient way\n",
    "progeny = dc.get_progeny(top=2500)\n",
    "progeny.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load full list of ligand-receptor pairs\n",
    "lr_pairs = li.resource.select_resource('consensus')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we use the `generate_lr_geneset` function from liana to assign the interactions to pathways. This function takes the ligand-receptor interactions and the pathway annotations, and returns a dataframe with annotated interactions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>source</th>\n",
       "      <th>interaction</th>\n",
       "      <th>weight</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1960</th>\n",
       "      <td>Androgen</td>\n",
       "      <td>HGF^MET</td>\n",
       "      <td>-1.288956</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3030</th>\n",
       "      <td>NFkB</td>\n",
       "      <td>SELE^CD44</td>\n",
       "      <td>3.332552</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3075</th>\n",
       "      <td>TNFa</td>\n",
       "      <td>SELE^CD44</td>\n",
       "      <td>3.322682</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4251</th>\n",
       "      <td>TNFa</td>\n",
       "      <td>FN1^CD44</td>\n",
       "      <td>2.590177</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6950</th>\n",
       "      <td>NFkB</td>\n",
       "      <td>LAMB3^CD44</td>\n",
       "      <td>4.055408</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "        source interaction    weight\n",
       "1960  Androgen     HGF^MET -1.288956\n",
       "3030      NFkB   SELE^CD44  3.332552\n",
       "3075      TNFa   SELE^CD44  3.322682\n",
       "4251      TNFa    FN1^CD44  2.590177\n",
       "6950      NFkB  LAMB3^CD44  4.055408"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# generate ligand-receptor geneset\n",
    "lr_progeny = li.rs.generate_lr_geneset(lr_pairs, progeny, lr_sep=\"^\")\n",
    "lr_progeny.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can additionally performed enrichment analysis of certain ligand-receptor scores using this newly-generated dataframe. For example, see the [application with Tensor-cell2cell](https://liana-py.readthedocs.io/en/latest/notebooks/liana_c2c.html#Downstream-Analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disease Annotations\n",
    "As another example, we can also annotate ligand-receptors to diseases in which both the ligand and the receptor are involved."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Downloading annotations for all proteins from the following resources: `['DisGeNet']`\n"
     ]
    }
   ],
   "source": [
    "diseases = op.requests.Annotations.get(\n",
    "    resources = ['DisGeNet']\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>disease</th>\n",
       "      <th>interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>693653</th>\n",
       "      <td>Hypertensive disease</td>\n",
       "      <td>ACE^AGTR2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>693926</th>\n",
       "      <td>Malignant neoplasm of stomach</td>\n",
       "      <td>ACE^AGTR2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>693991</th>\n",
       "      <td>Neoplasm Metastasis</td>\n",
       "      <td>ACE^AGTR2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>694293</th>\n",
       "      <td>Stomach Neoplasms</td>\n",
       "      <td>ACE^AGTR2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>693759</th>\n",
       "      <td>Left Ventricular Hypertrophy</td>\n",
       "      <td>ACE^AGTR2</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                              disease interaction\n",
       "693653           Hypertensive disease   ACE^AGTR2\n",
       "693926  Malignant neoplasm of stomach   ACE^AGTR2\n",
       "693991            Neoplasm Metastasis   ACE^AGTR2\n",
       "694293              Stomach Neoplasms   ACE^AGTR2\n",
       "693759   Left Ventricular Hypertrophy   ACE^AGTR2"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "diseases = diseases[['genesymbol', 'label', 'value']]\n",
    "diseases = diseases.pivot_table(index='genesymbol',\n",
    "                                columns='label', values='value',\n",
    "                                aggfunc=lambda x: '; '.join(x)).reset_index()\n",
    "diseases = diseases[['genesymbol', 'disease']]\n",
    "diseases['disease'] = diseases['disease'].str.split('; ')\n",
    "diseases = diseases.explode('disease')\n",
    "lr_diseases = li.rs.generate_lr_geneset(lr_pairs, diseases, source='disease', target='genesymbol', weight=None, lr_sep=\"^\")\n",
    "lr_diseases.sort_values(\"interaction\").head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check some protein of interest:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>disease</th>\n",
       "      <th>interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>31124</th>\n",
       "      <td>Acute Kidney Insufficiency</td>\n",
       "      <td>SPP1^CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>31159</th>\n",
       "      <td>Acute kidney injury</td>\n",
       "      <td>SPP1^CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32630</th>\n",
       "      <td>Kidney Failure, Acute</td>\n",
       "      <td>SPP1^CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>33038</th>\n",
       "      <td>Mammary Neoplasms, Experimental</td>\n",
       "      <td>SPP1^CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>33163</th>\n",
       "      <td>Neoplasm Metastasis</td>\n",
       "      <td>SPP1^CD44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>464305</th>\n",
       "      <td>Cerebral Hemorrhage</td>\n",
       "      <td>SPP1^ITGAV_ITGB3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1108109</th>\n",
       "      <td>Mammary Neoplasms, Experimental</td>\n",
       "      <td>SPP1^S1PR1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                 disease       interaction\n",
       "31124         Acute Kidney Insufficiency         SPP1^CD44\n",
       "31159                Acute kidney injury         SPP1^CD44\n",
       "32630              Kidney Failure, Acute         SPP1^CD44\n",
       "33038    Mammary Neoplasms, Experimental         SPP1^CD44\n",
       "33163                Neoplasm Metastasis         SPP1^CD44\n",
       "464305               Cerebral Hemorrhage  SPP1^ITGAV_ITGB3\n",
       "1108109  Mammary Neoplasms, Experimental        SPP1^S1PR1"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "lr_diseases[lr_diseases['interaction'].str.contains('SPP1')]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Following similar procedures, one may annotate ligand-receptors to any of the annotations available via OmniPath.\n",
    "\n",
    "See `op.requests.Annotations.resources()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Intracellular Signaling\n",
    "\n",
    "While we can obtain the pathways that are associated with each ligand-receptor interaction, we can also obtain the intracellular signaling pathways that are activated in response to the interaction. This is again done using the `omnipath` client package, but this time in combination with [decoupler](https://decoupler-py.readthedocs.io/en/latest/), which enables the enrichment of pathways, transcription factors, and other annotations.\n",
    "\n",
    "One specific scenario, heavily reliant on OmniPath knowledge and enrichment analysis with decoupler is presented in the [Differential Analysis Vignette](https://liana-py.readthedocs.io/en/latest/notebooks/targeted.html).\n",
    "\n",
    "There, to find putative causal networks between deregulated CCC interactions and transcription factors (TFs) we use:\n",
    "\n",
    "### 1) a protein-protein interaction network"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>source</th>\n",
       "      <th>target</th>\n",
       "      <th>source_genesymbol</th>\n",
       "      <th>target_genesymbol</th>\n",
       "      <th>is_directed</th>\n",
       "      <th>is_stimulation</th>\n",
       "      <th>is_inhibition</th>\n",
       "      <th>consensus_direction</th>\n",
       "      <th>consensus_stimulation</th>\n",
       "      <th>consensus_inhibition</th>\n",
       "      <th>curation_effort</th>\n",
       "      <th>references</th>\n",
       "      <th>sources</th>\n",
       "      <th>n_sources</th>\n",
       "      <th>n_primary_sources</th>\n",
       "      <th>n_references</th>\n",
       "      <th>references_stripped</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>P0DP23</td>\n",
       "      <td>P48995</td>\n",
       "      <td>CALM1</td>\n",
       "      <td>TRPC1</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>3</td>\n",
       "      <td>TRIP:11290752;TRIP:11983166;TRIP:12601176</td>\n",
       "      <td>TRIP</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>11290752;11983166;12601176</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>P0DP25</td>\n",
       "      <td>P48995</td>\n",
       "      <td>CALM3</td>\n",
       "      <td>TRPC1</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>3</td>\n",
       "      <td>TRIP:11290752;TRIP:11983166;TRIP:12601176</td>\n",
       "      <td>TRIP</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>11290752;11983166;12601176</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>P0DP24</td>\n",
       "      <td>P48995</td>\n",
       "      <td>CALM2</td>\n",
       "      <td>TRPC1</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>3</td>\n",
       "      <td>TRIP:11290752;TRIP:11983166;TRIP:12601176</td>\n",
       "      <td>TRIP</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>11290752;11983166;12601176</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Q03135</td>\n",
       "      <td>P48995</td>\n",
       "      <td>CAV1</td>\n",
       "      <td>TRPC1</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>13</td>\n",
       "      <td>DIP:19897728;HPRD:12732636;IntAct:19897728;Lit...</td>\n",
       "      <td>DIP;HPRD;IntAct;Lit-BM-17;TRIP</td>\n",
       "      <td>5</td>\n",
       "      <td>5</td>\n",
       "      <td>8</td>\n",
       "      <td>10980191;12732636;14551243;16822931;18430726;1...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>P14416</td>\n",
       "      <td>P48995</td>\n",
       "      <td>DRD2</td>\n",
       "      <td>TRPC1</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>True</td>\n",
       "      <td>True</td>\n",
       "      <td>False</td>\n",
       "      <td>1</td>\n",
       "      <td>TRIP:18261457</td>\n",
       "      <td>TRIP</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>18261457</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   source  target source_genesymbol target_genesymbol  is_directed  \\\n",
       "0  P0DP23  P48995             CALM1             TRPC1         True   \n",
       "1  P0DP25  P48995             CALM3             TRPC1         True   \n",
       "2  P0DP24  P48995             CALM2             TRPC1         True   \n",
       "3  Q03135  P48995              CAV1             TRPC1         True   \n",
       "4  P14416  P48995              DRD2             TRPC1         True   \n",
       "\n",
       "   is_stimulation  is_inhibition  consensus_direction  consensus_stimulation  \\\n",
       "0           False           True                 True                  False   \n",
       "1           False           True                 True                  False   \n",
       "2           False           True                 True                  False   \n",
       "3            True          False                 True                   True   \n",
       "4            True          False                 True                   True   \n",
       "\n",
       "   consensus_inhibition  curation_effort  \\\n",
       "0                  True                3   \n",
       "1                  True                3   \n",
       "2                  True                3   \n",
       "3                 False               13   \n",
       "4                 False                1   \n",
       "\n",
       "                                          references  \\\n",
       "0          TRIP:11290752;TRIP:11983166;TRIP:12601176   \n",
       "1          TRIP:11290752;TRIP:11983166;TRIP:12601176   \n",
       "2          TRIP:11290752;TRIP:11983166;TRIP:12601176   \n",
       "3  DIP:19897728;HPRD:12732636;IntAct:19897728;Lit...   \n",
       "4                                      TRIP:18261457   \n",
       "\n",
       "                          sources  n_sources  n_primary_sources n_references  \\\n",
       "0                            TRIP          1                  1            3   \n",
       "1                            TRIP          1                  1            3   \n",
       "2                            TRIP          1                  1            3   \n",
       "3  DIP;HPRD;IntAct;Lit-BM-17;TRIP          5                  5            8   \n",
       "4                            TRIP          1                  1            1   \n",
       "\n",
       "                                 references_stripped  \n",
       "0                         11290752;11983166;12601176  \n",
       "1                         11290752;11983166;12601176  \n",
       "2                         11290752;11983166;12601176  \n",
       "3  10980191;12732636;14551243;16822931;18430726;1...  \n",
       "4                                           18261457  "
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ppis = op.interactions.OmniPath().get(genesymbols = True)\n",
    "ppis.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2) Transcription Factor Regulons\n",
    "Provided via the [CollecTRI](https://academic.oup.com/nar/article/51/20/10934/7318114?login=false) resource:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>source</th>\n",
       "      <th>target</th>\n",
       "      <th>weight</th>\n",
       "      <th>PMID</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>MYC</td>\n",
       "      <td>TERT</td>\n",
       "      <td>1</td>\n",
       "      <td>10022128;10491298;10606235;10637317;10723141;1...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>SPI1</td>\n",
       "      <td>BGLAP</td>\n",
       "      <td>1</td>\n",
       "      <td>10022617</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>SMAD3</td>\n",
       "      <td>JUN</td>\n",
       "      <td>1</td>\n",
       "      <td>10022869;12374795</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>SMAD4</td>\n",
       "      <td>JUN</td>\n",
       "      <td>1</td>\n",
       "      <td>10022869;12374795</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>STAT5A</td>\n",
       "      <td>IL2</td>\n",
       "      <td>1</td>\n",
       "      <td>10022878;11435608;17182565;17911616;22854263;2...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   source target  weight                                               PMID\n",
       "0     MYC   TERT       1  10022128;10491298;10606235;10637317;10723141;1...\n",
       "1    SPI1  BGLAP       1                                           10022617\n",
       "2   SMAD3    JUN       1                                  10022869;12374795\n",
       "3   SMAD4    JUN       1                                  10022869;12374795\n",
       "4  STAT5A    IL2       1  10022878;11435608;17182565;17911616;22854263;2..."
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dc.get_collectri().head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are then linked using the a modification of the ILP problem proposed in [CARNIVAL](https://www.nature.com/articles/s41540-019-0118-z), solved using [CORNETO](https://github.com/saezlab/corneto) - a Unified Omics-Driven Framework for Network Inference."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Metabolite-Receptor Interactions\n",
    "\n",
    "Via LIANA+ we also provide access to the [MetalinksDB knowledge graph - a customisable database](https://github.com/biocypher/metalinks) of metabolite-receptor interactions, part of the [BioCypher](https://biocypher.org/) ecosystem. For more information please refer to [Farr et al, 2023](https://www.biorxiv.org/content/10.1101/2023.12.30.573715v1.abstract).\n",
    "\n",
    "Specifically, to enable light-weight access, we have converted the MetalinksDB knowledge graph into a database.\n",
    "\n",
    "This database is queried using `sqllite3` and we provide basic queries to customize according to the user's needs - e.g. disease, pathway, location."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check first the values within different tables of the database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Diabetes mellitus type 2',\n",
       " 'Obesity',\n",
       " 'Pancreatic cancer',\n",
       " 'Colorectal cancer',\n",
       " 'Schizophrenia']"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "li.resource.get_metalinks_values(table_name='disease', column_name='disease')[0:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we can obtain metabolite-receptor interactions, the metabolites of which have been reported to be associated with certain locations or diseases:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>metabolite</th>\n",
       "      <th>hmdb</th>\n",
       "      <th>uniprot</th>\n",
       "      <th>gene_symbol</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Dopamine</td>\n",
       "      <td>HMDB0000073</td>\n",
       "      <td>A5X5Y0</td>\n",
       "      <td>HTR3E</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Dopamine</td>\n",
       "      <td>HMDB0000073</td>\n",
       "      <td>O95264</td>\n",
       "      <td>HTR3B</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Dopamine</td>\n",
       "      <td>HMDB0000073</td>\n",
       "      <td>P08908</td>\n",
       "      <td>HTR1A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Dopamine</td>\n",
       "      <td>HMDB0000073</td>\n",
       "      <td>P14416</td>\n",
       "      <td>DRD2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Dopamine</td>\n",
       "      <td>HMDB0000073</td>\n",
       "      <td>P21728</td>\n",
       "      <td>DRD1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  metabolite         hmdb uniprot gene_symbol\n",
       "0   Dopamine  HMDB0000073  A5X5Y0       HTR3E\n",
       "1   Dopamine  HMDB0000073  O95264       HTR3B\n",
       "2   Dopamine  HMDB0000073  P08908       HTR1A\n",
       "3   Dopamine  HMDB0000073  P14416        DRD2\n",
       "4   Dopamine  HMDB0000073  P21728        DRD1"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "li.resource.get_metalinks(source=['Stich', 'CellPhoneDB', 'NeuronChat'],\n",
    "                          tissue_location='Brain',\n",
    "                          biospecimen_location='Cerebrospinal Fluid (CSF)',\n",
    "                          disease='Schizophrenia',\n",
    "                          ).head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This database can further be filtered according to the user's needs, and can be queried as any other standard RDBMS.\n",
    "\n",
    "For such cases, we also provide a utility function to print the database schema:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Schema of table: metabolites\n",
      "============================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: metabolite, Type: TEXT, Primary Key: 0\n",
      "Column ID: 2, Name: pubchem, Type: TEXT, Primary Key: 0\n",
      "Column ID: 3, Name: metabolite_subclass, Type: TEXT, Primary Key: 0\n",
      "\n",
      "No Foreign Keys.\n",
      "----------------------------------------\n",
      "Schema of table: proteins\n",
      "=========================\n",
      "Column ID: 0, Name: uniprot, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: gene_symbol, Type: TEXT, Primary Key: 0\n",
      "Column ID: 2, Name: protein_type, Type: TEXT, Primary Key: 0\n",
      "\n",
      "No Foreign Keys.\n",
      "----------------------------------------\n",
      "Schema of table: edges\n",
      "======================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: uniprot, Type: TEXT, Primary Key: 2\n",
      "Column ID: 2, Name: db_score, Type: REAL, Primary Key: 0\n",
      "Column ID: 3, Name: experiment_score, Type: REAL, Primary Key: 0\n",
      "Column ID: 4, Name: combined_score, Type: REAL, Primary Key: 0\n",
      "Column ID: 5, Name: interaction_mode, Type: TEXT, Primary Key: 0\n",
      "Column ID: 6, Name: mor, Type: INTEGER, Primary Key: 0\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: proteins, From: uniprot, To: uniprot\n",
      "ID: 1, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "Schema of table: source\n",
      "=======================\n",
      "Column ID: 0, Name: hmdb, Type: VARCHAR(255), Primary Key: 1\n",
      "Column ID: 1, Name: uniprot, Type: VARCHAR(255), Primary Key: 2\n",
      "Column ID: 2, Name: source, Type: VARCHAR(255), Primary Key: 3\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: edges, From: hmdb, To: hmdb\n",
      "ID: 0, Seq: 1, Table: edges, From: uniprot, To: uniprot\n",
      "----------------------------------------\n",
      "Schema of table: cell_location\n",
      "==============================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: cell_location, Type: TEXT, Primary Key: 2\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "Schema of table: tissue_location\n",
      "================================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: tissue_location, Type: TEXT, Primary Key: 2\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "Schema of table: biospecimen_location\n",
      "=====================================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: biospecimen_location, Type: TEXT, Primary Key: 2\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "Schema of table: disease\n",
      "========================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: disease, Type: TEXT, Primary Key: 2\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "Schema of table: pathway\n",
      "========================\n",
      "Column ID: 0, Name: hmdb, Type: TEXT, Primary Key: 1\n",
      "Column ID: 1, Name: pathway, Type: TEXT, Primary Key: 2\n",
      "\n",
      "Foreign Keys:\n",
      "ID: 0, Seq: 0, Table: metabolites, From: hmdb, To: hmdb\n",
      "----------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "li.rs.describe_metalinks()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "spiana",
   "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.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}