.template.foxs.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "FoXS: fitting structures against SAXS data {#foxs}\n",
    "==========================================\n",
    "\n",
    "[TOC]\n",
    "\n",
    "# Introduction {#foxs_introduction}\n",
    "\n",
    "Nup133 is one of the proteins that make up the yeast [Nuclear Pore Complex (NPC)](https://salilab.org/npc/). The structure of this protein has been characterized by both X-ray crystallography and\n",
    "small angle X-ray (SAXS).\n",
    "\n",
    "IMP includes a command line tool `foxs` for handling SAXS profiles, which will be demonstrated in this example. There is also a [web interface](https://salilab.org/foxs/) available, which functions similarly.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%htmlonly\n",
    "This tutorial can be followed in several ways:\n",
    "\n",
    " - Download the files using the \"Clone or download\" link at the [tutorial's GitHub page](https://github.com/salilab/foxs_tutorial/) and use them in conjunction with this text.\n",
    " - [Download the files from GitHub](https://github.com/salilab/foxs_tutorial/) and, using [Jupyter Notebook](https://jupyter.org/), open the notebook `foxs.ipynb`.\n",
    " - [Load the tutorial directly in your browser](https://colab.research.google.com/github/salilab/foxs_tutorial/blob/main/foxs-colab.ipynb), courtesy of [Google Colaboratory](https://colab.research.google.com/). (This needs no software installed on your machine, but may take a while to load.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%colabonly\n",
    "First, we need to install IMP and gnuplot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#%%colabonly\n",
    "!add-apt-repository -y ppa:salilab/ppa\n",
    "!apt install imp gnuplot\n",
    "import sys, os, glob\n",
    "sys.path.append(os.path.dirname(glob.glob('/usr/lib/python*/dist-packages/IMP')[0]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%colabonly\n",
    "Next, download the files for this tutorial from GitHub:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#%%colabonly\n",
    "!git clone https://github.com/salilab/foxs_tutorial.git\n",
    "%cd foxs_tutorial/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%htmlonly\n",
    "For full help on the `foxs` tool, run from a command line:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%htmlexclude\n",
    "For full help on the `foxs` tool, run from a command line (the ! prefix here requests the Linux shell command line, rather than Python):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!foxs -h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Calculation {#foxs_calculation}\n",
    "\n",
    "The structure of the C-terminal domain of yeast Nup133 is available in the [RCSB Protein Data Bank (PDB)](http://www.pdb.org) as code [3kfo](http://www.pdb.org/pdb/explore/explore.do?structureId=3KFO)\n",
    "(file `3KFO.pdb`), while the experimental SAXS profile is given in the `23922_merge.dat` file, both in the `foxs/nup133` subdirectory. The atomic structure can be fit against the SAXS profile by running FoXS:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd foxs/nup133/\n",
    "!foxs 3KFO.pdb 23922_merge.dat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "FoXS calculates the theoretical profile of the 3KFO structure and fits it against the experimental profile, and determines the quality of the fit, 𝝌 or Chi, with smaller values corresponding to closer fits. It also generates two `.dat` files, one containing the theoretical profile and the other this profile fit against the experimental profile. These files can be input to a plotting package (two [gnuplot](http://www.gnuplot.info/) input files with a `.plt` extension are provided).\n",
    "\n",
    "The fit in this example is not a good one (𝝌=2.96 or 𝝌<sup>2</sup>=8.76). To understand why this\n",
    "is so, the header of the 3KFO PDB file can be examined in a text editor. This reveals two problems. Several residues at the N and C termini were not resolved in the X-ray experiment (9 in total, 2 at the N terminus and 7 at the C terminus), and the sidechains of 16 other residues could also not be located\n",
    "(REMARK 465 and REMARK 470 lines). This problem can be resolved by adding in the missing atoms and residues by using [MODELLER](https://salilab.org/modeller/), which generated the\n",
    "<tt>3KFO-fill.B99990005.pdb</tt> file.\n",
    "\n",
    "> See `add-missing-residues.py` for the MODELLER script used. It simply\n",
    "> builds a model of the full sequence of 3KFO using the partial sequence\n",
    "> as a template (see the alignment file `alignment.ali`). Multiple models\n",
    "> are generated; each is fit against the SAXS data using FoXS and the\n",
    "> best-fitting model (`3KFO-fill.B99990005.pdb`) selected.\n",
    "\n",
    "The fits of the original PDB and the new structure can now be generated by running:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!foxs -g 3KFO.pdb 3KFO-fill.B99990005.pdb 23922_merge.dat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output shows that the new structure has a significantly better fit (𝝌=1.15 or 𝝌<sup>2</sup>=1.31). FoXS generates a gnuplot input file `fit.plt` which will plot the fits of all of the PDBs given against the profile. This can be run with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gnuplot fit.plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This generates an image, `fit.png`, showing the theoretical profiles\n",
    "(lines in top panel), the experimental profile (points in top panel) and the\n",
    "ratios of the experimental to theoretical profiles (bottom panel):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%htmlonly\n",
    "<img src=\"images/nup133_fit.png\" width=\"450px\" title=\"FoXS plot of Nup133 and its SAXS profile\" />"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#%%htmlexclude\n",
    "from IPython.display import Image\n",
    "Image(filename='fit.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%colabexclude\n",
    "For fitting multiple states against a SAXS profile, see the [next section on MultiFoXS](@file multifoxs)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%%colabonly\n",
    "For fitting multiple states against a SAXS profile, see the [next section on MultiFoXS](@file multifoxs-colab)."
   ]
  }
 ],
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}