IODA_exclusion_from_mzML.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# IODA exclusion-from-mzML notebook\n",
    "\n",
    "**Purpose**: This notebook generates exclusion table formatted for XCalibur and MaxQuant.Live. It accepts as input one mzML file from one sample data. The ions detected will be added the exclusion list. If you already have an mzTab, we recommend using the dedicated [IODA exclusion-from-mzTab notebook](IODA_exclusion_from_mzTab.ipynb). \n",
    "\n",
    "If you want to customise feature detection with OpenMS, we recommend [using the OpenMS workflow locally](link_documentation) and upload the resulting mzTab to the [IODA exclusion-from-mzTab notebook](IODA_exclusion_from_mzTab.ipynb). \n",
    "\n",
    "**Documentation**: Please refer to the documentation page for more informations on the for IODA exclusion-from-mzML worklow. [See here](link).\n",
    "\n",
    "**Instructions**: \n",
    "- Follow the instructions indicated below and run the cells accordingly\n",
    "- Provide the mzTab for the sample data to be used. \n",
    "- Modify the variables below as needed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "===========================\n",
    "### Step 1 - Provide the input mzML file\n",
    "\n",
    "#### Method 1 \n",
    "Upload your mzML with the Jupyter lab interface (left vertical panel: File / Upload icon on the top right). You can upload to the root of the binder server.\n",
    "\n",
    "#### Method 2\n",
    "We support downloading the mzTab file from the following cloud sharing services:\n",
    "- **Google Drive** (recommended): obtain the sharing the link (make sure the sharing setting is set to 'Anyone with the link can download').\n",
    "- **GoFile**: obtain the download sharing link from a file upload to [https://gofile.io/](https://gofile.io/) (make sure this is the actual downloading link).\n",
    "\n",
    "**Specificy the mzML file name or sharing link in the *input_filename* variable in the cell below**. (The string must be between parenthesis). If the file is not in the root, indicate the proper path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "input_filename = \"https://raw.githubusercontent.com/lfnothias/IODA_MS/test2/tests/Euphorbia/exclusion/toppas_input/Blank.mzML\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "============================\n",
    "### Step 2 - Run the OpenMS workflow\n",
    "\n",
    "**Specify the variables of the OpenMS feature finding metabolomics (FFM) tool**\n",
    "\n",
    "Note that the OpenMS workflow uses two parallel FFM tools. One FFM is optimised for the detection of narrow LC-MS features/peaks, while the other FFM is optimised for large LC-MS features/peaks. Note that we used the peak height for LC-MS peaks/features intensity estimation (instead of area under the curve). Parameters should be optimised depending on the sample complexity and acquisition parameters.\n",
    "\n",
    "##### Mass accuracy for FFM\n",
    "> *ppm_error*: the maximum mass error allowed for the feature detection. Used in both FFM tools. A value of 10 ppm is recommended for a resolution of 35K or less (must be an integer/float).\n",
    "\n",
    "##### Noise level for FFM\n",
    "> *narrow_feature_noise*: this is the MS1 noise level for the detection of narrow LC-MS features. The default value is 1E5 (must be an integer/float, can be in scientific format).\n",
    "\n",
    "> *large_feature_noise*: this is the MS1 noise level for the detection of large LC-MS features. The default value is 5E5 (must be an integer/float, can be in scientific format).\n",
    "\n",
    "TIPS: If your sample has a lot of features, increase the noise levels to limit the number of ions that are detected for subsequent exclusion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IODA_run_TOPPAS_exclusion import *\n",
    "from IODA_exclusion_workflow import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Python 3.7.1\n"
     ]
    }
   ],
   "source": [
    "#Debug variables\n",
    "input_filename = \"https://raw.githubusercontent.com/lfnothias/IODA_MS/test2/tests/Euphorbia/exclusion/toppas_input/Blank.mzML\"\n",
    "ppm_error = 10\n",
    "narrow_feature_noise = 1E5\n",
    "large_feature_noise = 5E5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "IODA_exclusion_workflow(input_filename,ppm_error,narrow_feature_noise,large_feature_noise)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "============================\n",
    "### Step 3 - Download the results of the OpenMS workflow\n",
    "- Download the result files from\n",
    "[download_results/IODA_exclusion_list_from_OpenMS.zip](download_results/IODA_exclusion_list_from_OpenMS.zip)\n",
    "- You can examine the performance of the FFM by visualizing the featureXML with TOPPView. [See documentation here](documentation)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "============================\n",
    "### Step 4 - Set the parameters for building the exclusion list\n",
    "\n",
    "The parameters below are used to the define the ions to be excluded.\n",
    "\n",
    "*min_intensity*: the minimum intensity for the ion/feature to be retained in the exclusion list (absolute count of the peak height).\n",
    "\n",
    "*rt_exclusion_margin*: define the side margin for the retention time range exclusion. Note that this value is added to each side of the actual feature/ion retention time range (in seconds).\n",
    "\n",
    "**Specify the variables for exclusion list in the cell below**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "min_intensity = 100\n",
    "rt_exclusion_margin = 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "============================\n",
    "### Step 5 - Run the cell below\n",
    "\n",
    "Beside running the cell below, no action is needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'make_exclusion_from_mzTabs' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-5-ba03d04160fa>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mmake_exclusion_from_mzTabs\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmin_intensity\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mrt_exclusion_margin\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m: name 'make_exclusion_from_mzTabs' is not defined"
     ]
    }
   ],
   "source": [
    "make_exclusion_from_mzTabs(min_intensity, rt_exclusion_margin)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4 - Examine the results\n",
    "\n",
    "- Examine the IODA-exclusion worflow log and the plots above in order to decide if the 'min_intensity' parameter is adapted to your data/mass spectrometer and sample(s) complexity.\n",
    "- Note that, at this stage, it cannot be evaluated if ion detection was done optimally. This should examinated during from the files generated by the OpenMS workflow.\n",
    "\n",
    "![](results/plot_exclusion_scatter_RT.png)\n",
    "![](results/plot_exclusion_scatter_MZ.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5 - Download the results\n",
    "\n",
    "Download the result files from\n",
    "[download_results/IODA_OpenMS_exclusion.zip](download_results/IODA_exclusion_from_mzML.zip?download=1)\n",
    "\n",
    "### Step 6 - Prepare your acquisition method\n",
    "For instructions on how to load and configure an exclusion list with XCalibur or MaxQuant.Live please refer to [the following documentation](nothing)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:python3]",
   "language": "python",
   "name": "conda-env-python3-py"
  },
  "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.7.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}