Getting Started

Installation extension

• A comfortable way to setup a python environment with common scientific python packages, as needed by ELEKTRONN, is the Anaconda distribution by Continuum (make sure to use the Python 2.7 version). If you don't want to install the whole Anaconda distribution you can use Miniconda instead. Install ELEKTRONN using conda:

  conda config --add channels conda-forge
  conda install elektronn

• This resolves all dependencies and installs ELEKTRONN, but you still need to configure Theano (which will be installed as a dependency).

• [Optionally: create a user configuration file by editing the file examples/config_template.py and put it into your home directory as elektronn.config (see configuration).]
• [Optionally: try out one of the examples to confirm everything works.]
• Users of Arch Linux can install the AUR package elektronn instead.
• For installation without Anaconda (pip or manually) please refer to the instructions in the documentation.

• codeGitHub Repository

Get Started with ELEKTRONN trending_up

Your First Training with MNIST school

MNIST is a famous benchmark data set for the task of handwritten digit recognition. To try out the example training:

elektronn-train MNIST_CNN_warp_config.py [--gpu=0]

The first argument to the script is the path to a config file which is within the package’s examples directory. You can alternatively copy the file, edit it and use your modified version. If you have an NVIDIA GPU add the option --gpu=0 which will make the execution significantly faster (make sure you have configured theano when installing ELEKTRONN). Plots of the training progress are saved to ~/CNN_Training/2D/MNIST_example_warp (the destination can be changed in the config file).

This is an example of "img-scalar" training: the input data is image like but the output is a scalar (namely the class prediction) describing the whole image. The main focus of ELEKTRONN lies however on "img-img" traing which is described in the next section.

Basic Recipe for CNN Training with Images format_list_numbered

• CNN training requires a training data set of spatial input data (2d/3d, optional with a fourth axis for (colour) channels) and labels (also called: ground truth, annotations, targets) that correspond to the individual pixels in the images. The labels can be classes - then each pixel contains an integer number encoding the class membership - or alternatively floats for regression targets.

• Convert your data arrays to h5 data sets in separate files for images and labels:

  • images: shape (x,y,z) or (ch,x,y,z)
  • labels: shape (x,y,z)
  • do not cut image patches manually. If the shape of the training data is greater than the CNN input patch size, the pipeline automatically cuts patches from random locations in the images.
  • for classification: labels contain integer numbers, ranging from 0 to (#classes-1)
  • for regression: labels contain float numbers
  • for 2d images the z-dimension can be viewed as the axis along which the instances of the training set are stacked
  • details on data format
• Find a valid CNN architecture by using elektronn.net.netutils.CNNCalculator(). For img-img tasks it advisable to make select an input patch size such that in the final layer a few 100 - 1000 output neurons/pixel remain, this is a good trade-off between gradient noise and iteration speed.
• Edit examples/config_template.py as a new file to specify your training scenario.

• Run the script scripts/elektronn-train from command line:

  elektronn-train </path/to_config_file> [ --gpu={Auto|False|<int>}]

• Inspect the printed output and the plots to refine training settings or detect misconfigurations. Training neural networks is work and needs time. For a better understanding of how they should be trained and which architecture you should pick, refer to the resources in the documentation.