example_nbs/multi_condition_analysis.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Running comparative analysis of multiple conditions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to compare multiple conditions and perform operations on them, we create a 'median reference' condition and compare all conditions in the dataset against the median condition. This then allows to do comparative analyses, such as heatmaps or general significance analyses (similar to ANOVA analyses on multiple conditions).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying input files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to run differential analyses you need two types of files:\n",
    "* an input file from a proteomics search engine (e.g. DIA-NN, Spectronaut, AlphaPept etc.), or a pre-formatted file\n",
    "* a sample mapping file that maps each sample to a condition (e.g.  sample 'brain_replicate_1' is mapped to condition 'brain'). In the GUI, there is some functionality to help create such a file\n",
    "\n",
    "For the results file, AlphaQuant is compatible to the default output tables of most common proteomics search engines. Detailed specifications on which tables you need can be found \n",
    "in our  [README](https://github.com/MannLabs/alphaquant/blob/main/README.md#section-title).\n",
    "\n",
    "The sample mapping file has to look as follows:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "INPUT_FILE = \"./data/mouse_tissues/example_dataset_mouse_sn.tsv\"\n",
    "SAMPLEMAP_FILE = \"./data/mouse_tissues/samplemap_200.tsv\"\n",
    "RESULTS_DIR = \"./data/mouse_tissues/results_median_comparison\"\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "display(pd.read_csv(INPUT_FILE, sep=\"\\t\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#displaying the samplemap file\n",
    "import pandas as pd\n",
    "display(pd.read_csv(SAMPLEMAP_FILE, sep='\\t'))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run AlphaQuant in Median Comparison mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%reload_ext autoreload\n",
    "%autoreload 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import alphaquant.run_pipeline as aqrunner\n",
    "\n",
    "aqrunner.run_pipeline(input_file=INPUT_FILE, samplemap_file=SAMPLEMAP_FILE, multicond_median_analysis=True, results_dir=RESULTS_DIR)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspect the results tables\n",
    "\n",
    "There are four different main results tables written out to the directory:\n",
    "1. `medianref_protein_alphaquant.tsv` -> protein quantities derived with AlphaQuant's cluster approach\n",
    "2. `medianref_protein_avg.tsv` -> averaged protein quantities ('classic approach')\n",
    "3. `medianref_proteoforms.tsv` -> quantities of all potential proteoforms\n",
    "4. `medianref_peptides.tsv` -> peptide quantities, for expert users\n",
    "\n",
    "In the following we will have a look at tables 1 and 3, which are likely to be the most relevant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df_protein = pd.read_csv(RESULTS_DIR + \"/medianref_protein_alphaquant.tsv\", sep='\\t')\n",
    "df_proteoform = pd.read_csv(RESULTS_DIR + \"/medianref_proteoforms.tsv\", sep='\\t')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(df_protein)\n",
    "display(df_proteoform)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The protein dataframe contains the protein quantities relative to the reference as well as a p_value for each protein which tests the null hypothesis that none of the conditions differs substantially from the median. In the example here all proteins are significant, which is not surprising, as we compare multiple tissues.\\\n",
    "The proteoform dataframe contains a bit more information than just protein quantities. A given protein can have multiple proteoform ids. A novel proteoform is defined if - for a given protein - one or more peptides exist that show a significantly altered regulatory profile as the other peptides that belong to the same protein, indicating a potential proteoform."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizing protein regulation using the protein results table"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#display dfs as clustermaps\n",
    "import seaborn as sns\n",
    "import numpy as np\n",
    "\n",
    "nan_mask = df_protein.set_index('protein').drop(columns=[\"p_value\"]).isna()\n",
    "\n",
    "sns.clustermap(df_protein.set_index('protein').drop(columns=[\"p_value\"]).replace(np.nan, 0), cmap=\"vlag\", center=0, figsize=(12, 12), row_cluster=True, col_cluster=True, mask=nan_mask)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Investigating proteoform profiles using the proteoform results table"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We define the proteoform with the most consistent peptides as the 'reference proteoform'. The pearson correlation coefficient between the reference proteoform and each other proteoform is calculated and reported under the 'corr_to_ref' column. In other words, the 'corr_to_ref' column says how similar a proteoform behaves as compared to another proteoform. We use one of the AlphaQuant utility functions to filter for the interesting proteoforms, meaning those with low correlation compared to the reference proteoform."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import alphaquant.multicond.multicond_utils as aq_multicond_utils\n",
    "\n",
    "df_proteoform_low_corr = aq_multicond_utils.get_low_correlation_proteoform_df(proteoform_df=df_proteoform,\n",
    "                                                                              max_correlation=0.7, keep_reference_proteoform=True)\n",
    "#we specified that we always keep also the reference proteoform\n",
    "display(df_proteoform_low_corr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we can use this dataframe to plot the profiles of the low correlation proteoforms and their reference proteoforms. For this we make use of the alphaquant plotting functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import alphaquant.plotting.multicond as aq_plotting_multicond"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = aq_plotting_multicond.plot_proteoform_intensity_profiles(proteoform_df=df_proteoform_low_corr)\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "test",
   "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.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}