Skip to content

Commit 7daa9d1

Browse files
chadhatchadhat
authored
Merge pull request #14 from SIPEC-Animal-Data-Analysis/update_readme
Update readme
2 parents e07fcd5 + 23357b7 commit 7daa9d1

2 files changed

Lines changed: 127 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 96 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -5,83 +5,127 @@
55
SIPEC: the deep-learning Swiss knife for behavioral data analysis
66

77

8-
This is the repository accompanying SIPEC, which is a pipeline that enables all-round behavioral analysis through usage of state-of-the-art neural networks.
9-
You can use SIPEC by either combining its many modules in your own workflow, or use template workflows, that have been used in the paper, which can be accessed via command line.
8+
This is the repository accompanying the [SIPEC publication*](https://doi.org/10.1101/2020.10.26.355115), which is a pipeline that enables all-round behavioral analysis through the usage of state-of-the-art neural networks.
9+
You can use SIPEC by either combining its modules in your own workflow, or using template workflows, that have been used in the paper, which can be accessed via command line.
1010
We will be providing more detailed and illustrated instructions soon. Moreover, extensive documentation and more exemplary data will be made available.
1111

12+
We welcome feedback via GitHub issues.
13+
14+
15+
* Markus Marks, Jin Qiuhan, Oliver Sturman, Lukas von Ziegler, Sepp Kollmorgen, Wolfger von der Behrens, Valerio Mante, Johannes Bohacek, Mehmet Fatih Yanik
16+
bioRxiv 2020.10.26.355115; doi: https://doi.org/10.1101/2020.10.26.355115
17+
1218
![](supp_files/Supplementary%20Video%201.gif)
1319

14-
## Installation
20+
## Usage/Installation
1521

16-
This setup instructions are for Linux (Mac and Windows will follow).
17-
Particularly this has been tested on Ubuntu 18.
18-
For really making use of SIPEC your machine should have at least one powerful, ideally multiple GPUs.
19-
It has been tested with either NVIDIA GTX 2080 Ti or V100 GPUs.
20-
The overall setup should be done in less than 5 minutes.
22+
**For using SIPEC, your machine should have a powerful GPU.
23+
We have tested the scripts with NVIDIA GTX 1080, NVIDIA GTX 2080 Ti and V100 GPUs.**
2124

22-
We recommend creating a virtual environment using anaconda.
25+
### Docker
2326

24-
```
25-
wget https://repo.anaconda.com/archive/Anaconda3-2020.02-Linux-x86_64.sh
26-
bash Anaconda3-2020.02-Linux-x86_64.sh -b
27-
rm Anaconda3-2020.02-Linux-x86_64.sh
27+
We provide a docker image with the required environment to run the SIPEC scripts.
2828

29-
source ./anaconda3/bin/activate
30-
conda init
29+
In order to pull the docker image you would first need to install `docker` and `nvidia-docker2` following the instructions on:
3130

32-
conda create -n new python=3.7 -y
33-
conda activate new
34-
conda update -n base -c defaults conda
31+
> [https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
3532
36-
conda install tensorflow-gpu=1.14.0 -y
37-
conda install keras=2.3.1
38-
pip install opencv-contrib-python
33+
After installing `docker` and `nvidia-docker2` you can download the SIPEC image by executing:
3934

40-
apt install build-essential libglib2.0-0 libsm6 libxext6 libxrender-dev -y
41-
apt install libsm6 libxrender1 libfontconfig1 -y
42-
apt install --no-install-recommends ffmpeg && pip install ffmpeg scikit-video
43-
```
35+
```
36+
docker pull chadhat/sipec:tf2
37+
```
4438

45-
Now that our environment is setup we can download and install SIPEC.
39+
**Note:** In order to run docker without `sudo` you would need to create a docker group and add your user to it. Please follow the instructions on: [https://docs.docker.com/engine/install/linux-postinstall/](https://docs.docker.com/engine/install/linux-postinstall/)
4640

47-
```
48-
git clone https://github.com/damaggu/SIPEC.git
41+
The docker image contains the environment, sample data and SIPEC scripts.
4942

50-
cd DeepLab-SwissKnife
51-
pip install -r requirements.txt
52-
```
53-
You can now add SIPEC to your ~/.bashrc or run this command to add it to your python path.
54-
```
55-
export PYTHONPATH="PATH-TO-SIPEC:${PYTHONPATH}"
56-
```
43+
### Environment installation
5744

58-
## Usage
45+
If you do not want to use the docker container you can follow these installation instructions for **Linux**.
46+
These instructions have been tested on Ubuntu 20.04 but would most likely also work on Ubuntu 18.
5947

60-
#### own pipline
61-
You can build your own workflow by combining functions of the different SIPEC modules.
62-
To do so, you usually need to define a config file, that specifies parameters for the network and training to be used.
63-
Next, you will need to load your data via the dataloader module.
64-
This enables you to run the different SIPEC modules.
48+
#### Step 1: Install Cuda 11.0.3
49+
50+
Download and install Cuda 11.0.3 (We have tested the setup with this cuda version).
51+
52+
After the installation is finised run `nvcc --version` to check the installed cuda version.
53+
54+
#### Step 2: Install cuDNN 8
55+
56+
Download and install cuDNN 8. For this you would need to register for NVIDIA's developer program (it is free):
57+
58+
https://developer.nvidia.com/cudnn-download-survey
59+
60+
#### Step 3:
6561

66-
#### predefined pipelines
62+
After you have successfully installed cuda and cuDNN:
63+
* clone the SIPEC repository
64+
* open a terminal and go to the cloned SIPEC directory: `cd PATH_TO_SIPEC_ON_YOUR_MACHINE`
65+
* run the following commands
66+
```
67+
chmod +x setup.sh
68+
./setup.sh
69+
```
70+
The script will ask you for the root password.
71+
72+
#### Step 4:
73+
The script `setup.sh` has created a virtual environment named `env` in the repository folder.
74+
Activate the environment by executing:
75+
```
76+
source ./env/bin/activate
77+
```
78+
79+
#### Step 5:
80+
81+
To test your setup run one of the scripts in the folder `SwissKnife`, e.g.,
82+
```
83+
python segmentation.py --help
84+
```
85+
## Usage
86+
87+
### predefined pipelines
6788

6889
You can run these template pipelines for training or evaluation of SIPEC networks.
69-
To do so, you need to adjust the paths in the respective python files.
70-
The gpu flag allows you to run a script on a specific GPU while keeping other GPUs free to run other scripts on.
90+
91+
If your system has multiple GPUs, the `--gpu` flag allows you to run a script on a specific GPU while keeping other GPUs free to run other scripts.
7192

7293
Here are some example command line usages of the pipeline
73-
```
74-
python segmentation.py --operation train_mouse --gpu 2 --cv_folds 0 --random_seed 2
75-
python identification.py --config identification_config --network ours --operation train_primate --gpu 3 --fraction 0.6 --video path_to_video
76-
python behavior.py --gpu 3 --operation train --config primate_final
77-
python poseestimation.py --operation train_mouse --gpu 1
78-
python full_inference.py --operation primate --gpu 2
79-
python visualization.py --operation vis_results_primate
80-
```
94+
<pre><code>
95+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
96+
classification_comparison.py --gpu 0 --config_name behavior_config_final --random_seed 1 --output_path=/home/user/results
97+
98+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
99+
poseestimation.py --gpu 0 --operation train_mouse --output_path=/home/user/results/
100+
101+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
102+
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
103+
104+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
105+
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
106+
107+
docker container run -v "<b>RESULTS_PATH</b>:/home/user/results" --runtime=nvidia --rm sipec:main_tf2
108+
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
109+
</pre></code>
110+
111+
Where, **RESULTS_PATH** is the path on your machine where you would like to write the results.
81112

82113
The output of these workflows are results files that quantify the network performance, and a .h5 file that are the network weights for subsequent use.
83114
Depending on modules to be trained, and the GPUs available the training can take multiple hours or days.
84115

116+
In order to find all the arguments that can be passed to the scripts use the flag `--help`, e.g.,
117+
118+
```
119+
docker container run --runtime=nvidia --rm sipec:main_tf2 segmentation.py --help
120+
```
121+
122+
123+
### own pipline
124+
You can build your own workflow by combining functions of the different SIPEC modules.
125+
To do so, you usually need to define a config file, that specifies parameters for the network and training to be used.
126+
Next, you will need to load your data via the dataloader module.
127+
This enables you to run the different SIPEC modules.
128+
85129
## Annotation of Data
86130

87131
For the annotation of segmentation as well as behavioral data we recommend the use of the VGG annotator, that can be found here:

‎setup.sh‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/bin/bash
2+
3+
# Updating the system and installing essentials
4+
5+
sudo apt-get update
6+
sudo apt-get install -y build-essential software-properties-common
7+
8+
# Adding the deadsnakes repository for Python 3.7
9+
sudo add-apt-repository ppa:deadsnakes/ppa -y
10+
sudo apt-get update
11+
sudo apt-get install -y libglib2.0-0 libsm6 libxext6 libxrender-dev python3.7 python3.7-dev python3.7-venv \
12+
wget vim git htop rsync libxrender1 libfontconfig
13+
14+
sudo apt-get update
15+
16+
sudo apt-get install -y --no-install-recommends ffmpeg
17+
18+
sudo apt-get install unzip
19+
20+
#wget https://bootstrap.pypa.io/get-pip.py && python3.7 get-pip.py && rm get-pip.py
21+
22+
python3.7 -m venv env
23+
24+
source ./env/bin/activate
25+
wget https://bootstrap.pypa.io/get-pip.py && python3.7 get-pip.py && rm get-pip.py
26+
27+
python -m pip install --upgrade pip && pip install -r requirements.txt
28+
29+
echo export PYTHONPATH=$PWD:'$PYTHONPATH' >> ~/.bashrc
30+
31+
echo export PATH=$PWD/SwissKnife:'$PATH' >> ~/.bashrc

0 commit comments

Comments
 (0)