interactive_QC_runner.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Creating QC reports with i2nca"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "With this notebook, Quality control reports can be generated from an .imzML file.\n",
    "There are three different QCtools available:\n",
    "\n",
    "- **agnostic_qc**:\n",
    "Takes only the .imzML file as input and generates an output file at the specified location.\n",
    "The file is evaluated and different metrics are applied to it.\n",
    "\n",
    "- **calibrant_qc**:\n",
    "Additionally to the imzML file, a file with masses of calibrants is provided.\n",
    "this QC tool evaluates how the spectra look around each calibrant and calculates metrics. Additionally, the spectrum of each pixel gets evaluated and the nearest peak is set into relation on how far the peak is from the theoretical value\n",
    "\n",
    "- **region_qc**:\n",
    "Together with the imzML file, a region annotation is loaded. The QC calculates the metrics for each region and compares them.\n",
    "If no region file is provided, one is automatically generated where connected pixels are grouped and a annotation file is generated.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# A very short introduction to jupyter\n",
    "If you are not familiar with jupyter notebooks, they are a really cool way how to make code accessible for people with little to no experience in coding. Please think of this as a nice text document that allows you to send some defined code boxes into a happy place where they get taken care of.\n",
    "Everything inside this document is organized in cells. Some cells contain a special kind of text (markdown) and some contain python code.\n",
    "All you need to do is to \"run\" a cell to make the code inside do its funky stuff. You can do this ususally by hitting a play-button in the upper menu (it should say \"Run Cell or Execute Cell\") or by right-clicking a cell and using the \"Run / Execute / ...\" statement."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Imports\n",
    "\n",
    "Before you can start the QC tools, load the required tools and libraries."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "\n",
    "PLEASE RUN THE CELL BELOW WITHOUT CHANGES"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "is_executing": true,
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# import statements\n",
    "import m2aia as m2\n",
    "from i2nca import report_agnostic_qc,  report_calibrant_qc, report_regions_qc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Loading a dataset\n",
    "\n",
    "To start a QC, you need to first load the imzML dataset. It needs to be loaded only once for all the QCs (this also makes the process quicker)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "THE CELL BELOW NEEDS YOUR INPUT\n",
    "\n",
    "Please change the following  variables in order to load the dataset:\n",
    "- `file_path`: Please provide a path to the imzML file on your machine. It must end with the full filename (`name` and `\".imzML\"`). Using the  `r\"...\"` notation allows to add windows-style paths without escaping each backslash.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "file_path = r\".../path/to/file/.../filename.imzML\"\n",
    "I = m2.ImzMLReader(file_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Agnostic QC\n",
    "\n",
    "To make a agnostic QC, we can use the  `report_agnostic_qc` function. Running this function will create a QC report as a pdf at a specifeid location. Inside the agnostic QC, different reports, graphs and images will be created for the dataset that do not assume anything on the type of experiment that was performed (hence the name \"agnostic\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "THE FOLLOWING CELL NEEDS YOUR INPUT\n",
    "\n",
    "Please change the variable `output_filepath` to a path on your machine. The output pdf will be saved there."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n",
     "is_executing": true
    }
   },
   "outputs": [],
   "source": [
    "output_filepath = r\".../path/to/file/.../file-name\""
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "PLEASE RUN THE CELL BELOW WITHOUT CHANGES\n",
    "\n",
    "An agnostic QC report will be created."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "report_agnostic_qc(I,output_filepath)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Calibrant QC\n",
    "\n",
    "In order to get a comparison between some calibrants (or other mz values that are of interest), the function  `report_calibrant_qc` creates a report where a comparison between the dataset and some refence mz values are compared.\n",
    "For this, some additional parameters need to be specified."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "THE FOLLOWING CELL NEEDS YOUR INPUT\n",
    "\n",
    "Please change the following variables in order to create a Calibrant QC:\n",
    "- `output_filepath`: Please provide a path on your machine. The output pdf will be saved there.\n",
    "\n",
    "- `calibrants_csv_file`: Please provide a file with the calibrant masses. Use a csv file with \";\" as delimiter. The column with the mz values must be called \"mz\" and the column with an identifier must be called \"name\".\n",
    "\n",
    "\n",
    "- `accuracy`: A parameter for the calculation of accuracy metrics. Only datapoints inside an interval of `accuracy` around any of the `calibrants_file` values are considered for the determination of different metrics. It is provided in ppm.\n",
    "\n",
    "- `coverage`: The coverage is a subsetting method for large datasets. A coverage of 0.3 means that the pixels get subsetted amounting to 30% of the full measurent. This allows faster computation for large datasets. For small datasets, the value should be 1.0\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n",
     "is_executing": true
    }
   },
   "outputs": [],
   "source": [
    "output_filepath =r\".../path/to/file/.../output_filename\"\n",
    "calibrants_csv_file = r\".../path/to/file/.../calibrants.csv\"\n",
    "\n",
    "accuracy = 100  # interval in ppm\n",
    "coverage = 1.0 # value between 0 and 1"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "PLEASE RUN THE CELL BELOW WITHOUT CHANGES\n",
    "\n",
    "An calibrant QC report will be created."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "report_calibrant_qc(I, output_filepath, calibrants_csv_file, accuracy, coverage)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Region QC\n",
    "\n",
    "The `report_region_qc` allows to compare some regions and see the differences in the data set with different metrics.\n",
    "For this, an additional annotation is required separating the dataset into different regions. If this is not provided, the QC report will automatically generate a annotation all the pixels presented in the dataset by the conected object they belong to (neighbouring pixels are conuted as one object)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "THE FOLLOWING CELL NEEDS YOUR INPUT\n",
    "\n",
    "Please change the following variables in order to create a Calibrant QC:\n",
    "- `output_filepath`: Please provide a path on your machine. The output pdf will be saved there.\n",
    "\n",
    "- `region_tsv_file`: Please optionally provide a tsv file with annotations. The pixels need to be annotated with their x and y position and any keyword for their annotation. pixels with the same keyword get grouped into one region. the column with the x position must be called \"x\", the y position \"y\" and the column in which the groups are defined must be called \"annotation\". \\\n",
    "If no regions are annotated, set this paramer to `False`. Then, a annotation will be created automatically.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n",
     "is_executing": true
    }
   },
   "outputs": [],
   "source": [
    "output_filepath = r\".../path/to/file/.../file-name\"\n",
    "region_tsv_file = r\".../path/to/file/.../region_annotation.tsv\""
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "PLEASE RUN THE CELL BELOW WITHOUT CHANGES\n",
    "\n",
    "An region QC report will be created."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "report_regions_qc(I,output_filepath)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}