README.md 4.11 KB
Newer Older
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
1
2
# Deep Finder

ARONSSOHN Constantin's avatar
ARONSSOHN Constantin committed
3
The code in this repository is described in [this pre-print](https://www.biorxiv.org/content/10.1101/2020.04.15.042747v1). This paper has been submitted to Nature Methods and has now been [published](https://doi.org/10.1038/s41592-021-01275-4).
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
4

5
6
7
__To reviewers__: you can follow our [tutorial](https://deepfinder.readthedocs.io/en/latest/tutorial.html) to reproduce segmentations from our paper.

__Disclaimer:__ DeepFinder is still in its early stages, any feedback is welcome for enhancing the user experience.
8

9
10
__News__: (29/01/20) A first version of the GUI is now available in folder pyqt/. [More information...](###Using the GUI) 

MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
11
12
13
14
## Contents
- [System requirements](##System requirements)
- [Installation guide](##Installation guide)
- [Instructions for use](##Instructions for use)
15
- [Documentation](https://deepfinder.readthedocs.io/en/latest/)
16
- [Google group](https://groups.google.com/g/deepfinder)
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
17
18

## System requirements
ARONSSOHN Constantin's avatar
ARONSSOHN Constantin committed
19
__Deep Finder__ has been implemented using __Python 3__ and is based on the __Keras__ package. It has been tested on Linux (Debian 10), and should also work on Mac OSX as well as Windows.
20

21
The algorithm needs an __Nvidia GPU__ and __CUDA__ to run at reasonable speed (in particular for training). The present code has been tested on Tesla K80 and M40 GPUs. For running on other GPUs, some parameter values (e.g. patch and batch sizes) may need to be changed to adapt to available memory.
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
22

23
24
25
26
```diff
- If above conditions are not met, we cannot guarantee the functionality of our code at this time.
```

MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
27
### Package dependencies
28
Deep Finder depends on following packages. The package versions for which our software has been tested are displayed in brackets:
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
29
```
30
31
32
33
tensorflow-gpu (2.6.0)
keras          (2.6.0)
numpy          (1.19.5)
h5py           (3.1.0)
34
35
36
37
38
39
lxml           (4.3.4)
scikit-learn   (0.21.2)     
scikit-image   (0.15.0)  
matplotlib     (3.1.0)
mrcfile        (1.1.2)
PyQt5          (5.13.2)
40
pyqtgraph      (0.10.0)
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
41
42
43
```

## Installation guide
44
45
46
Before installation, you need a python environment on your machine. If this is not the case, we advise installing [Miniconda](https://docs.conda.io/en/latest/miniconda.html).

Then, you need to download the present repository. Next, open a terminal, place yourself in your deep-finder folder and run:
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
47
```
48
cd /path/to/deep-finder/
49
pip install -r requirements_gpu.txt
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
50
```
51
Also, in order for Keras to work with your Nvidia GPU, you need to install CUDA. For more details about installing Keras and CUDA, please see [Keras installation instructions](https://keras.io/#installation).
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
52

53
Once these steps have been achieved, the user should be able to run Deep Finder.
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
54
55

## Instructions for use
56
57
### Using the scripts
Instructions for using Deep Finder are contained in folder examples/. The scripts contain comments on how the toolbox should be used. To run a script, first place yourself in its folder. For example, to run the target generation script:
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
58
```
59
60
cd examples/training/
python step1_generate_target.py
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
61
```
62
63

### Using the GUI
64
The GUI (Graphical User Interface) is launchable from folder bin/, and should be more intuitive for those who are not used to work with script. Currently, 5 GUIs are available (tomogram annotation, target generation, training, segmentation, clustering) and allow the same functionalities as the scripts in example/. To run a GUI, first open a terminal. For example, to run the target generation GUI:
MOEBEL Emmanuel's avatar
MOEBEL Emmanuel committed
65
```
66
/path/to/deepfinder/bin/generate_target
67
68
```

69
![Training GUI](./images/gui_segment.png)
70
71
72


__Notes:__ 
73
- working examples are contained in examples/analyze/, where Deep Finder processes the test tomogram from the [SHREC'19 challenge](http://www2.projects.science.uu.nl/shrec/cryo-et/2019/). 
74
75
- The script in examples/training/ will fail because the training data is not included in this Gitlab. 
- The evaluation script (examples/analyze/step3_launch_evaluation.py) is the one used in SHREC'19, which needs additional packages (pathlib and pycm, can be installed with pip). The performance of Deep Finder has been evaluated by an independent group, and the result of this evaluation has been published in Gubins & al., "SHREC'19 track: Classification in cryo-electron tomograms".