This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
pipeline:window:cryolo [2019/02/13 17:46] twagner [Data preparation] |
pipeline:window:cryolo [2019/09/17 13:18] twagner [Picking] |
||
---|---|---|---|
Line 7: | Line 7: | ||
* crYOLO makes picking **smart** -- The network learns the context of particles (e.g. not to pick particles on carbon or within ice contamination ) | * crYOLO makes picking **smart** -- The network learns the context of particles (e.g. not to pick particles on carbon or within ice contamination ) | ||
* crYOLO makes training **easy** -- You might use a general network model and skip training completely. However, if the general model doesn' | * crYOLO makes training **easy** -- You might use a general network model and skip training completely. However, if the general model doesn' | ||
+ | * crYOLO makes training **tolerant** -- Don't worry if you miss quite a lot particles during creation of your training set. [[: | ||
- | In this tutorial we explain our recommended configurations for single particle and filament projects. You can find more information about supported networks and about the config file in the following articles: | + | In this tutorial we explain our recommended configurations for single particle and filament projects. You can find more information |
+ | * [[https:// | ||
* [[: | * [[: | ||
* [[: | * [[: | ||
+ | |||
+ | |||
+ | |||
+ | < | ||
+ | |||
+ | You can find more technical details in our paper: | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | ---- | ||
+ | |||
+ | We are also proud that crYOLO was recommended by F1000: | ||
+ | |||
+ | //" | ||
+ | < | ||
+ | < | ||
+ | <a href=" | ||
+ | </ | ||
+ | </ | ||
+ | |||
===== Installation ===== | ===== Installation ===== | ||
You can find the download and installation instructions here: [[howto: | You can find the download and installation instructions here: [[howto: | ||
- | ===== Picking - Using a model trained for your data ===== | + | ===== Tutorials |
+ | Depending what you want to do, you can follow one of these self-contained Tutorials: | ||
- | ==== Data preparation ==== | + | - I would like to train a model from scratch for picking my particles |
- | CrYOLO supports MRC, TIF and JPG files. It can work with 32 bit data, 8 bit data and 16 bit data. | + | - I would like to train a model from scratch for picking filaments. |
- | It will work on original MRC files, but it will probably improve when the data are filtered. Therefore you should low-pass filter them to a reasonable level. Since Version 1.2 crYOLO can automatically do that for you. You just have to add | + | - I would like to refine |
- | < | + | |
- | " | + | The **first and the second tutorial** are the most common use cases and well tested. The **third tutorial** is still experimental but might give you better results in less time and less training data. |
- | </ | + | |
- | to the model section in your config file to filter your images down to an absolute frequency of 0.1. The filtered images are saved in folder '' | + | |
+ | |||
+ | ===== Picking particles - Using a model trained for your data ===== | ||
+ | This tutorial explains you how to train a model specific for you dataset. | ||
If you followed the installation instructions, | If you followed the installation instructions, | ||
Line 31: | Line 57: | ||
source activate cryolo | source activate cryolo | ||
</ | </ | ||
+ | ==== Data preparation ==== | ||
+ | {{page> | ||
- | In the following I will assume that your image data is in the folder '' | + | ==== Start crYOLO ==== |
+ | {{page> | ||
- | The next step is to create training data. To do so, we have to pick single particles manually in several micrographs. Ideally, the micrographs are picked to completion. One may ask how many micrographs have to be picked? It depends! Typically 10 micrographs are a good start. However, that number may increase / decrease due to several factors: | + | ==== Configuration ==== |
- | * A very heterogenous background could make it necessary | + | {{page> |
- | * If your micrograph is only sparsely decorated, | + | You can now press the Start button |
- | We recommend that you start with 10 micrographs, | + | {{page> |
+ | ==== Training ==== | ||
- | {{:pipeline: | + | {{page>pipeline: |
- | To create your training data, crYOLO is shipped with a tool called " | + | ==== Picking ==== |
+ | {{page> | ||
- | Start the box manager with the following command: | ||
- | < | ||
- | cryolo_boxmanager.py | ||
- | </ | ||
- | Now press //File -> Open image folder// and the select the '' | + | ==== Visualize the results ==== |
+ | {{page>pipeline: | ||
- | * LEFT MOUSE BUTTON: Place a box | + | ==== Evaluate your results ==== |
- | * HOLD LEFT MOUSE BUTTON: Move a box | + | {{page> |
- | * CONTROL + LEFT MOUSE BUTTON: Remove a box | + | ===== Picking particles - Without training using a general model ===== |
+ | Here you can find how to apply the general models we trained for you. If you would like to train your own general model, please see our extra wiki page: [[: | ||
- | You can change the box size in the main window, by changing the number in the text field labeled //Box size://. Press //Set// to apply it to all picked particles. For picking, you should the use minimum sized square which encloses your particle. | + | Our general models |
- | If you finished picking from your micrographs, you can export your box files with //Files -> Write box files//. | + | If you followed the installation instructions, you now have to activate the cryolo virtual environment |
- | Create a new directory called '' | + | |
- | + | ||
- | Now create a third folder with the name '' | + | |
- | ==== Configuration ==== | ||
- | You now have to create a config file your picking project. To do this type: | ||
< | < | ||
- | touch config.json | + | source activate cryolo |
</ | </ | ||
+ | ==== Start crYOLO ==== | ||
+ | {{page> | ||
- | To use the [[: | + | ==== Configuration==== |
- | <code json config.json> | + | In the GUI choose |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | " | + | {{ :pipeline:window:cryolo_filter_options.png? |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | [[:downloads:cryolo_1# |
- | " | + | |
- | | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | | + | * General model trained for low-pass filtered images : Select // |
- | | + | * General model trained for JANNI-denoised images: Select // |
- | " | + | * General model for negative stain images: Select filter |
- | " | + | Press the start button to write the configuration file to disk. |
- | } | + | |
- | } | + | |
+ | <hidden **Create the configuration file using the command line**> | ||
+ | In the following I assume that you target box size is 220. Please adapt if necessary. | ||
+ | |||
+ | For the general **[[: | ||
+ | < | ||
+ | cryoloo.py config config_cryolo_.json 220 --filter LOWPASS --low_pass_cutoff 0.1 | ||
</ | </ | ||
- | // | ||
- | Please set the value in the //" | + | For the general model trained with **neural-network denoised cryo images** (with [[: |
< | < | ||
- | " | + | cryoloo.py config config_cryolo_.json 220 --filter JANNI --janni_model / |
</ | </ | ||
- | crYOLO will automatically check if an image in full_data is available in the '' | ||
- | Please note the wiki entry about the [[:cryolo_config|crYOLO configuration file]] if you want to know more details. | + | For the general model for **negative stain data** please run: |
+ | < | ||
+ | cryoloo.py config config_cryolo_.json 220 --filter NONE | ||
+ | </ | ||
+ | </ | ||
+ | ==== Picking ==== | ||
+ | {{page> | ||
+ | ==== Visualize the results ==== | ||
+ | {{page> | ||
+ | ===== Picking particles - Using the general model refined for your data ===== | ||
- | ==== Training ==== | ||
- | Now you are ready to train the model. In case you have multiple GPUs, you should first select a free GPU. The following command will show the status of all GPUs: | + | Since crYOLO 1.3 you can train a model for your data by //fine-tuning// the general model. |
- | < | + | |
- | nvidia-smi | + | |
- | </code> | + | |
- | For this tutorial, we assume that you have either a single GPU or want to use GPU 0. Therefore we add '-g 0' after each command below. However, if you have multiple (e.g GPU 0 and GPU 1) you could also use both by adding '-g 0 1' after each command. | + | |
- | Navigate to the folder with '' | + | What does // |
- | **1. Warm up your network** | + | The general model was trained on a lot of particles with a variety of shapes and therefore learned a very good set of generic features. The last layers, however, learn a pretty abstract representation of the particles and it might be that they do not perfectly fit for your particle at hand. Fine-tuning only traines the last two convolutional layers, but keep the others fixed. This adjusts the more abstract representation for your specific problem. |
- | < | + | Why should I // |
- | cryolo_train.py | + | - From theory, using fine-tuning should reduce the risk of overfitting ((Overfitting means, that the model works good on the training micrographs, |
- | </code> | + | |
+ | - The training will need less GPU memory ((We are testing crYOLO with its default configuration on graphic cards with >= 8 GB memory. Using the fine tune mode, it should also work with GPUs with 4 GB memory)) and therefore is usable with NVIDIA cards with less memory. | ||
+ | |||
+ | However, the fine tune mode is still somewhat experimental and we will update this section if see more advantages or disadvantages. | ||
- | **2. Train your network** | + | If you followed the installation instructions, |
< | < | ||
- | cryolo_train.py -c config.json -w 0 -g 0 | + | source activate cryolo |
</ | </ | ||
- | The final model will be called | + | ==== Data preparation ==== |
+ | {{page> | ||
+ | |||
+ | ==== Start crYOLO ==== | ||
+ | |||
+ | {{page> | ||
+ | ==== Configuration ==== | ||
+ | {{page> | ||
+ | |||
+ | {{ : | ||
+ | Furthermore, | ||
+ | |||
+ | You can now press the Start button to create configuration file. | ||
+ | |||
+ | <hidden **Create the configuration file using the command line: | ||
+ | |||
+ | I assume your box files for training are in the folder | ||
- | The training stops when the " | ||
< | < | ||
- | cryolo_train.py -c config.json -w 0 -g 0 -e 10 | + | cryoloo.py config |
</ | </ | ||
- | to the training command. | + | |
- | ==== Picking ==== | + | To get a full description of all available options type: |
- | You can now use the model weights saved in '' | + | |
< | < | ||
- | cryolo_predict.py -c config.json -w model.h5 -i full_data/ -g 0 -o boxfiles/ | + | cryoloo.py config -h |
</ | </ | ||
- | You will find the picked particles in the directory '' | + | If you want to specify seperate validation folders you can use the %%--%%valid_image_folder and %%--%%valid_annot_folder options: |
- | If you want to pick less conservatively or more conservatively you might want to change the selection threshold from the default of 0.3 to a less conservative value like 0.2 or more conservative value like 0.4 using the //-t// parameter: | ||
< | < | ||
- | cryolo_predict.py -c config.json -w model.h5 -i full_data/ | + | cryoloo.py config |
</ | </ | ||
- | ==== Visualize the results | + | </ |
+ | |||
+ | ==== Training | ||
+ | |||
+ | Now you are ready to train the model. In case you have multiple GPUs, you should first select a free GPU. The following command will show the status of all GPUs: | ||
- | To visualize your results you can use the box manager: | ||
< | < | ||
- | cryolo_boxmanager.py | + | nvidia-smi |
</ | </ | ||
- | Now press //File -> Open image// folder and the select the '' | ||
+ | For this tutorial, we assume that you have either a single GPU or want to use GPU 0. | ||
+ | In the GUI choose the action //train//. In the //" | ||
+ | {{ : | ||
- | ===== Picking - Without training using a general model ===== | + | In the //" |
+ | {{ : | ||
+ | <note important> | ||
+ | The number of layers to fine tune (specified by layers_fine_tune in the //" | ||
+ | </ | ||
- | The general model can be found here: [[howto: | ||
- | ==== Configuration==== | ||
- | The next step is to create a configuration file. Type: | ||
- | < | ||
- | touch config.json | ||
- | </ | ||
- | Open the file with your preferred editor. | + | <note tip> |
- | For the general | + | **Training on CPU** |
- | <code json config.json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | Please set the value in the //" | + | The fine tune mode is especially useful if you want to [[downloads: |
+ | </note> | ||
+ | |||
+ | <hidden **Run training with the command line**> | ||
+ | In comparison to the training from scratch, you can skip the warm up training ( -w 0 ). Moreover you have to add the //%%--%%fine_tune// flag to tell crYOLO that it should do fine tuning. You can also tell crYOLO how many layers it should | ||
+ | |||
+ | < | ||
+ | cryolo_train.py -c config.json -w 0 -g 0 --fine_tune -lft 2 | ||
+ | </ | ||
+ | </ | ||
==== Picking ==== | ==== Picking ==== | ||
- | Just follow the description given [[pipeline: | + | {{page>pipeline: |
- | As for a direct trained model, you might want to play around with the -t parameter to make picking less or more conservative. | + | ==== Visualize |
+ | {{page> | ||
+ | ==== Evaluate your results ==== | ||
+ | {{page> | ||
===== Picking filaments - Using a model trained for your data ===== | ===== Picking filaments - Using a model trained for your data ===== | ||
Since version 1.1.0 crYOLO supports picking filaments. | Since version 1.1.0 crYOLO supports picking filaments. | ||
Line 213: | Line 242: | ||
{{: | {{: | ||
- | ==== Data preparation ==== | + | If you followed the installation instructions, you now have to activate the cryolo virtual environment with |
- | {{ : | + | |
- | After this is done, you have to prepare training data for your model. | ||
- | Right now, you have to use the sxhelixboxer.py to generate the training data: | ||
< | < | ||
- | sxhelixboxer.py --gui my_images/ | + | source activate cryolo |
</ | </ | ||
- | After tracing your training data in sxhelixboxer, | ||
- | ==== Configuration | + | ==== Data preparation |
- | You can configure it the same way as for a " | + | {{ :pipeline:window:settings_e2helixboxer.png?300|}} |
- | <code json config.json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | | + | |
- | " | + | The first step is to create the training data for your model. |
- | " | + | < |
- | " | + | e2helixboxer.py --gui my_images/*.mrc |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | + | ||
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | + | ||
- | " | + | |
- | " | + | |
- | " | + | |
- | + | ||
- | " | + | |
- | } | + | |
- | } | + | |
</ | </ | ||
- | // | ||
- | Just adapt the anchors accordingly to your box size. | + | After tracing |
- | ==== Training ==== | + | For projects with roughly 20 filaments per image we successfully trained on 40 images (=> 800 filaments). |
- | In principle, there is not much difference in training | + | ==== Start crYOLO ==== |
+ | {{page>pipeline: | ||
- | **1. Warm up your network** | ||
- | < | + | ==== Configuration ==== |
- | cryolo_train.py -c config.json -w 10 -g 0 | + | {{page>pipeline: |
- | </code> | + | |
- | **2. Train your network** | + | You can now press the Start button to create you configuration file. |
- | <code> | + | {{page>pipeline: |
- | cryolo_train.py -c config.json -w 0 -g 0 -e 10 | + | ==== Training ==== |
- | </ | + | |
- | The final model will be called '' | + | {{page> |
==== Picking ==== | ==== Picking ==== | ||
+ | Select the action prediction and fill all arguments in the “Required arguments” tab: | ||
+ | {{ : | ||
- | The biggest difference in picking filaments with crYOLO is during prediction. However, there are just three additional parameters needed: | + | Now select the " |
- | * //- -filament//: Option that tells crYOLO that you want to predict filaments | + | {{ :pipeline:window:cryolo_filament.png?700 |}} |
- | * //-fw//: Filament width (pixels) | + | |
- | * //-bd//: Inter-Box distance (pixels). | + | |
+ | Press the start button to start the picking. The directory '' | ||
+ | |||
+ | You can find a detailed description [[: | ||
+ | |||
+ | <hidden **Run prediction in commmand line**> | ||
Let's assume you want to pick a filament with a width of 100 pixels (-fw 100). The box size is 200x200 and you want a 90% overlap (-bd 20). Moreover, you wish that each filament has at least 6 boxes (-mn 6). The micrographs are in the '' | Let's assume you want to pick a filament with a width of 100 pixels (-fw 100). The box size is 200x200 and you want a 90% overlap (-bd 20). Moreover, you wish that each filament has at least 6 boxes (-mn 6). The micrographs are in the '' | ||
< | < | ||
- | cryolo_predict.py -c config.json -w model.h5 -i full_data --filament -fw 100 -bd 20 -o boxes/ -g 0 -mn 6 | + | cryolo_predict.py -c cryolo_config.json -w cryolo_model.h5 -i full_data --filament -fw 100 -bd 20 -o boxes/ -g 0 -mn 6 |
</ | </ | ||
+ | </ | ||
+ | |||
- | The directory '' | ||
==== Visualize the results ==== | ==== Visualize the results ==== | ||
- | You can use the boxmanager as described [[pipeline: | + | {{page>pipeline: |
===== Evaluate your results ===== | ===== Evaluate your results ===== | ||
- | + | {{page>pipeline: | |
- | The evaluation tool allows you, based on your validation data, to get statistics about your training. Unfortunately, | + | |
- | If you followed the tutorial, the validation data are selected randomly. With crYOLO 1.1.0 a run file for each training is created and saved into the folder runfiles/ in your project directory. This run file contains which files were selected for validation, and you can run your evaluation as follows: | + | |
- | < | + | |
- | cryolo_evaluation.py -c config.json -w model.h5 -r runfiles/ | + | |
- | </ | + | |
- | + | ||
- | The result looks like this: | + | |
- | {{:pipeline: | + | |
- | + | ||
- | The table contains several statistics: | + | |
- | * AUC: Area under curve of the precision-recall curve. Overall summary statistics. Perfect classifier = 1, Worst classifier = 0 | + | |
- | * Topt: Optimal confidence threshold with respect to the F1 score. It might not be ideal for your picking, as the F1 score weighs recall and precision equally. However in SPA, recall is often more important than the precision. | + | |
- | * R (Topt): Recall using the optimal confidence threshold. | + | |
- | * R (0.3): Recall using a confidence threshold of 0.3. | + | |
- | * R (0.2): Recall using a confidence threshold of 0.2. | + | |
- | * P (Topt): Precision using the optimal confidence threshold. | + | |
- | * P (0.3): Precision using a confidence threshold of 0.3. | + | |
- | * P (0.2): Precision using a confidence threshold of 0.2. | + | |
- | * F1 (Topt): Harmonic mean of precision and recall using the optimal confidence threshold. | + | |
- | * F1 (0.3): Harmonic mean of precision and recall using a confidence threshold of 0.3. | + | |
- | * F1 (0.2): Harmonic mean of precision and recall using a confidence threshold of 0.2. | + | |
- | * IOU (Topt): Intersection over union of the auto-picked particles and the corresponding ground-truth boxes. The higher, the better -- evaluated with the optimal confidence threshold. | + | |
- | * IOU (0.3): Intersection over union of the auto-picked particles and the corresponding ground-truth boxes. The higher, the better -- evaluated with a confidence threshold of 0.3. | + | |
- | * IOU (0.2): Intersection over union of the auto-picked particles and the corresponding ground-truth boxes. The higher, the better -- evaluated with a confidence threshold of 0.2. | + | |
- | + | ||
- | If the training data consists of multiple folders, then evaluation will be done for each folder separately. | + | |
- | Furthermore, | + | |
===== Advanced parameters ===== | ===== Advanced parameters ===== | ||
- | During **training** (// | + | During **training** (// |
- | * // | + | * //%%--%%warm_restarts//: |
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | * //%%-%%lft NUM_LAYER_FINETUNE//: | ||
- | During **picking** (// | + | During **picking** (// |
- | * //-t confidence_threshold//: With the -t parameter, you can let the crYOLO pick more conservative (e.g by adding -t 0.4 to the picking command) or less conservative (e.g by adding -t 0.2 to the picking command). The valid parameter range is 0 to 1. | + | * //-t CONFIDENCE_THRESHOLD//: With the -t parameter, you can let the crYOLO pick more conservative (e.g by adding -t 0.4 to the picking command) or less conservative (e.g by adding -t 0.2 to the picking command). The valid parameter range is 0 to 1. |
- | * //-d distance_in_pixel//: With the -d parameter you can filter your picked particles. Boxes with a distance (pixel) less than this value will be removed. | + | * //-d DISTANCE_IN_PIXEL//: With the -d parameter you can filter your picked particles. Boxes with a distance (pixel) less than this value will be removed. |
- | * // | + | * // |
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | * //-sr SEARCH_RANGE_FACTOR//: | ||
+ | |||
===== Help ===== | ===== Help ===== |