interactive_combiner_runner.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# File Joining and slicing with i2nca"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "With this notebook, Operation on joining and sclicing imzML files are demonstrated. Currentyl, the following operations are supported:\n",
    "\n",
    "- **File Joining**:\n",
    "Join two or more imzML files into one large imzML file.\n",
    "\n",
    "- **Subsampling from a file**:\n",
    "Cut a defined chunk out of an imzML file. Useful for very large images.\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "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."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "# Imports\n",
    "\n",
    "Before you can start the tools, load the required tools and libraries.\n",
    "\n",
    "PLEASE RUN THE CELL BELOW WITHOUT CHANGES"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import i2nca as i2\n",
    "import m2aia as m2"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Combine different files\n",
    "\n",
    "This tool allows the combination of different imzML files. They will be joint together into a single file.\n",
    "Due to this, they will be written as a processed imzML file. Apply the corresponing i2nca convertsion tool to obtain continous formats."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "THE CELL BELOW NEEDS YOUR INPUT\n",
    "\n",
    "Please change the following  variables in order to load the dataset:\n",
    "- `input_data_list`: Please provide a list of paths to the imzML files 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",
    "\n",
    "- `output_filepath`: Please provide a valid path for the imzML file and other outputs on your machine."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "input_data_list = [\"...path/to/.../file_1.imzML\",\n",
    "                   \"...path/to/.../file_1.imzML\",\n",
    "                   \"...path/to/.../file_1.imzML\"]\n",
    "\n",
    "output_filepath = \"...path/.../to/.../outputfile/.../filemname\""
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "THE CELL BELOW NEEDS YOUR INPUT\n",
    "\n",
    "Please change the following  variables in order to load the dataset:\n",
    "- `normalization_method`: Before the files are joined, they each are normalized internally. Provide a string to a valid Normalization method. to skip this, use \"None\".\n",
    "\n",
    "- `padding_distance`: Fix how much empty pixels should be between two neighbouring images.\n",
    "\n",
    "- `nr_columns`: Fix a number of coulmns. The rows are filled bottom-up according to this.\n",
    "\n",
    "- `overwrite_polarity`: Use this to overwrite polatity with the provided one. Useful for batches, where that info is missing. Please note that you should only use this if you are sure that no false information will be integrated in the data by this."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Additional parameters\n",
    "normalization_method = \"RMS\" # \"RMS\", \"TIC\", \"None\"\n",
    "\n",
    "padding_distance = 10\n",
    "\n",
    "nr_columns = 5\n",
    "\n",
    "overwrite_polarity =\"None\"  # \"None\", \"poitive\", \"negative\""
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "By running the following line, the files will be combined. To translate other annotations, a matrix with the old and new positions will be generated at the output location as well."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "i2.combine_datasets_imzml(input_data_list,\n",
    "                          output_filepath,\n",
    "                          normalization_method,\n",
    "                           padding_distance,\n",
    "                           nr_columns,\n",
    "                           overwrite_polarity)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Cut file in subsamples\n",
    "\n",
    "Similar two joining mulitple files, a singe file can aslo be cut into different files based on a Region-of-Interest annotation. A ROI annotation needs a cloumn with \"x\", \"y\", and \"annotation\" in order to run. Make sure that the tsv file supplies this."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "input_data = \"...path/to/.../file.imzML\"\n",
    "\n",
    "input_rois = \"...path/to/ROI-annotation.tsv\"\n",
    "\n",
    "output_filepath = \"...path/.../to/.../outputfile/.../filemname\""
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "With the ROIs, the imzML file is cut up. The newly generated files are named after the ROI annotation in the tsv file."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "i2.cut_dataset_imzml(input_data, input_rois, output_filepath)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "If you do not have a ROI annotation or are unsure how to make it, try to run the region_QC tool. This will provide you with a ROI annotaion based on neighbouring pixel groups. Check this file to see if your ROI-file follows the required format. The tsv file is generated at the output_filepath."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "I = m2.ImzMLReader(input_data)\n",
    "i2.report_regions_qc(I,output_filepath)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}