-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgetting-started.html
175 lines (124 loc) · 8.65 KB
/
getting-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
---
layout: page
permalink: /getting-started/
---
<section>
<header class="article-header">
<span class="box -explore"><i class="material-icons">explore</i></span>
<div>
<h1>Getting Started</h1>
<p>Learn how to use <strong>ELEKTRONN.</strong></p>
</div>
</header>
<div class="row getting-started-list">
<div class="col">
<h3>Installation</h3>
<p><strong>ELEKTRONN</strong> is a Python 2.7 package that can be installed with <a href="http://conda.pydata.org/docs/">conda</a> or <a href="https://pip.pypa.io/en/stable/">pip</a>. <!--<a href="#Installation">Installation instructions.</a>--> </p>
</div>
<div class="col">
<h3>Getting Started</h3>
<p>How do you use <strong>ELEKTRONN</strong> for your data analysis task? Read our <a href="#BasicRecipe">basic recipe</a> or try out one of the <a href="http://elektronn.github.io/documentation/Examples.html">examples</a>.</p>
<p>For an application on 3D image data, head to the <a href="http://elektronn.org/documentation/Examples.html#d-neuro-data">Documentation</a>.
</div>
<div class="col">
<h3>Documentation</h3>
<p><strong>ELEKTRONN’s</strong> full documentation, including many tips for training, can be found here:</p>
<p><a class="tag -icon" href="http://elektronn.github.io/documentation"><i class="material-icons">book</i> Documentation</a></p>
</div>
<div class="col">
<h3>Use Cases</h3>
<p><strong>ELEKTRONN</strong> can be used for...</p>
<ul>
<li>image segmentation</li>
<li>object recognition</li>
<li>prediction of income</li>
<li>... much more</li>
</ul>
</div>
</div>
<hr>
</section>
<section>
<h2 class="section-heading" id="Installation">Installation <span class="heading-icon"><i class="material-icons">extension</i></span></h2>
<ul>
<li>
<p>A comfortable way to setup a python environment with common scientific python packages, as needed by <strong>ELEKTRONN</strong>, is the <a href="https://store.continuum.io/cshop/anaconda/">Anaconda distribution</a> 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 <strong>ELEKTRONN</strong> using conda:</p>
<pre><code>conda config --add channels conda-forge</code><br><code>conda install elektronn</code></pre>
</li>
<li>
<p>This resolves all dependencies and installs <strong>ELEKTRONN</strong>, but you still need to <a href="http://elektronn.github.io/documentation/Installation.html#theano">configure Theano</a> (which will be installed as a dependency).</p>
</li>
<li>[Optionally: create a user configuration file by editing the file <a href="https://github.com/ELEKTRONN/ELEKTRONN/blob/master/elektronn/examples/config_template.py">examples/config_template.py</a> and put it into your home directory as <code>elektronn.config</code> (see <a href="http://elektronn.github.io/documentation/Pipeline.html#configuration-of-parameters">configuration</a>).]</li>
<li>[Optionally: try out one of the <a href="http://elektronn.github.io/documentation/Examples.html">examples</a> to confirm everything works.]</li>
<li>Users of <em>Arch Linux</em> can install the <a href="https://aur.archlinux.org/packages/elektronn/">AUR package elektronn</a> instead.</li>
<li>For installation without Anaconda (pip or manually) please refer to the <a href="http://elektronn.github.io/documentation/Installation.html">instructions</a> in the documentation.</li>
<li><p><a class="tag" href="https://github.com/ELEKTRONN/ELEKTRONN"><i class="material-icons">code</i>GitHub Repository</a></p></li>
</ul>
<hr>
</section>
<section>
<h2 class="section-heading">Get Started with <strong>ELEKTRONN</strong> <span class="heading-icon"><i class="material-icons">trending_up</i></span></h2>
<div class="row">
<div class="col">
<p>For people new to Neural Networks and CNNs we recommend reading the practical <a href="http://elektronn.github.io/documentation/IntroNN.html">introduction</a> in our documentation.</p>
<p>A more theoretical introduction, including formulae and references can be found <a href="/downloads/Intro-ANN.pdf">here</a>.</p>
</div>
<div class="col popover">
<h6>External Links</h6>
<ul>
<li><a href="http://deeplearning.net/software/theano/index.html">Theano homepage</a></li>
<li><a href="http://deeplearning.net/tutorial/contents.html">Overview Theano tutorials</a></li>
<li><a href="http://http://arxiv.org/abs/1206.5533">Practical recommendations for gradient-based training of deep architectures [2012 Y.Bengio]</a></li>
<li><a href="https://cs231n.github.io/convolutional-networks/">Tutorial from Stanford CS class</a></li>
<li><a href="https://youtu.be/bEUX_56Lojc">VIDEO Tutorial by Nando de Freitas</a></li>
</ul>
</div>
</div>
</section>
<hr>
<section>
<h2 class="section-heading">Your First Training with MNIST <span class="heading-icon"><i class="material-icons">school</i></span></h2>
<p>MNIST is a famous benchmark data set for the task of handwritten digit recognition. To try out the example training:</p>
<pre><code>elektronn-train MNIST_CNN_warp_config.py [--gpu=0]</code></pre>
<p>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 <code>--gpu=0</code> which will make the execution significantly faster (make sure you have <a href="http://elektronn.github.io/documentation/Installation.html#theano">configured theano</a> when installing <strong>ELEKTRONN</strong>). Plots of the training progress are saved to <code>~/CNN_Training/2D/MNIST_example_warp</code> (the destination can be changed in the config file).</p>
<p>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 <strong>ELEKTRONN</strong> lies however on "img-img" traing which is described in the next section.</p>
</section>
<hr>
<section>
<h2 class="section-heading" id="BasicRecipe">Basic Recipe for CNN Training with Images <span class="heading-icon"><i class="material-icons">format_list_numbered</i></span></h2>
<ul>
<li>
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.
</li>
<li>
<p>Convert your data arrays to h5 data sets in separate files for images and labels:</p>
<ul>
<li>images: shape (x,y,z) or (ch,x,y,z)</li>
<li>labels: shape (x,y,z)</li>
<li>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.</li>
<li>for classification: labels contain integer numbers, ranging from 0 to (#classes-1)</li>
<li>for regression: labels contain float numbers</li>
<li>for 2d images the z-dimension can be viewed as the axis along which the instances of the training set are stacked</li>
<li><a href="http://elektronn.github.io/documentation/Pipeline.html#data-format">details on data format</a></li>
</ul>
</li>
<li>Find a valid CNN architecture by using <a href="http://elektronn.github.io/documentation/elektronn.net.html#elektronn.net.netutils.CNNCalculator">elektronn.net.netutils.CNNCalculator()</a>. 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.</li>
<li>Edit <a href="https://github.com/ELEKTRONN/ELEKTRONN/blob/master/elektronn/examples/config_template.py">examples/config_template.py</a> as a new file to specify your training scenario.</li>
<li>
<p>Run the script <a href="https://github.com/ELEKTRONN/ELEKTRONN/blob/master/elektronn/scripts/elektronn-train">scripts/elektronn-train</a> from command line:</p>
<pre><code>elektronn-train </path/to_config_file> [ --gpu={Auto|False|<int>}]</code></pre>
</li>
<li>
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 <a href="http://elektronn.github.io/documentation">documentation</a>.
</li>
</ul>
</section>