docs/notebooks/tut04_quant.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. External Quantification Tools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import suspect\n",
    "import numpy as np\n",
    "from matplotlib import pyplot as plt\n",
    "%matplotlib nbagg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "data = suspect.io.load_rda(\"/home/jovyan/suspect/tests/test_data/siemens/SVS_30.rda\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## LCModel\n",
    "\n",
    "LCModel requires several different files in order to process a spectrum. The actual MRS data is stored in the time domain in a .RAW file, with an optional .H20 file containing the water reference data (these are actually the same format but the extension helps in distinguishing the files). A .CONTROL file is what the LCModel program actually receives as input, it lists the input and output files, and any parameters which have non-default values. Finally the metabolite basis set used for fitting the data is contained in a .BASIS file. The .BASIS file is normally provided with LCModel and unlike the other files does not need to be changed with each new dataset.\n",
    "\n",
    "Suspect can generate all the files necessary to process data with LCModel using the `write_all_files()` function from the `suspect.io.lcmodel` module. This function takes a path to which to save the .RAW file (any other files will be saved in the same directory), the `MRSData` object to be written, and an optional `params` dictionary to customise any of the values in the .CONTROL file. This dictionary can contain any of the parameter names from the LCModel manual. Let's take a look at an example of how to save our data for [LCModel](http://s-provencher.com/pages/lcm-manual.shtml) to process."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# create a parameters dictionary to set the basis set to use\n",
    "params = {\n",
    "    \"FILBAS\": \"/path/to/lcmodel/basis.BASIS\"\n",
    "}\n",
    "suspect.io.lcmodel.write_all_files(\"lcmodel_data/example.RAW\", data, params=params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use some IPython magic to show the files that were created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "example.RAW  example_sl0.CONTROL\r\n"
     ]
    }
   ],
   "source": [
    "!ls lcmodel_data/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and to look at the contents of the .CONTROL file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " $LCMODL\r\n",
      " OWNER = ''\r\n",
      " KEY = 123456789\r\n",
      " DELTAT = 0.000833\r\n",
      " HZPPPM = 123.234655\r\n",
      " NUNFIL = 1024\r\n",
      " NDROWS = 1\r\n",
      " NDCOLS = 1\r\n",
      " FILBAS = '/path/to/lcmodel/basis.BASIS'\r\n",
      " NDSLIC = 1\r\n",
      " FILPS = 'lcmodel_data/example.PS'\r\n",
      " ICOLST = 1\r\n",
      " FILRAW = 'lcmodel_data/example.RAW'\r\n",
      " IROWEN = 1\r\n",
      " ICOLEN = 1\r\n",
      " DOWS = F\r\n",
      " IROWST = 1\r\n",
      " DOECC = F\r\n",
      " $END\r\n"
     ]
    }
   ],
   "source": [
    "!cat lcmodel_data/example_sl0.CONTROL"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The .CONTROL file contains all the parameters necessary for LCModel to process the file, including the path we specified to the correct basis set. Once the .RAW and .CONTROL files are generated, it only remains to run the LCModel program on the command line, passing in the .CONTROL file like this:\n",
    "\n",
    "    lcmodel < lcmodel_data/example_sl0.CONTROL\n",
    "\n",
    "If you are running your Suspect code on the same computer as your LCModel installation, so that lcmodel is in your path, it is trivial to run it from within a Jupyter notebook using IPython magic, or from a script using the `subprocess` module. However if you are running Suspect on a different computer, for example using the OpenMRSLab Docker container, then you will have to transfer the LCModel files to the LCModel computer for processing. This can be inconvenient because the paths in the generated .CONTROL file can become out of date. In our lab we have solved this problem by using a shared network drive which is mounted by both machines, then the paths remain consistent and the `lcmodel` program can be launched remotely from the Docker container with a simple ssh command. Another alternative is to use the `suspect.io.lcmodel.save_raw()` function instead to save only the .RAW file which can then be loaded by LCMGUI and the other parameters configured there. \n",
    "\n",
    "By default the control file is set to only generate the standard 1 page .PS output. The other output files can be generated by setting the appropriate options in the params dictionary. For example, to generate the .CSV file, set the \"LCSV\" parameter to True. In this case, Suspect will automatically generate the path for the .CSV in the same folder as the .RAW and .CONTROL files. To set a custom location to save the .CSV, instead set the parameter \"FILCSV\" in params."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# create a parameters dictionary to set the basis set to use\n",
    "params = {\n",
    "    \"FILBAS\": \"/path/to/lcmodel/basis.BASIS\",\n",
    "    \"LCSV\": True\n",
    "}\n",
    "suspect.io.lcmodel.write_all_files(\"lcmodel_data/example.RAW\", data, params=params)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " $LCMODL\r\n",
      " OWNER = ''\r\n",
      " KEY = 123456789\r\n",
      " DELTAT = 0.000833\r\n",
      " HZPPPM = 123.234655\r\n",
      " NUNFIL = 1024\r\n",
      " NDROWS = 1\r\n",
      " NDCOLS = 1\r\n",
      " FILBAS = '/path/to/lcmodel/basis.BASIS'\r\n",
      " NDSLIC = 1\r\n",
      " FILPS = 'lcmodel_data/example.PS'\r\n",
      " ICOLST = 1\r\n",
      " FILRAW = 'lcmodel_data/example.RAW'\r\n",
      " IROWEN = 1\r\n",
      " ICOLEN = 1\r\n",
      " LCSV = 11\r\n",
      " DOWS = F\r\n",
      " IROWST = 1\r\n",
      " FILCSV = 'lcmodel_data/example.CSV'\r\n",
      " DOECC = F\r\n",
      " $END\r\n"
     ]
    }
   ],
   "source": [
    "!cat lcmodel_data/example_sl0.CONTROL"
   ]
  }
 ],
 "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}