Skip to content

Commit c604349

Browse files
chadhatchadhat
committed
readme rst
1 parent 27d2287 commit c604349

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎docs/source/README.rst‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
Usage/Installation
2+
------------------
3+
4+
**For really making use of SIPEC, your machine should have a powerful
5+
GPU. We have tested the scripts with NVIDIA GTX 1080, NVIDIA GTX 2080 Ti
6+
and V100 GPUs.**
7+
8+
Docker
9+
~~~~~~
10+
11+
We provide a docker image with the required environment to run the SIPEC
12+
scripts.
13+
14+
In order to pull the docker image you would first need to install
15+
``docker`` and ``nvidia-docker2`` following the instructions on:
16+
17+
https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
18+
19+
After installing ``docker`` and ``nvidia-docker2`` you can download the
20+
SIPEC image by executing:
21+
22+
::
23+
24+
docker pull chadhat/sipec:tf2
25+
26+
**Note:** In order to run docker without ``sudo`` you would need to
27+
create a docker group and add your user to it. Please follow the
28+
instructions on:
29+
https://docs.docker.com/engine/install/linux-postinstall/
30+
31+
The docker image contains the environment and SIPEC scripts.
32+
33+
Environment installation
34+
~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
If you do not want to use the docker container you can follow these
37+
installation instructions for **Linux**. These instructions have been
38+
tested on Ubuntu 18 and 20.04.
39+
40+
Step 1: Install Cuda 11.0.3
41+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
42+
43+
Download and install Cuda 11. We have tested the setup with cuda 11.0.3.
44+
45+
After the installation is finised run ``nvcc --version`` to check the
46+
installed cuda version.
47+
48+
Step 2: Install cuDNN 8
49+
^^^^^^^^^^^^^^^^^^^^^^^
50+
51+
Download and install cuDNN 8. For this you would need to register for
52+
NVIDIA’s developer program (it is free):
53+
54+
https://developer.nvidia.com/cudnn-download-survey
55+
56+
Step 3:
57+
^^^^^^^
58+
59+
After you have successfully installed cuda and cuDNN: \* clone the SIPEC
60+
repository \* open a terminal and go to the cloned SIPEC directory:
61+
``cd PATH_TO_SIPEC_ON_YOUR_MACHINE`` \* run the following commands
62+
63+
::
64+
65+
chmod +x setup.sh
66+
./setup.sh
67+
68+
The script will ask you for the root password.
69+
70+
Usage
71+
-----
72+
73+
predefined pipelines
74+
~~~~~~~~~~~~~~~~~~~~
75+
76+
You can run these template pipelines for training or evaluation of SIPEC
77+
networks.
78+
79+
If your system has multiple GPUs, the ``--gpu`` flag allows you to run a
80+
script on a specific GPU while keeping other GPUs free to run other
81+
scripts.
82+
83+
Here are some example command line usages of the pipeline
84+
85+
.. raw:: html
86+
87+
<pre><code>
88+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
89+
classification_comparison.py --gpu 0 --config_name behavior_config_final --random_seed 1 --output_path=/home/user/results
90+
91+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
92+
poseestimation.py --gpu 0 --operation train_mouse --output_path=/home/user/results/
93+
94+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
95+
behavior.py --gpu 0 --annotations /home/user/data/20180124T113800-20180124T115800_0.csv --video /home/user/data/fullvids_20180124T113800-20180124T115800_%T1_0.mp4 --output_path /home/user/results
96+
97+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
98+
full_inference.py --gpu 0 --species mouse --video /home/user/data/full_inference_and_vis_data/animal5678_day2.avi --segnet_path "/home/user/data/full_inference_and_vis_data/mask_rcnn_mouse_0095.h5" --max_ids 4 --results_sink /home/user/results/full_inference
99+
100+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
101+
segmentation.py --cv_folds 0 --gpu 0 --frames /home/user/data/mouse_segmentation_single/annotated_frames --annotations /home/user/data/mouse_segmentation_single/mouse_top_segmentation.json
102+
</pre>
103+
104+
Where, **RESULTS_PATH** is the path on your machine where you would like
105+
to write the results.
106+
107+
The output of these workflows are results files that quantify the
108+
network performance, and a .h5 file that are the network weights for
109+
subsequent use. Depending on modules to be trained, and the GPUs
110+
available the training can take multiple hours or days.
111+
112+
In order to find all the arguments that can be passed to the scripts use
113+
the flag ``--help``, e.g.,
114+
115+
::
116+
117+
docker container run --runtime=nvidia --rm sipec:main_tf2 segmentation.py --help
118+
119+
own pipline
120+
~~~~~~~~~~~
121+
122+
You can build your own workflow by combining functions of the different
123+
SIPEC modules. To do so, you usually need to define a config file, that
124+
specifies parameters for the network and training to be used. Next, you
125+
will need to load your data via the dataloader module. This enables you
126+
to run the different SIPEC modules.
127+
128+
Annotation of Data
129+
------------------
130+
131+
For the annotation of segmentation as well as behavioral data we
132+
recommend the use of the VGG annotator, that can be found here:
133+
http://www.robots.ox.ac.uk/~vgg/software/via/ For the annotation of
134+
identification data we provide a GUI:
135+
https://github.com/damaggu/idtracking_gui
136+
137+
Example Data
138+
------------
139+
140+
Mouse OFT behavioral videos
141+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
142+
143+
For open field (OFT) mouse behavioral analysis, you can use the
144+
exemplary data from Sturman et al. from zenedo.
145+
https://zenodo.org/record/3608658 The corresponding labels can be
146+
accessed here.
147+
https://github.com/ETHZ-INS/DLCAnalyzer/tree/master/data/OFT/Labels
148+
149+
Cite
150+
----
151+
152+
If you use any part of this code for your work, please cite the
153+
following:
154+
155+
::
156+
157+
SIPEC: the deep-learning Swiss knife for behavioral data analysis
158+
Markus Marks, Jin Qiuhan, Oliver Sturman, Lukas von Ziegler, Sepp Kollmorgen, Wolfger von der Behrens, Valerio Mante, Johannes Bohacek, Mehmet Fatih Yanik
159+
bioRxiv 2020.10.26.355115; doi: https://doi.org/10.1101/2020.10.26.355115

0 commit comments

Comments
 (0)