{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Building Ion Tables\n\n:mod:`interferences` core funciton is to generate, filter and visualise tables\nof isotope-specified small inorganic ionic molecules. This example demonstrates how\nto build a small table of ions, and some of the options available. Note that as\n:mod:`interferences` is largely built around :mod:`pandas`, you can expect to be\nworking with :class:`~pandas.DataFrame` objects most of the time.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import pandas as pd\nfrom interferences.table import build_table"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In the simplest case, where you have a list of elments you want to find viable set of\nions which they may produce, you can simply specify these elements in a call to\n:func:`~interferences.table.build_table`:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"])\ndf.info()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Note that the table is indexed by the ions themselves, with the respective mass/charge\nratio found under the `m_z` column. Even with a small set of elements, with the\ncombination of isotopes, we've generated a fair number of potential ions:\n\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df.index.size"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "As this is probably more ions than you want to consider, let's narrow the foucs\nusing a mass window (here for $39 \\ge m/z \\le 41$):\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"], window=(39, 41))\ndf.index.size"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "While you can use m/z ratios if you know them specifically, it's likely more useful\nto specify an ion mass and a mass-window either side, which you can do as follows:\n\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"], window=(\"Ca[40]\", 0.01))\ndf.index.size"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "By default, :mod:`interferences` builds ions for molecules with up to three atoms\nwith ionic charges of either `+1` or `+2` (note the sign of the charge is largely\nirrelevant, given a mass spectrometer will be set up for either positive or negative\nions). If you wanted to use different parameters to generate a table, you can use the\n`max_atoms` and `charges` keyword arguemnts:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"], charges=[1], max_atoms=2)\ndf.index.size"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Also, to save time for futher computation, :mod:`interferences` uses a local\nHDFStore to cache results. You can disable this behaviour and gain some speed\nif you're generating one-off large tables by using :code:`cache_results=False`:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"], cache_results=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "If you're finding that you end up with a table which includes minor ions which\nlikely have too low an isotopic abundance to influence results, you can\nuse the `threshold` keyword argument to adjust the isotopic abundance threshold for\nisotopes used to build the table. Note that these won't be added to the cached\nreference:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"N\", \"K\"], threshold=0.5)\ndf.index.size"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally, if you're likely to do some plotting with the ion data, you can specify\nthis using the `add_labels` keyword argument, which will add nicely formatted labels\ncomapatible with :mod:`matplotlib`:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "df = build_table([\"Ca\", \"O\", \"Ar\", \"H\"], add_labels=True)"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "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.7.9"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}