{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "19917597",
   "metadata": {},
   "source": [
    "# Quick Start\n",
    "\n",
    "This python script describes how to use `LiRTMaTS` python package. The\n",
    "input data and retention time reference files used here are in\n",
    "https://github.com/wanchanglin/lirtmats/tree/master/examples/data.\n",
    "\n",
    "## Setup\n",
    "\n",
    "The users need to load python package `LAMP` before using `LiRTMaTS`. It's\n",
    "functions used here are for loading data set and summarising the matching\n",
    "results. For details, see https://github.com/wanchanglin/lamp."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b045fb5c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:41.718675Z",
     "iopub.status.busy": "2025-12-04T12:29:41.718675Z",
     "iopub.status.idle": "2025-12-04T12:29:42.611230Z",
     "shell.execute_reply": "2025-12-04T12:29:42.610197Z"
    }
   },
   "outputs": [],
   "source": [
    "import sqlite3\n",
    "import pandas as pd\n",
    "from lamp import anno\n",
    "import lirtmats.lirtmats as rtm"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4c99a20",
   "metadata": {},
   "source": [
    "## Data Loading\n",
    "\n",
    "`LiRTMaTS` supports text files separated by comma (`,`) or tab (`\\t`).\n",
    "The Microsoft's XLSX is also supported, using argument `sheet_name` to\n",
    "indicate which sheet is used for input data. The default is 0 for the\n",
    "first sheet.\n",
    "\n",
    "Here we use a small example data set with `tsv` format. This data set\n",
    "includes peak list and intensity data matrix. `LiRTMaTS` requires peak\n",
    "list's name, m/z value and retention time. User needs to indicate the\n",
    "locations of feature name, m/z value, retention time and starting points\n",
    "of data matrix from data. Here they are 1, 2, 3 and 4, respectively.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "aae9685b",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:42.611230Z",
     "iopub.status.busy": "2025-12-04T12:29:42.611230Z",
     "iopub.status.idle": "2025-12-04T12:29:42.662591Z",
     "shell.execute_reply": "2025-12-04T12:29:42.662591Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>mz</th>\n",
       "      <th>rt</th>\n",
       "      <th>D121</th>\n",
       "      <th>A122</th>\n",
       "      <th>A125</th>\n",
       "      <th>A126</th>\n",
       "      <th>A127</th>\n",
       "      <th>A128</th>\n",
       "      <th>B131</th>\n",
       "      <th>...</th>\n",
       "      <th>E214</th>\n",
       "      <th>E215</th>\n",
       "      <th>E216</th>\n",
       "      <th>H234</th>\n",
       "      <th>H235</th>\n",
       "      <th>H236</th>\n",
       "      <th>H237</th>\n",
       "      <th>H238</th>\n",
       "      <th>H239</th>\n",
       "      <th>H240</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>M102T899</td>\n",
       "      <td>102.034153</td>\n",
       "      <td>898.850160</td>\n",
       "      <td>1.404584e+07</td>\n",
       "      <td>3.689953e+06</td>\n",
       "      <td>3.598363e+06</td>\n",
       "      <td>1.138875e+07</td>\n",
       "      <td>4.887524e+06</td>\n",
       "      <td>2.104782e+06</td>\n",
       "      <td>7.288258e+06</td>\n",
       "      <td>...</td>\n",
       "      <td>3.125203e+06</td>\n",
       "      <td>3.608369e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>4.763811e+06</td>\n",
       "      <td>2.281365e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>3.404450e+06</td>\n",
       "      <td>3.720441e+06</td>\n",
       "      <td>4.539032e+05</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>M102T849</td>\n",
       "      <td>102.034154</td>\n",
       "      <td>849.085350</td>\n",
       "      <td>1.473961e+07</td>\n",
       "      <td>NaN</td>\n",
       "      <td>5.934387e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>4.607624e+06</td>\n",
       "      <td>5.969186e+06</td>\n",
       "      <td>3.367949e+06</td>\n",
       "      <td>...</td>\n",
       "      <td>1.276006e+07</td>\n",
       "      <td>1.490770e+07</td>\n",
       "      <td>2.880142e+06</td>\n",
       "      <td>4.263577e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>4.437697e+06</td>\n",
       "      <td>6.777076e+06</td>\n",
       "      <td>6.341930e+06</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>105.042677</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>5.520865e+05</td>\n",
       "      <td>1.813279e+05</td>\n",
       "      <td>2.734923e+05</td>\n",
       "      <td>2.342655e+05</td>\n",
       "      <td>6.241395e+04</td>\n",
       "      <td>1.068277e+05</td>\n",
       "      <td>1.192451e+05</td>\n",
       "      <td>...</td>\n",
       "      <td>3.092946e+04</td>\n",
       "      <td>1.788324e+05</td>\n",
       "      <td>1.810794e+05</td>\n",
       "      <td>3.225256e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>3.734778e+05</td>\n",
       "      <td>1.935349e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>1.094705e+05</td>\n",
       "      <td>1.946732e+05</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>M105T54</td>\n",
       "      <td>105.054961</td>\n",
       "      <td>54.350049</td>\n",
       "      <td>6.669635e+05</td>\n",
       "      <td>4.833251e+06</td>\n",
       "      <td>2.137479e+06</td>\n",
       "      <td>1.552473e+06</td>\n",
       "      <td>1.753294e+06</td>\n",
       "      <td>2.301363e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>...</td>\n",
       "      <td>1.186390e+06</td>\n",
       "      <td>3.001167e+06</td>\n",
       "      <td>2.558921e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>1.695460e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>1.834140e+06</td>\n",
       "      <td>1.029692e+06</td>\n",
       "      <td>4.382618e+05</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>M105T48_1</td>\n",
       "      <td>105.074216</td>\n",
       "      <td>47.538626</td>\n",
       "      <td>6.310113e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>5.199302e+05</td>\n",
       "      <td>4.302566e+05</td>\n",
       "      <td>5.650141e+05</td>\n",
       "      <td>3.635406e+05</td>\n",
       "      <td>1.096530e+06</td>\n",
       "      <td>...</td>\n",
       "      <td>7.882748e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>9.822090e+05</td>\n",
       "      <td>4.974403e+05</td>\n",
       "      <td>3.604541e+05</td>\n",
       "      <td>1.340656e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>6.020203e+05</td>\n",
       "      <td>3.597655e+05</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1995</th>\n",
       "      <td>M299T296</td>\n",
       "      <td>299.233645</td>\n",
       "      <td>295.569540</td>\n",
       "      <td>8.125150e+04</td>\n",
       "      <td>1.020165e+05</td>\n",
       "      <td>2.209362e+05</td>\n",
       "      <td>3.557402e+05</td>\n",
       "      <td>6.039153e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.330915e+05</td>\n",
       "      <td>...</td>\n",
       "      <td>3.872671e+05</td>\n",
       "      <td>1.632064e+05</td>\n",
       "      <td>7.224218e+04</td>\n",
       "      <td>3.678394e+04</td>\n",
       "      <td>9.526812e+04</td>\n",
       "      <td>5.785549e+04</td>\n",
       "      <td>6.183749e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.915690e+04</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1996</th>\n",
       "      <td>M300T43_1</td>\n",
       "      <td>299.919504</td>\n",
       "      <td>42.832066</td>\n",
       "      <td>5.042924e+04</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.222376e+05</td>\n",
       "      <td>3.763288e+05</td>\n",
       "      <td>2.094474e+05</td>\n",
       "      <td>1.163715e+05</td>\n",
       "      <td>...</td>\n",
       "      <td>4.035525e+05</td>\n",
       "      <td>2.032260e+05</td>\n",
       "      <td>2.700920e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.675647e+05</td>\n",
       "      <td>2.695188e+05</td>\n",
       "      <td>2.750383e+05</td>\n",
       "      <td>2.882957e+05</td>\n",
       "      <td>6.720465e+04</td>\n",
       "      <td>3.352428e+05</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1997</th>\n",
       "      <td>M300T62</td>\n",
       "      <td>300.119720</td>\n",
       "      <td>62.428854</td>\n",
       "      <td>NaN</td>\n",
       "      <td>3.914945e+05</td>\n",
       "      <td>5.182468e+05</td>\n",
       "      <td>7.492101e+05</td>\n",
       "      <td>1.546338e+06</td>\n",
       "      <td>5.741346e+05</td>\n",
       "      <td>9.712791e+05</td>\n",
       "      <td>...</td>\n",
       "      <td>8.554399e+05</td>\n",
       "      <td>7.431820e+05</td>\n",
       "      <td>8.878200e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>3.625514e+05</td>\n",
       "      <td>4.987110e+05</td>\n",
       "      <td>1.393237e+06</td>\n",
       "      <td>5.217566e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>1.257126e+05</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1998</th>\n",
       "      <td>M300T285_2</td>\n",
       "      <td>300.124255</td>\n",
       "      <td>285.061758</td>\n",
       "      <td>NaN</td>\n",
       "      <td>4.602130e+05</td>\n",
       "      <td>4.559729e+05</td>\n",
       "      <td>9.718658e+05</td>\n",
       "      <td>3.864969e+05</td>\n",
       "      <td>3.877729e+05</td>\n",
       "      <td>1.315307e+06</td>\n",
       "      <td>...</td>\n",
       "      <td>2.418197e+06</td>\n",
       "      <td>2.917536e+06</td>\n",
       "      <td>9.108396e+05</td>\n",
       "      <td>4.583314e+05</td>\n",
       "      <td>4.022556e+05</td>\n",
       "      <td>2.673259e+05</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>8.926295e+04</td>\n",
       "      <td>2.126753e+04</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1999</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>300.181271</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>7.880306e+05</td>\n",
       "      <td>1.738638e+06</td>\n",
       "      <td>1.113482e+06</td>\n",
       "      <td>4.063701e+06</td>\n",
       "      <td>3.788191e+06</td>\n",
       "      <td>1.201084e+06</td>\n",
       "      <td>2.988076e+06</td>\n",
       "      <td>...</td>\n",
       "      <td>2.907005e+06</td>\n",
       "      <td>3.365814e+06</td>\n",
       "      <td>2.761628e+06</td>\n",
       "      <td>1.865813e+06</td>\n",
       "      <td>1.956308e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.918514e+06</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>2000 rows × 40 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "            name          mz          rt          D121          A122  \\\n",
       "0       M102T899  102.034153  898.850160  1.404584e+07  3.689953e+06   \n",
       "1       M102T849  102.034154  849.085350  1.473961e+07           NaN   \n",
       "2        M105T45  105.042677   45.353942  5.520865e+05  1.813279e+05   \n",
       "3        M105T54  105.054961   54.350049  6.669635e+05  4.833251e+06   \n",
       "4      M105T48_1  105.074216   47.538626  6.310113e+05           NaN   \n",
       "...          ...         ...         ...           ...           ...   \n",
       "1995    M299T296  299.233645  295.569540  8.125150e+04  1.020165e+05   \n",
       "1996   M300T43_1  299.919504   42.832066  5.042924e+04           NaN   \n",
       "1997     M300T62  300.119720   62.428854           NaN  3.914945e+05   \n",
       "1998  M300T285_2  300.124255  285.061758           NaN  4.602130e+05   \n",
       "1999    M300T288  300.181271  287.944377  7.880306e+05  1.738638e+06   \n",
       "\n",
       "              A125          A126          A127          A128          B131  \\\n",
       "0     3.598363e+06  1.138875e+07  4.887524e+06  2.104782e+06  7.288258e+06   \n",
       "1     5.934387e+06           NaN  4.607624e+06  5.969186e+06  3.367949e+06   \n",
       "2     2.734923e+05  2.342655e+05  6.241395e+04  1.068277e+05  1.192451e+05   \n",
       "3     2.137479e+06  1.552473e+06  1.753294e+06  2.301363e+06           NaN   \n",
       "4     5.199302e+05  4.302566e+05  5.650141e+05  3.635406e+05  1.096530e+06   \n",
       "...            ...           ...           ...           ...           ...   \n",
       "1995  2.209362e+05  3.557402e+05  6.039153e+05           NaN  2.330915e+05   \n",
       "1996           NaN  2.222376e+05  3.763288e+05  2.094474e+05  1.163715e+05   \n",
       "1997  5.182468e+05  7.492101e+05  1.546338e+06  5.741346e+05  9.712791e+05   \n",
       "1998  4.559729e+05  9.718658e+05  3.864969e+05  3.877729e+05  1.315307e+06   \n",
       "1999  1.113482e+06  4.063701e+06  3.788191e+06  1.201084e+06  2.988076e+06   \n",
       "\n",
       "      ...          E214          E215          E216          H234  \\\n",
       "0     ...  3.125203e+06  3.608369e+06           NaN  4.763811e+06   \n",
       "1     ...  1.276006e+07  1.490770e+07  2.880142e+06  4.263577e+06   \n",
       "2     ...  3.092946e+04  1.788324e+05  1.810794e+05  3.225256e+05   \n",
       "3     ...  1.186390e+06  3.001167e+06  2.558921e+06           NaN   \n",
       "4     ...  7.882748e+05           NaN  9.822090e+05  4.974403e+05   \n",
       "...   ...           ...           ...           ...           ...   \n",
       "1995  ...  3.872671e+05  1.632064e+05  7.224218e+04  3.678394e+04   \n",
       "1996  ...  4.035525e+05  2.032260e+05  2.700920e+05           NaN   \n",
       "1997  ...  8.554399e+05  7.431820e+05  8.878200e+05           NaN   \n",
       "1998  ...  2.418197e+06  2.917536e+06  9.108396e+05  4.583314e+05   \n",
       "1999  ...  2.907005e+06  3.365814e+06  2.761628e+06  1.865813e+06   \n",
       "\n",
       "              H235          H236          H237          H238          H239  \\\n",
       "0     2.281365e+06           NaN  3.404450e+06  3.720441e+06  4.539032e+05   \n",
       "1              NaN           NaN           NaN  4.437697e+06  6.777076e+06   \n",
       "2              NaN  3.734778e+05  1.935349e+05           NaN  1.094705e+05   \n",
       "3              NaN  1.695460e+06           NaN  1.834140e+06  1.029692e+06   \n",
       "4     3.604541e+05  1.340656e+06           NaN           NaN  6.020203e+05   \n",
       "...            ...           ...           ...           ...           ...   \n",
       "1995  9.526812e+04  5.785549e+04  6.183749e+05           NaN  2.915690e+04   \n",
       "1996  2.675647e+05  2.695188e+05  2.750383e+05  2.882957e+05  6.720465e+04   \n",
       "1997  3.625514e+05  4.987110e+05  1.393237e+06  5.217566e+05           NaN   \n",
       "1998  4.022556e+05  2.673259e+05           NaN           NaN  8.926295e+04   \n",
       "1999  1.956308e+06           NaN  2.918514e+06           NaN           NaN   \n",
       "\n",
       "              H240  \n",
       "0              NaN  \n",
       "1     6.341930e+06  \n",
       "2     1.946732e+05  \n",
       "3     4.382618e+05  \n",
       "4     3.597655e+05  \n",
       "...            ...  \n",
       "1995           NaN  \n",
       "1996  3.352428e+05  \n",
       "1997  1.257126e+05  \n",
       "1998  2.126753e+04  \n",
       "1999           NaN  \n",
       "\n",
       "[2000 rows x 40 columns]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cols = [1, 2, 3, 4]\n",
    "data_fn = \"./data/df_pos_3.tsv\"                 # use tsv file\n",
    "df = anno.read_peak(data_fn, cols, sep='\\t')\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "719fc2c2",
   "metadata": {},
   "source": [
    "Data frame `df` now includes only `name`, `mz`, `rt` and intensity data\n",
    "matrix.\n",
    "\n",
    "## Retention Time Matching\n",
    "\n",
    "To perform retention time matching, users use either default retention\n",
    "time library or their own reference file. The reference file must have one\n",
    "column: `rt_lib` which is used for retention time matching with a range or\n",
    "torrance in seconds. Also the column `ion_mode` should be required for\n",
    "indication of positive or negative mode matching. If `ion_mode` is not\n",
    "included in the reference file, all rows will be used for matching.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f11caa11",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:42.665135Z",
     "iopub.status.busy": "2025-12-04T12:29:42.665135Z",
     "iopub.status.idle": "2025-12-04T12:29:42.686202Z",
     "shell.execute_reply": "2025-12-04T12:29:42.686202Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>identifier</th>\n",
       "      <th>metabolite_name</th>\n",
       "      <th>rt_lib</th>\n",
       "      <th>inchikey</th>\n",
       "      <th>ion_mod</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>ACMG_aqC18_POS_0001</td>\n",
       "      <td>MS5029_Isovaleraldehyde</td>\n",
       "      <td>24.6</td>\n",
       "      <td>QPUYECUOLPXSFR-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>ACMG_aqC18_POS_0002</td>\n",
       "      <td>LO57_Dihydroxyfumaric acid hydrate</td>\n",
       "      <td>27.0</td>\n",
       "      <td>SEKGMJVHSBBHRD-WZHZPDAFSA-M</td>\n",
       "      <td>positive</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>ACMG_aqC18_POS_0003</td>\n",
       "      <td>LO61_Benzoic acid</td>\n",
       "      <td>27.0</td>\n",
       "      <td>DMBUODUULYCPAK-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>ACMG_aqC18_POS_0004</td>\n",
       "      <td>LO52_Spermine</td>\n",
       "      <td>28.2</td>\n",
       "      <td>XDSPGKDYYRNYJI-IUPFWZBJSA-N</td>\n",
       "      <td>positive</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>ACMG_aqC18_POS_0005</td>\n",
       "      <td>LO21_Spermidine</td>\n",
       "      <td>30.0</td>\n",
       "      <td>HELXLJCILKEWJH-NCGAPWICSA-N</td>\n",
       "      <td>positive</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2827</th>\n",
       "      <td>ACMG_aqC18_POS_1412</td>\n",
       "      <td>LIM3312_Cholesterol</td>\n",
       "      <td>659.4</td>\n",
       "      <td>ASOSVCXGWPDUGN-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2828</th>\n",
       "      <td>ACMG_aqC18_POS_1413</td>\n",
       "      <td>LO13_5alpha-Cholestan-3-one</td>\n",
       "      <td>672.6</td>\n",
       "      <td>XQCZBXHVTFVIFE-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2829</th>\n",
       "      <td>ACMG_aqC18_POS_1414</td>\n",
       "      <td>LIM3310_5alpha-Cholest-7-en-3beta-ol</td>\n",
       "      <td>675.0</td>\n",
       "      <td>WLFXSECCHULRRO-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2830</th>\n",
       "      <td>ACMG_aqC18_POS_1415</td>\n",
       "      <td>LO302_5alpha-Cholestanol</td>\n",
       "      <td>681.6</td>\n",
       "      <td>YCIMNLLNPGFGHC-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2831</th>\n",
       "      <td>ACMG_aqC18_POS_1416</td>\n",
       "      <td>LO45_10Z-Nonadecenoic acid</td>\n",
       "      <td>723.6</td>\n",
       "      <td>QIGBRXMKCJKVMJ-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>2832 rows × 5 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "               identifier                       metabolite_name  rt_lib  \\\n",
       "0     ACMG_aqC18_POS_0001               MS5029_Isovaleraldehyde    24.6   \n",
       "1     ACMG_aqC18_POS_0002    LO57_Dihydroxyfumaric acid hydrate    27.0   \n",
       "2     ACMG_aqC18_POS_0003                     LO61_Benzoic acid    27.0   \n",
       "3     ACMG_aqC18_POS_0004                         LO52_Spermine    28.2   \n",
       "4     ACMG_aqC18_POS_0005                       LO21_Spermidine    30.0   \n",
       "...                   ...                                   ...     ...   \n",
       "2827  ACMG_aqC18_POS_1412                   LIM3312_Cholesterol   659.4   \n",
       "2828  ACMG_aqC18_POS_1413           LO13_5alpha-Cholestan-3-one   672.6   \n",
       "2829  ACMG_aqC18_POS_1414  LIM3310_5alpha-Cholest-7-en-3beta-ol   675.0   \n",
       "2830  ACMG_aqC18_POS_1415              LO302_5alpha-Cholestanol   681.6   \n",
       "2831  ACMG_aqC18_POS_1416            LO45_10Z-Nonadecenoic acid   723.6   \n",
       "\n",
       "                         inchikey   ion_mod  \n",
       "0     QPUYECUOLPXSFR-UHFFFAOYSA-N  positive  \n",
       "1     SEKGMJVHSBBHRD-WZHZPDAFSA-M  positive  \n",
       "2     DMBUODUULYCPAK-UHFFFAOYSA-N  positive  \n",
       "3     XDSPGKDYYRNYJI-IUPFWZBJSA-N  positive  \n",
       "4     HELXLJCILKEWJH-NCGAPWICSA-N  positive  \n",
       "...                           ...       ...  \n",
       "2827  ASOSVCXGWPDUGN-UHFFFAOYSA-N  negative  \n",
       "2828  XQCZBXHVTFVIFE-UHFFFAOYSA-N  negative  \n",
       "2829  WLFXSECCHULRRO-UHFFFAOYSA-N  negative  \n",
       "2830  YCIMNLLNPGFGHC-UHFFFAOYSA-N  negative  \n",
       "2831  QIGBRXMKCJKVMJ-UHFFFAOYSA-N  negative  \n",
       "\n",
       "[2832 rows x 5 columns]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ion_mode = \"pos\"\n",
    "# ref_path = \"\"  # if empty, use default reference file for matching\n",
    "ref_path = \"./data/rt_lib_202509.tsv\"\n",
    "ref = rtm.read_rt(ref_path, ion_mode=ion_mode)\n",
    "ref"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2559f87",
   "metadata": {},
   "source": [
    "`rt_tol` is a threshold for the retention time matching window. The unit\n",
    " is seconds and the default value is 5."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "1e2067e8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:42.686202Z",
     "iopub.status.busy": "2025-12-04T12:29:42.686202Z",
     "iopub.status.idle": "2025-12-04T12:29:44.329388Z",
     "shell.execute_reply": "2025-12-04T12:29:44.329388Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>id</th>\n",
       "      <th>rt</th>\n",
       "      <th>identifier</th>\n",
       "      <th>metabolite_name</th>\n",
       "      <th>rt_lib</th>\n",
       "      <th>inchikey</th>\n",
       "      <th>ion_mod</th>\n",
       "      <th>rt_range</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>ACMG_aqC18_POS_0280</td>\n",
       "      <td>LO309_Asymmetric dimethylarginine</td>\n",
       "      <td>40.5</td>\n",
       "      <td>ZDLDXNCMJBOYJV-YFKPBYRVSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>ACMG_aqC18_POS_0281</td>\n",
       "      <td>MS5037_Ribonic acid gamma-lactone</td>\n",
       "      <td>40.5</td>\n",
       "      <td>DAUAQNGYDSHRET-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>ACMG_aqC18_POS_0282</td>\n",
       "      <td>LO18_L-Dihydroorotic acid</td>\n",
       "      <td>40.5</td>\n",
       "      <td>KCDXJAYRVLXPFO-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>ACMG_aqC18_POS_0283</td>\n",
       "      <td>LO30_Stachydrine</td>\n",
       "      <td>40.5</td>\n",
       "      <td>ITECRQOOEQWFPE-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>M105T45</td>\n",
       "      <td>45.353942</td>\n",
       "      <td>ACMG_aqC18_POS_0284</td>\n",
       "      <td>LO72_Aminoadipic acid</td>\n",
       "      <td>40.5</td>\n",
       "      <td>JYPHNHPXFNEZBR-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150065</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>ACMG_aqC18_POS_0942</td>\n",
       "      <td>MS5008_Ethyl crotonate</td>\n",
       "      <td>291.0</td>\n",
       "      <td>OZWKMVRBQXNZKK-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150066</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>ACMG_aqC18_POS_0943</td>\n",
       "      <td>MS5032_2-Phenyl-1-propanol</td>\n",
       "      <td>291.0</td>\n",
       "      <td>DKYWVDODHFEZIM-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150067</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>ACMG_aqC18_POS_0944</td>\n",
       "      <td>LO15_Methyl indole-3-acetate</td>\n",
       "      <td>291.0</td>\n",
       "      <td>RTIXKCRFFJGDFG-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150068</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>ACMG_aqC18_POS_0945</td>\n",
       "      <td>LO03_Cinnamic aldehyde</td>\n",
       "      <td>291.6</td>\n",
       "      <td>FNYLWPVRPXGIIP-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150069</th>\n",
       "      <td>M300T288</td>\n",
       "      <td>287.944377</td>\n",
       "      <td>ACMG_aqC18_POS_0945</td>\n",
       "      <td>LO03_Cinnamic aldehyde</td>\n",
       "      <td>291.6</td>\n",
       "      <td>FNYLWPVRPXGIIP-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>150070 rows × 8 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "              id          rt           identifier  \\\n",
       "0        M105T45   45.353942  ACMG_aqC18_POS_0280   \n",
       "1        M105T45   45.353942  ACMG_aqC18_POS_0281   \n",
       "2        M105T45   45.353942  ACMG_aqC18_POS_0282   \n",
       "3        M105T45   45.353942  ACMG_aqC18_POS_0283   \n",
       "4        M105T45   45.353942  ACMG_aqC18_POS_0284   \n",
       "...          ...         ...                  ...   \n",
       "150065  M300T288  287.944377  ACMG_aqC18_POS_0942   \n",
       "150066  M300T288  287.944377  ACMG_aqC18_POS_0943   \n",
       "150067  M300T288  287.944377  ACMG_aqC18_POS_0944   \n",
       "150068  M300T288  287.944377  ACMG_aqC18_POS_0945   \n",
       "150069  M300T288  287.944377  ACMG_aqC18_POS_0945   \n",
       "\n",
       "                          metabolite_name rt_lib                     inchikey  \\\n",
       "0       LO309_Asymmetric dimethylarginine   40.5  ZDLDXNCMJBOYJV-YFKPBYRVSA-N   \n",
       "1       MS5037_Ribonic acid gamma-lactone   40.5  DAUAQNGYDSHRET-UHFFFAOYSA-N   \n",
       "2               LO18_L-Dihydroorotic acid   40.5  KCDXJAYRVLXPFO-UHFFFAOYSA-N   \n",
       "3                        LO30_Stachydrine   40.5  ITECRQOOEQWFPE-UHFFFAOYSA-N   \n",
       "4                   LO72_Aminoadipic acid   40.5  JYPHNHPXFNEZBR-UHFFFAOYSA-N   \n",
       "...                                   ...    ...                          ...   \n",
       "150065             MS5008_Ethyl crotonate  291.0  OZWKMVRBQXNZKK-UHFFFAOYSA-N   \n",
       "150066         MS5032_2-Phenyl-1-propanol  291.0  DKYWVDODHFEZIM-UHFFFAOYSA-N   \n",
       "150067       LO15_Methyl indole-3-acetate  291.0  RTIXKCRFFJGDFG-UHFFFAOYSA-N   \n",
       "150068             LO03_Cinnamic aldehyde  291.6  FNYLWPVRPXGIIP-UHFFFAOYSA-N   \n",
       "150069             LO03_Cinnamic aldehyde  291.6  FNYLWPVRPXGIIP-UHFFFAOYSA-N   \n",
       "\n",
       "         ion_mod  rt_range  \n",
       "0       positive         5  \n",
       "1       positive         5  \n",
       "2       positive         5  \n",
       "3       positive         5  \n",
       "4       positive         5  \n",
       "...          ...       ...  \n",
       "150065  negative         5  \n",
       "150066  negative         5  \n",
       "150067  negative         5  \n",
       "150068  positive         5  \n",
       "150069  negative         5  \n",
       "\n",
       "[150070 rows x 8 columns]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rt_tol = 5\n",
    "res = rtm.comp_match_rt(df, ref, rt_tol)\n",
    "res"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fb0512a",
   "metadata": {},
   "source": [
    "## Summarize Results\n",
    "\n",
    "The function `comp_summ` in package `LAMP`  summarises the retention time\n",
    "matching."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e4d97561",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:44.330903Z",
     "iopub.status.busy": "2025-12-04T12:29:44.330903Z",
     "iopub.status.idle": "2025-12-04T12:29:44.879843Z",
     "shell.execute_reply": "2025-12-04T12:29:44.879843Z"
    }
   },
   "outputs": [],
   "source": [
    "sr, mr = anno.comp_summ(df, res)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "499abec3",
   "metadata": {},
   "source": [
    "This function combines peak table with retention time matching results and\n",
    "returns two results in different formats. `sr` is single row results for\n",
    "each peak id in peak table `df`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "99c35f0a",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:44.881389Z",
     "iopub.status.busy": "2025-12-04T12:29:44.881389Z",
     "iopub.status.idle": "2025-12-04T12:29:44.895776Z",
     "shell.execute_reply": "2025-12-04T12:29:44.895776Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>mz</th>\n",
       "      <th>rt</th>\n",
       "      <th>rt_range</th>\n",
       "      <th>identifier</th>\n",
       "      <th>metabolite_name</th>\n",
       "      <th>rt_lib</th>\n",
       "      <th>inchikey</th>\n",
       "      <th>ion_mod</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0389::ACMG_aqC18_POS_0389::ACMG...</td>\n",
       "      <td>LO488_Maleic acid::LO488_Maleic acid::LO321_L-...</td>\n",
       "      <td>48.9::48.9::49.2::49.2::50.4::50.4::50.4::50.4...</td>\n",
       "      <td>JJVNINGBHGBWJH-UHFFFAOYSA-N::JJVNINGBHGBWJH-UH...</td>\n",
       "      <td>positive::negative::positive::negative::positi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>M1015T254</td>\n",
       "      <td>1014.985384</td>\n",
       "      <td>253.626177</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0782::ACMG_aqC18_POS_0783::ACMG...</td>\n",
       "      <td>LO481_3-Hydroxydecanedioic acid::LIM3308_Suber...</td>\n",
       "      <td>249.00000000000003::249.00000000000003::249.00...</td>\n",
       "      <td>FVWJYYTZTCVBKE-ROUWMTJPSA-N::TVZGACDUOSZQKY-UH...</td>\n",
       "      <td>positive::positive::negative::negative::positi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>M101T228</td>\n",
       "      <td>101.060060</td>\n",
       "      <td>228.125403</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0654::ACMG_aqC18_POS_0654::ACMG...</td>\n",
       "      <td>MS5018_Dimethyl maleate::MS5018_Dimethyl malea...</td>\n",
       "      <td>223.2::223.2::223.8::223.8::223.8::223.8::223....</td>\n",
       "      <td>KIWQWJKWBHZMDT-UHFFFAOYSA-N::KIWQWJKWBHZMDT-UH...</td>\n",
       "      <td>positive::negative::positive::positive::positi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>M102T849</td>\n",
       "      <td>102.034154</td>\n",
       "      <td>849.085350</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>M102T899</td>\n",
       "      <td>102.034153</td>\n",
       "      <td>898.850160</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1995</th>\n",
       "      <td>M865T700</td>\n",
       "      <td>865.244172</td>\n",
       "      <td>700.365420</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1996</th>\n",
       "      <td>M919T647</td>\n",
       "      <td>918.701782</td>\n",
       "      <td>646.988220</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_1407::ACMG_aqC18_POS_1407::ACMG...</td>\n",
       "      <td>LO05_Vitamin K1::LO05_Vitamin K1::LIM3314_Phyl...</td>\n",
       "      <td>642.6::642.6::643.2::643.2::647.1::647.1</td>\n",
       "      <td>ZFDIRQKJPRINOQ-HYXAFXHYSA-N::ZFDIRQKJPRINOQ-HY...</td>\n",
       "      <td>positive::negative::positive::negative::positi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1997</th>\n",
       "      <td>M925T237_1</td>\n",
       "      <td>924.898294</td>\n",
       "      <td>236.964462</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0690::ACMG_aqC18_POS_0691::ACMG...</td>\n",
       "      <td>LO306_Syringic acid::LO315_ortho-Hydroxyphenyl...</td>\n",
       "      <td>232.2::232.2::232.2::232.2::232.2::232.2::232....</td>\n",
       "      <td>AFBPFSWMIHJQDM-UHFFFAOYSA-N::OISVCGZHLKNMSJ-UH...</td>\n",
       "      <td>positive::positive::positive::positive::positi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1998</th>\n",
       "      <td>M933T267</td>\n",
       "      <td>933.410460</td>\n",
       "      <td>266.976471</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0839::ACMG_aqC18_POS_0840::ACMG...</td>\n",
       "      <td>MS5012_Diethyl malonate::MS5019_Trimethylaceti...</td>\n",
       "      <td>262.2::262.2::262.2::262.2::262.2::262.2::262....</td>\n",
       "      <td>KEVYVLWNCKMXJX-UHFFFAOYSA-N::WTTJVINHCBCLGX-ZD...</td>\n",
       "      <td>positive::positive::positive::negative::negati...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1999</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>5.0</td>\n",
       "      <td>ACMG_aqC18_POS_0720::ACMG_aqC18_POS_0721::ACMG...</td>\n",
       "      <td>LIM3312_Aspartame::MS5023_Ethyl levulinate::MS...</td>\n",
       "      <td>237.6::237.6::237.6::237.6::237.6::237.6::237....</td>\n",
       "      <td>MBDOYVRWFFCFHM-SNAWJCMRSA-N::XPFVYQJUAUNWIW-UH...</td>\n",
       "      <td>positive::positive::positive::positive::negati...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>2000 rows × 9 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "            name           mz          rt  rt_range  \\\n",
       "0        M100T54   100.075925   53.810924       5.0   \n",
       "1      M1015T254  1014.985384  253.626177       5.0   \n",
       "2       M101T228   101.060060  228.125403       5.0   \n",
       "3       M102T849   102.034154  849.085350       NaN   \n",
       "4       M102T899   102.034153  898.850160       NaN   \n",
       "...          ...          ...         ...       ...   \n",
       "1995    M865T700   865.244172  700.365420       NaN   \n",
       "1996    M919T647   918.701782  646.988220       5.0   \n",
       "1997  M925T237_1   924.898294  236.964462       5.0   \n",
       "1998    M933T267   933.410460  266.976471       5.0   \n",
       "1999    M934T242   933.932365  242.395371       5.0   \n",
       "\n",
       "                                             identifier  \\\n",
       "0     ACMG_aqC18_POS_0389::ACMG_aqC18_POS_0389::ACMG...   \n",
       "1     ACMG_aqC18_POS_0782::ACMG_aqC18_POS_0783::ACMG...   \n",
       "2     ACMG_aqC18_POS_0654::ACMG_aqC18_POS_0654::ACMG...   \n",
       "3                                                   NaN   \n",
       "4                                                   NaN   \n",
       "...                                                 ...   \n",
       "1995                                                NaN   \n",
       "1996  ACMG_aqC18_POS_1407::ACMG_aqC18_POS_1407::ACMG...   \n",
       "1997  ACMG_aqC18_POS_0690::ACMG_aqC18_POS_0691::ACMG...   \n",
       "1998  ACMG_aqC18_POS_0839::ACMG_aqC18_POS_0840::ACMG...   \n",
       "1999  ACMG_aqC18_POS_0720::ACMG_aqC18_POS_0721::ACMG...   \n",
       "\n",
       "                                        metabolite_name  \\\n",
       "0     LO488_Maleic acid::LO488_Maleic acid::LO321_L-...   \n",
       "1     LO481_3-Hydroxydecanedioic acid::LIM3308_Suber...   \n",
       "2     MS5018_Dimethyl maleate::MS5018_Dimethyl malea...   \n",
       "3                                                   NaN   \n",
       "4                                                   NaN   \n",
       "...                                                 ...   \n",
       "1995                                                NaN   \n",
       "1996  LO05_Vitamin K1::LO05_Vitamin K1::LIM3314_Phyl...   \n",
       "1997  LO306_Syringic acid::LO315_ortho-Hydroxyphenyl...   \n",
       "1998  MS5012_Diethyl malonate::MS5019_Trimethylaceti...   \n",
       "1999  LIM3312_Aspartame::MS5023_Ethyl levulinate::MS...   \n",
       "\n",
       "                                                 rt_lib  \\\n",
       "0     48.9::48.9::49.2::49.2::50.4::50.4::50.4::50.4...   \n",
       "1     249.00000000000003::249.00000000000003::249.00...   \n",
       "2     223.2::223.2::223.8::223.8::223.8::223.8::223....   \n",
       "3                                                   NaN   \n",
       "4                                                   NaN   \n",
       "...                                                 ...   \n",
       "1995                                                NaN   \n",
       "1996           642.6::642.6::643.2::643.2::647.1::647.1   \n",
       "1997  232.2::232.2::232.2::232.2::232.2::232.2::232....   \n",
       "1998  262.2::262.2::262.2::262.2::262.2::262.2::262....   \n",
       "1999  237.6::237.6::237.6::237.6::237.6::237.6::237....   \n",
       "\n",
       "                                               inchikey  \\\n",
       "0     JJVNINGBHGBWJH-UHFFFAOYSA-N::JJVNINGBHGBWJH-UH...   \n",
       "1     FVWJYYTZTCVBKE-ROUWMTJPSA-N::TVZGACDUOSZQKY-UH...   \n",
       "2     KIWQWJKWBHZMDT-UHFFFAOYSA-N::KIWQWJKWBHZMDT-UH...   \n",
       "3                                                   NaN   \n",
       "4                                                   NaN   \n",
       "...                                                 ...   \n",
       "1995                                                NaN   \n",
       "1996  ZFDIRQKJPRINOQ-HYXAFXHYSA-N::ZFDIRQKJPRINOQ-HY...   \n",
       "1997  AFBPFSWMIHJQDM-UHFFFAOYSA-N::OISVCGZHLKNMSJ-UH...   \n",
       "1998  KEVYVLWNCKMXJX-UHFFFAOYSA-N::WTTJVINHCBCLGX-ZD...   \n",
       "1999  MBDOYVRWFFCFHM-SNAWJCMRSA-N::XPFVYQJUAUNWIW-UH...   \n",
       "\n",
       "                                                ion_mod  \n",
       "0     positive::negative::positive::negative::positi...  \n",
       "1     positive::positive::negative::negative::positi...  \n",
       "2     positive::negative::positive::positive::positi...  \n",
       "3                                                   NaN  \n",
       "4                                                   NaN  \n",
       "...                                                 ...  \n",
       "1995                                                NaN  \n",
       "1996  positive::negative::positive::negative::positi...  \n",
       "1997  positive::positive::positive::positive::positi...  \n",
       "1998  positive::positive::positive::negative::negati...  \n",
       "1999  positive::positive::positive::positive::negati...  \n",
       "\n",
       "[2000 rows x 9 columns]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sr"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05503557",
   "metadata": {},
   "source": [
    "`mr` is multiple rows format if the match more than once from the reference\n",
    "file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "95c9b44f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:44.895776Z",
     "iopub.status.busy": "2025-12-04T12:29:44.895776Z",
     "iopub.status.idle": "2025-12-04T12:29:44.919033Z",
     "shell.execute_reply": "2025-12-04T12:29:44.918004Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>mz</th>\n",
       "      <th>rt</th>\n",
       "      <th>identifier</th>\n",
       "      <th>metabolite_name</th>\n",
       "      <th>rt_lib</th>\n",
       "      <th>inchikey</th>\n",
       "      <th>ion_mod</th>\n",
       "      <th>rt_range</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>ACMG_aqC18_POS_0389</td>\n",
       "      <td>LO488_Maleic acid</td>\n",
       "      <td>48.9</td>\n",
       "      <td>JJVNINGBHGBWJH-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>ACMG_aqC18_POS_0389</td>\n",
       "      <td>LO488_Maleic acid</td>\n",
       "      <td>48.9</td>\n",
       "      <td>JJVNINGBHGBWJH-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>ACMG_aqC18_POS_0390</td>\n",
       "      <td>LO321_L-Theanine</td>\n",
       "      <td>49.2</td>\n",
       "      <td>SULYEHHGGXARJS-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>ACMG_aqC18_POS_0390</td>\n",
       "      <td>LO321_L-Theanine</td>\n",
       "      <td>49.2</td>\n",
       "      <td>SULYEHHGGXARJS-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>M100T54</td>\n",
       "      <td>100.075925</td>\n",
       "      <td>53.810924</td>\n",
       "      <td>ACMG_aqC18_POS_0391</td>\n",
       "      <td>LO310_Dihydrothymine</td>\n",
       "      <td>50.4</td>\n",
       "      <td>YPTJKHVBDCRKNF-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150218</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>ACMG_aqC18_POS_0775</td>\n",
       "      <td>LO35_2-Methoxybenzoic acid</td>\n",
       "      <td>247.2</td>\n",
       "      <td>RFKITWRHKUYMRJ-UHFFFAOYSA-N</td>\n",
       "      <td>positive</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150219</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>ACMG_aqC18_POS_0772</td>\n",
       "      <td>MS5015_Phenylglyoxal</td>\n",
       "      <td>247.2</td>\n",
       "      <td>QWIZNVHXZXRPDR-WSCXOGSTSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150220</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>ACMG_aqC18_POS_0773</td>\n",
       "      <td>MS5021_Ethyl 2-methylacetoacetate</td>\n",
       "      <td>247.2</td>\n",
       "      <td>BHTRKEVKTKCXOH-LBSADWJPSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150221</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>ACMG_aqC18_POS_0774</td>\n",
       "      <td>LO12_Homoveratrumic acid</td>\n",
       "      <td>247.2</td>\n",
       "      <td>SEBFKMXJBCUCAI-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>150222</th>\n",
       "      <td>M934T242</td>\n",
       "      <td>933.932365</td>\n",
       "      <td>242.395371</td>\n",
       "      <td>ACMG_aqC18_POS_0775</td>\n",
       "      <td>LO35_2-Methoxybenzoic acid</td>\n",
       "      <td>247.2</td>\n",
       "      <td>RFKITWRHKUYMRJ-UHFFFAOYSA-N</td>\n",
       "      <td>negative</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>150223 rows × 9 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "            name          mz          rt           identifier  \\\n",
       "0        M100T54  100.075925   53.810924  ACMG_aqC18_POS_0389   \n",
       "1        M100T54  100.075925   53.810924  ACMG_aqC18_POS_0389   \n",
       "2        M100T54  100.075925   53.810924  ACMG_aqC18_POS_0390   \n",
       "3        M100T54  100.075925   53.810924  ACMG_aqC18_POS_0390   \n",
       "4        M100T54  100.075925   53.810924  ACMG_aqC18_POS_0391   \n",
       "...          ...         ...         ...                  ...   \n",
       "150218  M934T242  933.932365  242.395371  ACMG_aqC18_POS_0775   \n",
       "150219  M934T242  933.932365  242.395371  ACMG_aqC18_POS_0772   \n",
       "150220  M934T242  933.932365  242.395371  ACMG_aqC18_POS_0773   \n",
       "150221  M934T242  933.932365  242.395371  ACMG_aqC18_POS_0774   \n",
       "150222  M934T242  933.932365  242.395371  ACMG_aqC18_POS_0775   \n",
       "\n",
       "                           metabolite_name rt_lib  \\\n",
       "0                        LO488_Maleic acid   48.9   \n",
       "1                        LO488_Maleic acid   48.9   \n",
       "2                         LO321_L-Theanine   49.2   \n",
       "3                         LO321_L-Theanine   49.2   \n",
       "4                     LO310_Dihydrothymine   50.4   \n",
       "...                                    ...    ...   \n",
       "150218          LO35_2-Methoxybenzoic acid  247.2   \n",
       "150219                MS5015_Phenylglyoxal  247.2   \n",
       "150220  MS5021_Ethyl 2-methylacetoacetate   247.2   \n",
       "150221            LO12_Homoveratrumic acid  247.2   \n",
       "150222          LO35_2-Methoxybenzoic acid  247.2   \n",
       "\n",
       "                           inchikey   ion_mod  rt_range  \n",
       "0       JJVNINGBHGBWJH-UHFFFAOYSA-N  positive       5.0  \n",
       "1       JJVNINGBHGBWJH-UHFFFAOYSA-N  negative       5.0  \n",
       "2       SULYEHHGGXARJS-UHFFFAOYSA-N  positive       5.0  \n",
       "3       SULYEHHGGXARJS-UHFFFAOYSA-N  negative       5.0  \n",
       "4       YPTJKHVBDCRKNF-UHFFFAOYSA-N  positive       5.0  \n",
       "...                             ...       ...       ...  \n",
       "150218  RFKITWRHKUYMRJ-UHFFFAOYSA-N  positive       5.0  \n",
       "150219  QWIZNVHXZXRPDR-WSCXOGSTSA-N  negative       5.0  \n",
       "150220  BHTRKEVKTKCXOH-LBSADWJPSA-N  negative       5.0  \n",
       "150221  SEBFKMXJBCUCAI-UHFFFAOYSA-N  negative       5.0  \n",
       "150222  RFKITWRHKUYMRJ-UHFFFAOYSA-N  negative       5.0  \n",
       "\n",
       "[150223 rows x 9 columns]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mr"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8837c041",
   "metadata": {},
   "source": [
    "All of results can be saved into a `sqlite3` database and use\n",
    "[DB Browser for SQLite](https://sqlitebrowser.org/) to view. Or save these\n",
    "results in other formats, such as TSV, CSV or XLSX, separately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "bdc0a967",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:44.921039Z",
     "iopub.status.busy": "2025-12-04T12:29:44.921039Z",
     "iopub.status.idle": "2025-12-04T12:29:44.925914Z",
     "shell.execute_reply": "2025-12-04T12:29:44.925914Z"
    }
   },
   "outputs": [],
   "source": [
    "f_save = False          # here we do NOT save results\n",
    "db_out = \"test.db\"\n",
    "sr_out = \"test_s.tsv\"\n",
    "mr_out = \"test_m.tsv\"\n",
    "xlsx_out = \"test.xlsx\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "919b88f6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-12-04T12:29:44.925914Z",
     "iopub.status.busy": "2025-12-04T12:29:44.925914Z",
     "iopub.status.idle": "2025-12-04T12:29:44.934684Z",
     "shell.execute_reply": "2025-12-04T12:29:44.934684Z"
    }
   },
   "outputs": [],
   "source": [
    "if f_save:\n",
    "    # save all results into a sqlite3 database\n",
    "    conn = sqlite3.connect(db_out)\n",
    "    df[[\"name\", \"mz\", \"rt\"]].to_sql(\"peaklist\",\n",
    "                                    conn,\n",
    "                                    if_exists=\"replace\",\n",
    "                                    index=False)\n",
    "    mr.to_sql(\"anno_mr\", conn, if_exists=\"replace\", index=False)\n",
    "    sr.to_sql(\"anno_sr\", conn, if_exists=\"replace\", index=False)\n",
    "\n",
    "    conn.commit()\n",
    "    conn.close()\n",
    "\n",
    "    # save results into text files\n",
    "    sr.to_csv(sr_out, sep=\"\\t\", index=False)\n",
    "    mr.to_csv(mr_out, sep=\"\\t\", index=False)\n",
    "\n",
    "    # save results into Excel format\n",
    "    with pd.ExcelWriter(xlsx_out, mode=\"w\", engine=\"openpyxl\") as writer:\n",
    "        sr.to_excel(writer, sheet_name=\"single-row\", index=False)\n",
    "        mr.to_excel(writer, sheet_name=\"multiple-row\", index=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4256549",
   "metadata": {},
   "source": [
    "It should be noted that saving of Excel file takes much longer time than\n",
    "text files.\n",
    "\n",
    "## End User Usages\n",
    "\n",
    "`LiRTMaTS` provides two computation options: command line interface(CLI)\n",
    "and graphical user interface (GUI).\n",
    "\n",
    "To use GUI,  you need to open a terminal and type in:\n",
    "\n",
    "```bash\n",
    "$ lirtmats gui\n",
    "```\n",
    "\n",
    "To use CLI, open a terminal and type in command with required arguments,\n",
    "something like:\n",
    "\n",
    "```bash\n",
    "lirtmats cli \\\n",
    "  --input-data \"./data/df_pos_3.tsv\" \\\n",
    "  --input-sep \"tab\" \\\n",
    "  --col-idx \"1, 2, 3, 4\" \\\n",
    "  --rt-path \"\" \\\n",
    "  --rt-sep \"tab\" \\\n",
    "  --rt-tol \"5.0\" \\\n",
    "  --ion-mode \"pos\" \\\n",
    "  --save-db \\\n",
    "  --summ-type \"xlsx\" \\\n",
    "```\n",
    "\n",
    "Execution of this command line will produce `df_pos_3_rtm.db` and\n",
    "`df_pos_3_rtm.xlsx` in the directory `./data/`. If the `summ-type` is `tsv`\n",
    "or `csv`, files `df_pos_3_rtm_s.tsv` or `df_pos_3_rtm_s.csv` and\n",
    "`df_pos_3_rtm_m.tsv` or `df_pos_3_rtm_m.csv` will be saved into `./data`.\n",
    "\n",
    "For the best practice, you can create a bash script `.sh` (Linux\n",
    "and MacOS) or Windows script `.bat` to contain these CLI\n",
    "arguments. Change parameters in these files each time when processing new\n",
    "data set.\n",
    "\n",
    "For example, there are `lirtmats_cli.sh` and `lirtmats_cli.bat` in\n",
    "https://github.com/wanchanglin/lirtmats/tree/master/examples.\n",
    "\n",
    "- For Linux and MacOS terminal:\n",
    "\n",
    "  ```bash\n",
    "  $ chmod +x lirtmats_cli.sh\n",
    "  $ ./lirtmats_cli.sh\n",
    "  ```\n",
    "\n",
    "- For Windows terminal:\n",
    "\n",
    "  ```bash\n",
    "  $ lirtmats_cli.bat\n",
    "  ```\n",
    "\n",
    "Note that if users use `xlsx` files for input data and reference file when\n",
    "using GUI or CLI, all data must be in the first sheet. If you use\n",
    "`LiRTMaTS` functions in your python scripts, there are no such\n",
    "requirements."
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  },
  "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": 5
}