Stereology Plugin Help

--------------------------

The IMOD Stereology plugin provides an interface for performing rapid stereology on tomographic volumes and/or stacks of images. To achieve this, the Stereology plugin allows you to customize and project a set of grid over desired sections. There are a dozen different types of grids to choose from, including grids appropriate for volume density, surface area density, length and number density. Point counting stereology is often a process where points are manually counted and recorded on paper. The Stereology plugin takes this a step further by allowing you to setup a list of categories, and then set each points as belonging to one (or in some cases more) categories... and take care of the counting for you by generating the numbers at the end. Points in different categories are marked in different colors and saved into special labelled "STEREOLOGY" objects within the imod model file - so that the user can come back to these models later to check points and/or add points to the grid. To further speedup the process of counting points, faster than is possible with manual counting/recording of points, the plugin allows you to classify points using shortcut keys, navigate the grid with arrow keys and also has a special "Point Painter" where you can quickly paint regions of points a particular color. In addition to this you can apply "rules" or use closed contours to apply "masks" change the value of multiple points or automatically add "interception points" for estimating surface area with test lines. Although not originally designed for stereology, the advantages of using IMOD's 3dmod interface to segment perform stereology is that 3dmod has a great set of tools for viewing and navigating 3D images and you are able to show and perform surface segmentation and point counting within the same model. Before using this tool however, you should make sure you understand the Basics of Stereology (click to read). The Stereology plugin specializes in point counting stereology, but if used wisely, can also project different types of grids and be used for estimating surface area by the number of times membranes intersect vertical lines. On this page we focus on the plugin itself.

Hot Key Summary
---------------------

[1]-[9]

Apply corresponding category to currently selected point or - if "Pt Painter" selected - to all point in paint radius

[arrow keys]

Navigate the grid by moving the currently selected point [left], [right], [up] and [down]. If you hold [shift], the left and right keys will skip any checked points, and the up/down arrows will take you to the next/previous grid.

[,]

Go to previous grid

[.]

Go to next grid

[tab]

Select the very first unchecked point in the grids.

[enter]

Jump to the next unchecked point in the grid (equivalent of pressing "Next" button).

[space]

Toggle wether the currently selected point is checked.

[b]

Jump to the first invalid point in the grid.

[mouse wheel]

Adjust the size/radius of the point painter (used to quickly classify regions of points).

[w]

Increase size of point painter circle.

[q]

Decrease size of point painter circle.

How it Works
--------------------------
When this plugin is first launched (via: Special > Stereology) it starts by
checking for any "STEREOLOGY" objects already setup in the model.
If none are found it prompts the user to setup the grid and then setup and "Finalize" two or more different "categories". Once the user hits okay new
objects will be setup and named as per this example:

NOTE: This first object, starting "STEREOLOGY.SETTINGS" represents the grid settings and keeps track of "checked" points. In this case the object's label (something generally hidden from the user) tells the plugin to setup a grid with 50x50 pixel squares (the x and y spacing) on every 5th section (the z spacing)... starting on the 10th section and going to up to section 190. Grid lines/points are placed between the x and y min and max values shown.

NOTHING. #(STEREOLOGY)#grid_set=1#

Nucleus. #(STEREOLOGY)#grid_set=1#

Mitochondrion. #(STEREOLOGY)#grid_set=1#

Vesicle. #(STEREOLOGY)#grid_set=1#

And each label will match..

NOTE: All objects containing "(STEREOLOGY)" in their label represent a "category" and store the points in that category. For example, the last object ("Vesicle") is most likely used to mark any points falling in vesicles, and each stereology point which is inside a vesicle will be represented as a contour point in this object. Notice also that all these objects are in "grid_set=1", which ties them to the "STEREOLOGY.SETTINGS" object. It is thus possible to have multiple grids per model file, although in most cases you'll only want or need one.

All of these objects are set to scattered points with a single contour.

The "STEREOLOGY.SETTINGS" object is the most important one - and it's
label contains/stores instructions about how the grid is setup.
As the user click "Next" to go to a new points, the ZAP window jumps to
center on the next "unchecked" position in the grid (left to right then down)
and a point is added to the "STEREOLOGY.SETTINGS" object. The number of points
in "STEREOLOGY.SETTINGS" is thus is equal to the the number of points the user has gone though.

The "(STEREOLOGY)" objects each represent a "category" and each is tied
to the "STEREOLOGY.SETTING" by their "grid_set" id. As each point is selected
the user can then use shortcut keys [1]-[9] or click the appropriate buttons
to select what category each point is in, and it it will advance to the next.
Each time a category is "assigned" to a point, that point is added to the
corresponding object... hence the number of points in each object corresponds
to the point in that category.

By default, each point should be assigned one and ONLY one category,
however when the user clicks "Finalize Categories" there is an option to "allow point
to be assigned multiple categories". Another option sometimes presented during this finalize step is "allow intercepts" whereby, the user can enter a "Intercept" mode and draw points wherever their surface of interest intercepts test lines. If either of these
options are chosen the string "multi_cats" or "allow_intercepts" will be included
in the label of the "STEREOLOGY.SETTINGS" object.

