IMOD - finding round compartments
Contents
About
This page is copy of a guide I wrote for "slashsegmentation.com" at this URL:
I recommend you click the link above for the most recent information, but I have made this copy here as my own record. The page itself explains how this program I wrote can help automatically segment circular and/or spherical objects.
IMOD's "slashfindsphere" Program
The follow page explains how to use IMOD's "slashfindspheres" - a command line program that takes a small number of spheres and tries to find other spheres in the same volume which have a similar profile. To find similar sphere it uses a very basic "template matching" algorithm, where an area of pixels with similar values to the input spheres will be selected. This is a relatively crude approach, but since spheres are simple shapes it can do quite well !
Instructions
Here's a simple guide to running "slashfindspheres" in 4 easy steps:
Step 1: Install IMOD
To install IMOD go to the download's page of IMOD and follow the official IMOD installation instructions. Instead of installing the standard release however, get the latest "alpha" version of the IMOD stereology plugin by downloading the appropriate install file from this directory: "ftp://bio3d.colorado.edu/latestIMOD/alpha/" (login as guest)..... or if really keen you can copy the appropriate .csh file from the nightly build area instead.
Step 2: Open your image in IMOD's 3dmod, draw a few points and then save the model file
NOTE: To work in IMOD your image must be in MRC image file format to load, so if in some other format see the instructions here
To open your image type "3dmod" into a terminal window. In the loading window that appears, browse to your big image dataset. In the pictured example our image is called "vol.mrc". Since your dataset is (likely) too big to fit into your memory make sure you enter "1" section and tick "fill cache" at the top right. Now click okay.
When the image opens hit [Shift]+[A] to autocontrast image... and in some cases you may want to hit [F11] to invert color. We want to create a "scattered point" object, so click "Edit > Object > Type" to change your "object 1". Here you should change the object type to "scattered", give the object a sensible name, and set the object sphere size to an appropriate radius.
On the main 3dmod window click "model" mode and you are now ready to add some spheres. Use [+] / [-] to zoom in and out, and (most important) [PgUp] / [PgDown] to find change up and down slices as you try to find the center of an image. The mouse buttons can be used to pan and add points, so once you've found the center of a sphere, click the mouse to add a single point, and use the mouse scroll wheel to resize the point. If you don't have a scroll wheel click "Edit > Point > Size" and use the slider there until the radius fits the image. Repeat this process and draw about 5-10 spheres, then hit File > Save, save your model with a .mod extension (eg: "model_in.mod") and then close the model.
Step 3: Run slashfindspheres
To run "slashfindspheres" it helps to navigate to the correct directory in your Terminal window by typing "cd /full/path/to/directory/". If you are unfamiliar with Unix these instructions here can help. Once in the correct directory type the following line:
slashfindspheres vol.mrc model_in.mod model_out.mod
This line of code is the minimum you must type to run "slashfindspheres" and what it will do is use our scattered points in "volume_in.mod" to create "pixel templates" and use this to find matches, which it will add to the model and write the output as as new file called "volume_out.mod". Depending on the size of your image, and the size and number of spheres you have input, the program could take anywhere between a minute and hour to run! Fortunately it will show progress, and when it's finished you'll notice it shows a summary of how many spheres were added and also shows a line you can cut and paste to open the output volume.
Step 4: Open and refine the results in 3dmod
The quickest way you can open your output file in 3dmod cut and paste the very last line of output by slashfindspheres. The line you will cut (or can type) to open your results should look like this:
3dmod -C 1 vol.mrc model_out.mod
Once open, what you will probably see is a colorful array of new spheres. These spheres have been spread across five new objects, and the objects colored using "heatmap" colors (red,yellow,green,cyan,blue) where red representing the spheres with the best confidence, and blue represents the spheres with the least confidence. Within each object spheres are also ordered from most to least confident.
To select a particular object, contour and point, select "model" mode the use the little number boxes in the main little 3dmod window. A little yellow circle should always appear around your selected point. Since not all points will be correct, you may want to check all contours by first selecting the very last contour of the very last object, then you should zoom in with [+], then and use the [c] and [shift]+[c] keys to go to the previous/next point. For each point you can move it with the "3rd" mouse button and the numpad keys, where [9] and [3] will move the point up and down one slice. To see a "side" view it can also help to open a Slicer window, "Image > Slicer", then click the little "keep centered" icon (a box in a box) and change the X rotation to -90 to see an XZ view. You can also use the 3rd mouse button in the slicer window for even better alignment and centering the point between whole slice values. You'll probably also find you want to use the mouse-wheel to adjust the radius slightly, or you can delete a contour by hitting [shift]+[d]. Alternatively you can deleting a point with [del], and run "Edit > Object > Clean" to delete empty contours at the end. Often you'll find that the blue points are almost all wrong, so one thing you can do is actually delete that whole object by first selecting that "Object > Edit > Delete".
When you're happy that all bad points are removed, you may wish to merge all the good spheres into the original object. The easiest way to do this is open the "Name Wizard" by clicking "Special > Name Wizard". Here you will see the names of each object, including the "confidence range" values output by imodfindspheres. To merge objects, just tick all the desired objects to merge, then click "Selection > Merge Selected". A more advanced method is to click "Edit > Contour > Move" and this will bring up a dialog which lets you move a single contour at a time into any other object - something which can help you "sort" contours into their correct object in cases where you may have more than one type of spherical shaped compartment. This next image shows a good setup you can use for the "Slicer" and "Move Contour" windows which you can use to quickly adjust and move/sort points.
Looking Deeper into the Different Options
In the example above we typed the bare minimum arguments which "slashfindspheres" allows. To see a full list of arguments you can just type "slashfindspheres" to see the syntax or type "man slashfindspheres" to see a more in depth discussion of all the options. Here's a copy of the "syntax / usage" of slashfindspheres:
> imodslashspheres syntax
Usage: slashfindspheres [options] <image> <input_model> <output_model>
Options:
-o # list of scattered pt objects to use as input (eg: '1,4-5')
or enter '-o 0' for 'no object' approach... if omitted the
program uses the 1st scattered pt object in the model.
-e # list of extra scattered pt objects we don't want to overlap.
-G # # of pixels to use as a gutter around each sphere radius
when generating template to match (default: 2)
-Z # # of pixels to use as a gutter in Z (default: G/zScale)
-C # cut off for cross-correlation as a percentage (default: 80)
-R # a range of pixel values to scale the cross-correlation
-M # maximum allowed pixels for a template to span (default: 30)
-B # the number of Z slices in the 'slice buffer (default: 30)
-N # maximum number of spheres added (default: 10,000)
-x #,# limits for x
-y #,# limits for y
-z #,# limits for z (starting at 0 for first slice)
-i ignore the z axis (looks at everything in 2D only)
-d allow new spheres to duplicate/overlap input spheres
-t # test radius used to to quickly skip unlikely pixel values or
set to 0 to check every pixel in detail (default: 3)
-s # number new objects to split new spheres over (default: 10)
-m only create a single contour (with multiple points) per
object (by default is only 1 points per contour)
-c use original color of objects instead of heatmap colors
-w # write out intermediate mrc files to help see results
-p # print level where # is 0-10 -> 0 prints almost nothing
and 5 prints the most info during processing (default: 2)
-F keys ordered list of image filters to apply in the form 'm5,s'
where m5=median size 5, s=sobel, etc (see man page for all)'
(default is 'm3' but you can enter '-F 0' for no filters)
As you can see, imodslash spheres has a lot of options, including the ability to search for spheres from multitple objects at once using -o. In our example above we didn't use "-o" and so it searched for the first scattered point object, but generally speaking you should specify which object or objects you want to use as input. Here's an example which is a bit more sophisticated:
slashfindspheres -o 1 -e 2-6 -s 10 -c -F m5,s vol.mrc model_in.mod model_out.mod
In the example below we take out output from the first model, input the first object again (-o 1), but make sure we don't overlap any sphere's we've already added (-e 2-6), then we decide to output spheres into just 10 object (instead of the default five) with "-s 10" and give them all the same color as our input model with -c. Most importantly we also have used "-F m5,s" which runs a median filter then a sobel edge filter on each image slice before processing it. The sobel edge filter helps highlight edges as white and so might do a better job than before. Also notice that we have (deliberately) entered the same name for the input and output volume, meaning that out input gets "overwritten" with the new data, which can be a bit risky, but here I just wanted to show how that works.
With template matching, the trickiest part is deciding at what "cutoff" value / confidence are we getting bad negatives. By default, imodslashspheres will compare all input spheres with all other input spheres in the same object and use this to help determine a reasonable variation in confidence - hence it's a good idea to have at least 5 input spheres. If you decide to input 50 spheres, you'll probably get better results, but it may also take 10x as long, so this is a tradeoff. As you can see, there are plenty of other variables you might be able to play with, but generally speaking you'll probably find slashfindspheres will never find ALL of your spheres with 100% accuracy - you'll just have to decide on a good cutoff value, delete all the false positives and then manually add the ones which were missed.
Applying a Mask to Refine Results
In cell biology you'll expect all your vesicles or other spherical compartments to occur inside a particular cell boundary. In neuroscience, synaptic vesicles occur inside axons, transport vesicles are usually in the cytoplasm and so on. In the picture above, Chlamydia bacteria only occur in the pale "inclusion" area of the cell, but we see lots of blue and green spheres outside this area. We could go through and delete all bad ones, but since there could be thousands of these, it gets time consuming. Instead what you can do is delimit the area you need with contours then run "slashmasksort" to isolate only these contours. With "slashmasksort" your mask area must be a "closed contour" object and you must also put a contour on every slice. Since drawing a contour every slice is very slow you'll probably only want to draw every few slices and then use the Interpolation plugin ("Edit > Special > Interpolation") (see video) or mesh and then run "imodfillin" to add contours to all the slices in between. Once you have an object completely delimiting your area of interest you are ready to run slashmasksort. In the follow example lets imagine our "inclusion" area (closed contours) are object 0, and the sphere's we have generated with imodfindspheres are objects 3-7 :
slashmasksort -o 3,4,5,6,7 -m 1 -d vol.mrc model_in.mod model_out.mod
The results of this is shown below, and in this case reduced the number of spheres we need to check by over 2/3 rds. As you can see, most of these outside spheres were blue, but it's still a huge time saver, so using this program to refine your results from slashfindsphere is always worth considering - especially if you need or want to draw the bounding area anyway.
Links
- IMOD - a list of other wiki pages I've written about IMOD
- finding round compartments - same article as this one (although may be hidden).
| Acknowledgements: The SLASH team |
