Getting Started

System Requirements & Installation

  • Python 2.7
  • The whole toolkit was designed and tested on Linux systems (in particular Debian, Ubuntu, CentOS, Arch)
  • Theano creates CUDA binaries. Hence only Nvidia-GPUs will work (as a fallback it can use any CPU, but this might be too slow for large nets and CNNs).
  • Windows and Python3 support is planned for a major update.

For installation instructions see installation.


ELEKTRONN is structured into two subpackages which contain most importantly:

Basic Recipe for CNN Training with Images


This section is addressed to people interested into large scale image processing tasks (such as found in connectomics). For smaller toy examples and processing of non-image data have a look at the examples.

  • 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. Illustrations of training labels can be found here

  • Transform 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 dimension z can be viewed as the axis along which the instances of the training set are stacked
    • for whole image classification the labels must be 1d
  • Find a valid CNN architecture by using 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 as a new file to specify your training scenario.

  • Run the script elektronn-train:

    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 hard work and needs time. For a better understanding of how they should be trained refer to the sources in the next section.

Details of the configuration are explained here.