NOTE: By default each object has is points represented with spheres, however it possible to go "Edit > Object > Type" to change sphere size and the representation of points in each object/category.
As for the grid display: the "Grid Setup" tab contains a couple of options
to change the way the grid is drawn, but many more options can be found under "Options > Display Options" and under "Options > Grid Settings" you can change several other grid-related values including the default values used to set up new grids.

This plugin relies heavily on object labels to store grid parameters because, unlike object names, they are fairly hidden from the user and thus hard to accidentally change or delete outside of the plugin. To see and/or modify the object labels you can use "Options > Modify grid settings/labels". Ideally you should get your grid settings right the first time (before you click "Finalize"), but if you do decide you suddenly want/need a finer grid the safest option is to "override" values in the label by changing the object's name. In the example above, the user could halve the spacing of points in x and change the grid type to lines and by renaming the grid setting object to: "STEREOLOGY.SETTINGS #grid_set=1#type=lines#xspacing=25#" and then would click "Options > Load/reload grid from model" to make these changes take effect - and hopefully the points he has marked up will still be loaded (since he has exactly halved the spacing). If the user then deleted the changes and/or the whole object name and reloaded it again, the original grid settings (when the user clicked "Finalize Categories") should be restored.

Saving/Loading a List of Categories
---------------------
"Options > Settings", however lists of categories must be loaded and saved via a special comma separated value (csv) text file. Whenever you start a new grid, the default set of categories is loaded from the following location:

The "IMOD_PLUGIN_DIR":
"$IMOD_DIR/lib/imodplug/standard_names.csv"

This folder is typically found under "/Applications/IMOD/lib/..." on Mac or "C:/cygwin/usr/local/IMOD/lib/..." on Windows. The format for this file is:

This file format is based on the same "standard names and colors csv file" format used by the "Name Wizard" plugin, which you can read about here. Used in the "Stereology" plugin the category name is entered into the first field, the red, and blue values are entered as integers between 0 and 255 into the next three fields, and the last two field (specific to this plugin) can be used to store the sphere size in pixels and line width in pixels. Notice that commas delimit the separation between each field. If you chose to edit one of these files manually by a spreadsheet or text edit application you can add a hyperlink and description of the category, but make sure you save in Windows .csv format and use commas correctly. The safer option is to click the little down arrow below the category list (available only before you click "Finalize") and here you have options to save the current list of categories to file... or load a different set of categories from file.

Types of Grids
---------------------

The very first option in the "Grid Setup" tab is to select a "grid type". It's a good idea to understand what each of these grids is useful for:

lines - show all horizontal and vertical grid lines... use this for VOLUME estimates over large areas.

crosshairs - show a small crosshair over every stereology point.. recommended for VOLUME estimates using <10,000 points.

arrows - show a tiny arrow over every point... same as above, but using tiny arrows, not crosshairs.

off pts - shows points which are offset/staggered every second row... similar to above but maximizes distance between points.

rand - allows you to randomly add any number of points to your grid... use this for quick-and-dirty VOLUME estimates - this is not a standard or reproducible stereology method.

vert lines - show vertical grid lines only... use this for SURFACE AREA estimations, but tallying the number of intersecting lines/membranes per line.

diag up - projects diagonal lines which slope upward to the right and slope can be adjusted by adjusting with x and y spacing separately... similar effect as above.

diag down - projects diagonal lines which slope down to the right... same idea as above.

line pairs - spaced out horz lines staggered on alternate rows... a popular stereology technique for estimating SURFACE AREA by the number of intersections per line.

cycloids - evenly spaced cycloid lines which are distorted by the values of x and y spacing... used for SURFACE AREA estimation and by using these curves instead of straight lines can help capture more intersections.

cycloids alt - as above, but with every second cycloid facing down ("alternating") ... similar to above.

cycloids long - shows continuous cycloid lines and, unlike above options, these are true cycloids in that they are not stretched or squashed by any y spacing value... can be used in LENGTH estimation of string like filaments, but only if you know what you're doing.

rectangles 1:2 - projects rectangles which are half the length of the x and y spacing respectively... possible to use for NUMBER estimation (number of surfaces per volume), but preferred method is to use forbidden squares.

forbidden squares1:2 - shows special 'forbidden squares' structures used for counting surfaces per area. The side of each square is set to half the x spacing or y spacing - whichever is shorter.

forbidden squares 1:4 - as above, but side length 1/4 of minimum spacing.

forbidden squares 1:8 - as above, but side length 1/8 of minimum spacing.

none - shows no grid.... an option you may want to chose if you have turned on "subsample rectangles" and are using these as custom sized forbidden squares.

