tutorial/01_quick_start_guide.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick start guide\n",
    "\n",
    "This notebook details the minimal steps needed to train a particle detection model and then use that model to extract predicted particle coordinates with Topaz. For a more detailed walkthrough with visualization of outputs from the different steps, please see: https://github.com/tbepler/topaz/blob/master/tutorial/02_walkthrough.ipynb\n",
    "\n",
    "Topaz now includes pretrained particle picking models that can be used to skip the training step for many datasets. Even when training, initializing from these models can substantially reduce the amount of training steps required. By default, topaz train will now initialize from these models.\n",
    "\n",
    "__Topaz is assumed to be installed in a conda environment named \"topaz\" for purposes of running topaz commands within bash cells.__ If topaz was installed in some other way, then the \"source activate topaz\" lines will need to be removed or changed below. See https://github.com/tbepler/topaz#installation for details on installing Topaz.\n",
    "\n",
    "### Demo dataset\n",
    "\n",
    "This guide uses a demo dataset that can be downloaded [here](http://bergerlab-downloads.csail.mit.edu/topaz/topaz-tutorial-data.tar.gz) and should be unpacked directly in this (the tutorial) directory.\n",
    "\n",
    "```\n",
    "wget http://bergerlab-downloads.csail.mit.edu/topaz/topaz-tutorial-data.tar.gz\n",
    "tar -xzvf topaz-tutorial-data.tar.gz\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Topaz pipeline\n",
    "\n",
    "The Topaz particle picking pipeline proceeds as follows:\n",
    "\n",
    "(Before running Topaz, optional): label a small (100-1000, more is likely to give better results) number of particles on your micrographs using the software of your choice. This can be skipped when using the pretrained models bundled with Topaz. \n",
    "\n",
    "1. (Preprocessing) Micrographs are downsampled and normalized, any labeled particle coordinates also need to be scaled appropriately\n",
    "2. (Training, optional) The particle detection model is trained on the preprocessed micrographs using the labeled particle coordinates. This requires setting the expected number of particles per micrograph. This can be skipped when using the pretrained models bundled with Topaz.\n",
    "3. (Extraction) Using a trained model, particle coordinates and their associated scores are extracted from the micrographs. This requires knowing the particle radius in pixels on the downsampled micrographs.\n",
    "\n",
    "(Optional postprocessing): examine classifier performance, rescale particle coordinates, extract particle stack, change particle file format, filter particles by model score, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### In this guide\n",
    "\n",
    "We assume that the user already has a file containing their labeled particle coordinates (data/EMPIAR-10025/rawdata/particles.txt in this case), that the expected number of particles per micrograph is 300, and that the particle radius is ~74 Å (14 pixels after downsampling 8x)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Preprocessing\n",
    "\n",
    "Downsample the micrographs by a factor of 8 (to ~5.28 Å/pix) and also scale the labeled coordinates to match.\n",
    "\n",
    "__A note on downsampling:__ For this demo dataset, we downsample 8x, but this may not always be the best downsampling amount for your data. We recommend downsampling your data enough that the diameter of your particle fits within the receptive field of the CNN architecture you are using. In this tutorial, we use the default architecture of resnet8, which has a receptive field size of 71 pixels. If you are using a different architecture, this number is slightly different. See [here](https://github.com/tbepler/topaz#model-architectures) for architecture details.\n",
    "\n",
    "As a rule of thumb, downsampling to about 4-8 Å per pixel works well, but this may need to be adjusted for very large or very small particles to fit the classifier as described above.\n",
    "\n",
    "__Pretrained models:__ When using the pretrained models, they assume that microcraphs are downsampled to the 4-8 Å per pixel range. Generally speaking, ~4 Å/pix is better for small to medium sized particles, but ~8 Å/pix is better for large particles (>= 300 Å particle diameter). Very large particles may require additional downsampling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "# processed: 14sep05c_c_00003gr_00014sq_00004hl_00004es_c\n",
      "# processed: 14sep05c_c_00003gr_00014sq_00005hl_00003es_c\n",
      "# processed: 14sep05c_c_00003gr_00014sq_00007hl_00004es_c\n",
      "# processed: 14sep05c_c_00003gr_00014sq_00011hl_00003es_c\n",
      "# processed: 14sep05c_c_00003gr_00015sq_00015hl_00002es_c\n",
      "# processed: 14sep05c_c_00003gr_00018sq_00008hl_00003es_c\n",
      "# processed: 14sep05c_c_00003gr_00018sq_00010hl_00005es_c\n",
      "# processed: 14sep05c_c_00003gr_00020sq_00011hl_00002es_c\n",
      "# processed: 14sep05c_c_00003gr_00020sq_00011hl_00004es_c\n",
      "# processed: 14sep05c_c_00004gr_00031sq_00002hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00031sq_00005hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00031sq_00010hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00007hl_00003es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00010hl_00003es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00029hl_00005es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00031hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00033hl_00005es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00037hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00037hl_00003es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00040hl_00002es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00040hl_00004es_c\n",
      "# processed: 14sep05c_c_00004gr_00032sq_00041hl_00005es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00004hl_00003es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00005hl_00002es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00006hl_00002es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00008hl_00003es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00008hl_00004es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00009hl_00002es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00009hl_00004es_c\n",
      "# processed: 14sep05c_c_00007gr_00013sq_00014hl_00004es_c\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "source activate topaz\n",
    "\n",
    "# we'll store the processed data in data/EMPIAR-10025/processed\n",
    "# so we need to make these directories first\n",
    "mkdir -p data/EMPIAR-10025/processed\n",
    "mkdir -p data/EMPIAR-10025/processed/micrographs\n",
    "\n",
    "# to run the preprocess command, we pass the input micrographs as command line arguments\n",
    "# preprocess will write the processed images to the directory specified with the -o argument\n",
    "# -s sets the downsampling amount (in this case, we downsample by a factor of 8)\n",
    "# -d/--device X sets preprocess to use GPU with ID X\n",
    "# -t/--num-workers X sets preprocess to use X processes (preprocesses X micrographs in parallel), this and GPU device are mutually exclusive\n",
    "# -v gives verbose output to track progress\n",
    "topaz preprocess -v -s 8 -o data/EMPIAR-10025/processed/micrographs/ data/EMPIAR-10025/rawdata/micrographs/*.mrc\n",
    "\n",
    "# this command takes the particle coordinates matched to the original micrographs\n",
    "# and scales them by 1/8 (-s is downscaling)\n",
    "# the -x option applies upscaling instead\n",
    "topaz convert -s 8 -o data/EMPIAR-10025/processed/particles.txt data/EMPIAR-10025/rawdata/particles.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. Model training\n",
    "\n",
    "Given the preprocessed micrographs and particle coordinates, we train the particle detection model using positive-unlabeled learning. This requires us to specify the expected number of particles per micrograph, which we set to 400 in this case."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "# Loading model: resnet8\n",
      "# Model parameters: units=32, dropout=0.0, bn=on\n",
      "# Loading pretrained model: resnet8_u32\n",
      "# Receptive field: 71\n",
      "# Using device=0 with cuda=True\n",
      "# Loaded 30 training micrographs with 1500 labeled particles\n",
      "# source\tsplit\tp_observed\tnum_positive_regions\ttotal_regions\n",
      "# 0\ttrain\t0.00163\t43500\t26669790\n",
      "# Specified expected number of particle per micrograph = 400.0\n",
      "# With radius = 3\n",
      "# Setting pi = 0.0130484716977524\n",
      "# minibatch_size=256, epoch_size=1000, num_epochs=10\n",
      "# Done!\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "source activate topaz\n",
    "\n",
    "# first, make sure we have the folders where we want to put the saved models\n",
    "# store the saved models in saved_models/EMPIAR-10025\n",
    "mkdir -p saved_models\n",
    "mkdir -p saved_models/EMPIAR-10025\n",
    "\n",
    "# Now, we train the model\n",
    "\n",
    "# We set -n 400 to tell Topaz that we expect there to be on average 400 particles per micrograph\n",
    "# and --num-workers=8 to speed up training\n",
    "\n",
    "# By default, topaz train will use your first GPU if available, to force topaz train to use the CPU, set: -d -1\n",
    "# To use a different GPU, set -d X where X is the GPU ID\n",
    "\n",
    "# the models will be saved to the saved_models/EMPIAR-10025 directory\n",
    "topaz train -n 400 \\\n",
    "            --num-workers=8 \\\n",
    "            --train-images data/EMPIAR-10025/processed/micrographs/ \\\n",
    "            --train-targets data/EMPIAR-10025/processed/particles.txt \\\n",
    "            --save-prefix=saved_models/EMPIAR-10025/model \\\n",
    "            -o saved_models/EMPIAR-10025/model_training.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Extract particle coordinates\n",
    "\n",
    "Now that we have a trained model, we use it to extract predicted particle coordinates using a particle radius of 14 pixels.\n",
    "\n",
    "Extract can be run using a particle picking model trained above by passing the model path as an argument. It can also use the pretrained models by specifying on of:\n",
    "\n",
    "- resnet8_u32\n",
    "- resnet8_u64\n",
    "- resnet16_u32\n",
    "- resnet16_u64 (the default)\n",
    "\n",
    "as the model argument. If no argument is passed, extract uses the resnet16_u64 pretrained model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "source activate topaz\n",
    "\n",
    "## make a directory to write the topaz particles to\n",
    "mkdir -p data/EMPIAR-10025/topaz\n",
    "\n",
    "## extract particle coordinates using the  trained model\n",
    "## we set the radius parameter to 14 (-r 14)\n",
    "## to prevent extracting particle coordinates closer than the radius of the particle\n",
    "## i.e. we don't want multiple predictions for a single particle\n",
    "## we also set -x 8 in order to scale the coordinates back to the original micrograph size\n",
    "\n",
    "topaz extract -r 14 -x 8 -m saved_models/EMPIAR-10025/model_epoch10.sav \\\n",
    "              -o data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.txt \\\n",
    "              data/EMPIAR-10025/processed/micrographs/*.mrc\n",
    "              \n",
    "              \n",
    "## To use the pretrained particle picking model instead, we can omit the model argument.\n",
    "\n",
    "#topaz extract -r 14 -x 8 \\\n",
    "#              -o data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.txt \\\n",
    "#              data/EMPIAR-10025/processed/micrographs/*.mrc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "# (Optional) change format of particle coordinates file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "source activate topaz\n",
    "\n",
    "# we can convert the particles file to .star format (and others) by changing the file extension\n",
    "# of the output file (data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.txt)\n",
    "# to .star (data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.star)\n",
    "# the convert command can also filter the particle table by model score using the -t argument\n",
    "# e.g. -t 0 would only keep particles with scores >= 0\n",
    "\n",
    "topaz convert -o data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.star \\\n",
    "              data/EMPIAR-10025/topaz/predicted_particles_all_upsampled.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# That's it!\n",
    "\n",
    "We now have a table containing particle coordinates for each micrograph with their corresponding model score."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next steps\n",
    "\n",
    "- To better understand the outputs of the individual steps and to visualize intermediate results, take a look at the detailed walkthrough [here](https://github.com/tbepler/topaz/blob/master/tutorial/02_walkthrough.ipynb)\n",
    "\n",
    "- To jump straight to understanding model selection and evaluation criteria, take a look at the cross validation tutorial [here](https://github.com/tbepler/topaz/blob/master/tutorial/03_cross_validation.ipynb) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python [conda env:topaz]",
   "language": "python",
   "name": "conda-env-topaz-py"
  },
  "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}