EMAN Wiki

User Tools

Site Tools

Trace:
eman2:programs:e2tomoseg

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
eman2:programs:e2tomoseg [2025/06/14 18:54] – steveludtkeeman2:programs:e2tomoseg [2025/06/14 21:05] (current) – steveludtke
Line 45: Line 45:
     * All of the other options should normally be fine, and you can press **Launch**     * All of the other options should normally be fine, and you can press **Launch**
  
-{{attachment:import_tomo.png|Import Tomogram|width="600"}}+{{http://blake.bcm.edu/dl/EMAN2/import_tomo.png|Import Tomogram}}
  
   * Note: There may be cases where it is impossible to pick a single scale which works well to annotate features at different scales. For example, if you are trying to annotate icosahedral viruses (large scale) and actin filaments (require small scale to identify) in the same tomogram, you may need to import the tomogram twice, with 2 different "shrink" factors, segment each feature at the appropriate scale, then rescale/merge the final segmentation maps. This is a topic for advanced users, and we encourage you to learn the basic pipeline with a single feature before attempting this.   * Note: There may be cases where it is impossible to pick a single scale which works well to annotate features at different scales. For example, if you are trying to annotate icosahedral viruses (large scale) and actin filaments (require small scale to identify) in the same tomogram, you may need to import the tomogram twice, with 2 different "shrink" factors, segment each feature at the appropriate scale, then rescale/merge the final segmentation maps. This is a topic for advanced users, and we encourage you to learn the basic pipeline with a single feature before attempting this.
Line 78: Line 78:
   * You have now created two new files in the //particles/// folder. You may repeat this process for other tomograms spanning the defocus range in your project. Each time you do this you will create a pair of new files in //particles///   * You have now created two new files in the //particles/// folder. You may repeat this process for other tomograms spanning the defocus range in your project. Each time you do this you will create a pair of new files in //particles///
  
-{{attachment:gen_ptcls.png|Particle Output|width="300"}}+{{ http://blake.bcm.edu/dl/EMAN2/gen_ptcls.png|Particle Output}}
  
 Note: The box size for training tiles MUST be 64x64. If the feature of interest does not fit in a 64x64 tile, you will need to create a more down-sampled copy of your tomogram for the recognition to work well. You can do this manually with e2proc3d.py. If you create a down-sampled version of a tomogram, use the exact same name and location as the original tomogram, but add a suffix to the name preceded by %%__%% (double underscore). eg - //tomograms/tomo_12345.hdf// might become //tomograms/tomo_12345%%__%%shrink2.hdf// Note: The box size for training tiles MUST be 64x64. If the feature of interest does not fit in a 64x64 tile, you will need to create a more down-sampled copy of your tomogram for the recognition to work well. You can do this manually with e2proc3d.py. If you create a down-sampled version of a tomogram, use the exact same name and location as the original tomogram, but add a suffix to the name preceded by %%__%% (double underscore). eg - //tomograms/tomo_12345.hdf// might become //tomograms/tomo_12345%%__%%shrink2.hdf//
Line 98: Line 98:
   * When you are finished, simply close the windows. The segmentation file will be saved automatically as "*_seg.hdf" with the same base file name as your ROIs.    * When you are finished, simply close the windows. The segmentation file will be saved automatically as "*_seg.hdf" with the same base file name as your ROIs. 
  
-{{attachment:segment_ptcls.png |Segment Particles|width="400"}}+{{ http://blake.bcm.edu/dl/EMAN2/segment_ptcls.png|Segment Particles}}
  
 ===== Build Training Set ===== ===== Build Training Set =====
Line 133: Line 133:
     * Open the //trainout_*.hdf// using the EMAN2 file browser. You should see something like:      * Open the //trainout_*.hdf// using the EMAN2 file browser. You should see something like: 
  
-{{attachment:nnet_trainout.png |Training Results |width="400"}}+{{ http://blake.bcm.edu/dl/EMAN2/nnet_trainout.png|Training Results}}
  
   * Zoom in or out a bit so there are 3*N images displayed in each row. For each image triplet, the first one is the tile from the tomogram, the second is the corresponding manual segmentation, and the third is the neural network output for the same FOI after training. The neural network is considered well trained if the third image matches the second image reasonably well. For the negative particles, both the second and the third images should be largely blank (the 3rd may contain some very weak features, this is ok).    * Zoom in or out a bit so there are 3*N images displayed in each row. For each image triplet, the first one is the tile from the tomogram, the second is the corresponding manual segmentation, and the third is the neural network output for the same FOI after training. The neural network is considered well trained if the third image matches the second image reasonably well. For the negative particles, both the second and the third images should be largely blank (the 3rd may contain some very weak features, this is ok). 
Line 142: Line 142:
 ===== Apply to Tomograms ===== ===== Apply to Tomograms =====
  
 +{{ http://blake.bcm.edu/dl/EMAN2/segment_out.png|Segmentation Result}}
 Finally, open **Apply the neural network panel**. Choose the tomogram you used to generate the boxes in the **tomograms** box, choose the saved neural network file (not the "trainout_" file, which is only used for visualization), and set the output filename. You can change the number of threads to use by adjusting the **thread** option. Keep in mind that using more threads will consume more memory as the tomogram slices are read in at the same time. For example, processing a 1k x 1k x 512 downsampled tomogram on 10 cores would use ~5 GB of RAM. Processing an unscaled 4k x 4k x 1k tomogram would increase RAM usage to ~24 GB. When this process finishes, you can open the output file in your favourite visualization software to view the segmentation.  Finally, open **Apply the neural network panel**. Choose the tomogram you used to generate the boxes in the **tomograms** box, choose the saved neural network file (not the "trainout_" file, which is only used for visualization), and set the output filename. You can change the number of threads to use by adjusting the **thread** option. Keep in mind that using more threads will consume more memory as the tomogram slices are read in at the same time. For example, processing a 1k x 1k x 512 downsampled tomogram on 10 cores would use ~5 GB of RAM. Processing an unscaled 4k x 4k x 1k tomogram would increase RAM usage to ~24 GB. When this process finishes, you can open the output file in your favourite visualization software to view the segmentation. 
- 
-{{attachment:segment_out.png |Segmentation Result |width="400"}} 
  
 To segment a different feature, just repeat the entire process for the each feature of interest. Make sure to use different file names (eg - _good2 and _bad2)! The trained network should generally work well on other tomograms using a similar specimen with similar microscope settings (clearly the A/pix value must be the same). To segment a different feature, just repeat the entire process for the each feature of interest. Make sure to use different file names (eg - _good2 and _bad2)! The trained network should generally work well on other tomograms using a similar specimen with similar microscope settings (clearly the A/pix value must be the same).
Line 152: Line 151:
 Merging the results from multiple networks on a single tomogram can help resolve ambiguities, or correct regions which were apparently misassigned. For example, in the microtubule annotation shown above, the carbon edge is falsely recognized as a microtubule. An extra neural network can be trained to  specifically recognize the carbon edge and its result can be competed against the microtubule annotation. A multi-level mask is produced after merging multiple annotation result in which the integer values in a voxel identify the type of feature the voxel contains. To merge multiple annotation results, simply run in the terminal: Merging the results from multiple networks on a single tomogram can help resolve ambiguities, or correct regions which were apparently misassigned. For example, in the microtubule annotation shown above, the carbon edge is falsely recognized as a microtubule. An extra neural network can be trained to  specifically recognize the carbon edge and its result can be competed against the microtubule annotation. A multi-level mask is produced after merging multiple annotation result in which the integer values in a voxel identify the type of feature the voxel contains. To merge multiple annotation results, simply run in the terminal:
  
-  mergetomoseg.py <annotation #1> <annotation #2> <...> --output <output mask file>+<code> 
 +mergetomoseg.py <annotation #1> <annotation #2> <...> --output <output mask file> 
 +</code>
  
 ===== Tips in selecting training samples ===== ===== Tips in selecting training samples =====
 +{{ http://blake.bcm.edu/dl/EMAN2/seg_compare.png|Good vs bad segments}}
 +
   * Annotate samples correctly, as a bad segmentation in the training set can damage the overall performance. In the microtubule case, if you annotate the spacing between microtubules, instead of the microtubules themselves (it is actually quite easy to make such mistake when annotating microtubule bundles), the neural network can behave unpredictably and sometimes just refuse to segment anything. Here is the training result on an incorrect and correct segmentation in one training set. Note the top one (22) is annotating the space between microtubules.    * Annotate samples correctly, as a bad segmentation in the training set can damage the overall performance. In the microtubule case, if you annotate the spacing between microtubules, instead of the microtubules themselves (it is actually quite easy to make such mistake when annotating microtubule bundles), the neural network can behave unpredictably and sometimes just refuse to segment anything. Here is the training result on an incorrect and correct segmentation in one training set. Note the top one (22) is annotating the space between microtubules. 
-{{attachment:seg_compare.png |Good vs bad segments |width="200"}} 
   * Make sure there are no positive samples in the negative training set. If your target feature is everywhere and it is hard to find negative regions, you can add additional positive samples which include various features other than the target feature (annotating only the target feature).    * Make sure there are no positive samples in the negative training set. If your target feature is everywhere and it is hard to find negative regions, you can add additional positive samples which include various features other than the target feature (annotating only the target feature). 
   * You can bin your tomogram differently to segment different features. Just import multiple copies of raw tomogram with different shrink factors, and unbin the segmentation using math.fft.resample processor. It is particularly useful when you have features with different lengthscales in one tomogram, and it is impossible to both fit the large features into a 64*64 box and still have the smaller features visible at the same scale.    * You can bin your tomogram differently to segment different features. Just import multiple copies of raw tomogram with different shrink factors, and unbin the segmentation using math.fft.resample processor. It is particularly useful when you have features with different lengthscales in one tomogram, and it is impossible to both fit the large features into a 64*64 box and still have the smaller features visible at the same scale. 
Line 166: Line 168:
  
 Darius Jonasch, the first user of the tomogram segmentation protocol, provided many useful advices to make the workflow user-friendly. He also wrote a tutorial of the earlier version of the protocol, on which this tutorial is based. Darius Jonasch, the first user of the tomogram segmentation protocol, provided many useful advices to make the workflow user-friendly. He also wrote a tutorial of the earlier version of the protocol, on which this tutorial is based.
- 
eman2/programs/e2tomoseg.1749927270.txt.gz · Last modified: by steveludtke