Notice that the first four grid types are used for estimating VOLUME DENSITY (VV) using "point counting stereology". If you choose one of these techniques you should setup each category representing a different type of structure and each point should be classified into one of these categories. The "rand" option is quite unique in that it is not really a grid. If you choose this option you will have to click the "Random Pts+" button to generate as many randomly positioned points as you want. The advantage of this is you can add as many points as you want, but the disadvantage is that it's not a "supported" stereology technique - it's impossible to reproduce or write up in a paper.

The next several grid types (vert lines, cycloids) should be used for estimating SURFACE AREA DENSITY (SV) . If you choose one of these techniques you should setup categories differently.... and the easiest method is to let the plugin add as categories: "0.INTERSECTIONS", "1.INTERSECTIONS", "2.INTERSECTIONS" etc. Using this system you can quickly click the matching number keys [0]-[9] to show how many times each "test line" is intersected by the edge of a particular type of surface. If the test line doesn't touch any surface you should choose [0]. If you want to count intersections for more than one type of surface at once an alternative approach is to setup categories as normal (eg: "NOTHING", "MITOCHODRION, "VESICLE", etc) and make sure you tick the "allow intersections" options when you click "Finalize Categories". This option enables an "Intercept" mode button which, when selected, allows you to click points along each test line which intercept each surface type, and use the numbers to change/add points in the different categories.

The final few grid types (rectangles and forbidden squares) can be used for estimating NUMBER DENSITY (SN) . In the forbidden squares system, the number of surfaces in each square are counted, but any surface touching the solid lines (along the left side and bottom) should be omitted - if a surface touches the dotted line (but not the solid line) it should be counted and also counted if it's completely inside the box without touching any lines. This system is specially setup such that even if all your forbidden squares were touching, you wouldn't double count any surfaces. If you want to setup a custom size for forbidden squares, you should tick the "subsample" rectangles option in the "Grid Setup" tab and will probably want to check "show grid on every slice" if using the 3D "Physical Dissector" method to count the number of surfaces in a 3D volume (instead of 2D plane).

Please note that for both surface area and number measurements, it's important you setup the right pixel size and units under "Edit > Model > Header" - so that the scale of the image is known and thus you can get a measure for SV or SN. When you click "Options > Calculate Results", the plugin should detect this and, if your categories are labelled "1.INTERSECTIONS", "2.INTERSECTIONS" etc, should add the total number of intersections appropriately. If you've used the "allow intercepts" approach it should just add the number of points in that category... or you can do this yourself using the main 3dmod window to see how many points are in each object.

Options
---------------------

In addition to the options on the main Stereology plugin interface, a large number of
additional tools are available when you click the "Options" button.
A small description of each is written below.

Set/view grid spacing in units - Allows you to view and/or set grid spacing in whatever metric unit is specified in the model header (typically 'nm').

Load/reload grid from model - Will search the currently open IMOD model for 'STEREOLOGY' objects and if it find any, gives you options to load the grid settings, categories and points from one of these grids.

Start new grid (wizard) - Allows you to start a new grid using a wizard to decide what type of grid and method you want to use.

Modify grid settings/labels - Allows you to modify a grid which has already been finalized by changing object labels.... something you should ONLY do if you have read the documentation and know what you're doing.
--

Apply (contour) mask to points - Allows you to change the classification of stereology points inside and/or outside a set of closed contour within a closed (non-stereology) object.

Apply batch mask to points - Allows you to change the classification of all stereology stereology points inside several (closed contour) objects at once. Unlike the option above, this function checks for contour 'holes' (contours inside contours), but has far fewer options and assumes that each point should have only one category.

Change point values - Allows you to apply a set of *rules* to change the classification of points which meet a set criteria. As one example: you could change only unchecked points on the current grid/section to be category 1 and checked.

Validate point values - Will validate your grid points by finding any unchecked points without a category, or points with more than one category (in cases where the "allow multiple categories" option was not checked).
--

Check progress - Quickly shows how many points you have checked and how many points fall in each category.

Calculate results! - Calculates and outputs results from your selected point-counting stereology grids. Results can be output in various formats for easy copy and paste easily into a spreadsheet, and you can also choose to omit certain points and/or categories from calculation.
--

This plugin was created by Andrew Noske (andrew.noske<at>gmail<dot>com).

If you encounter bugs please e-mail me before e-mailing the
IMOD group (to reduce traffic).
In your e-mail please tell me exactly how and when the problem
occurred and attach the model file you were using with
enough information that I can replicate the error/crash.

NOTE: This plugin is now part of the is part of the
"SLASH segmententation"
initiative. Please contact me for citation information.

Acknowledgements:Mark Ellisman and The National Center for
Microscopy and Imaging Research (www.ncmir.ucsd.edu) for helping sponsor
and encourage this work. Guy Perkins,Eric Bushong and Keun-Young Kim (Christine) from my lab for helping advocate and beta test this plugin. David Mastronarde and the team at The Boulder Lab for 3-D Electron Microscopy
(bio3d.colorado.edu) for their wonderful support of all my plugins.