slashfindspheres(1)                                        slashfindspheres(1)



NAME
       slashfindspheres - Inputs spheres from one or more scattered point
       objects and outputs new spheres with similar pixel values (useful for
       small vesicles).

SYNOPSIS
       slashfindspheres  [options]  image_file input_model  output_model

DESCRIPTION
       Uses a simple template matching algorithm to try to finding non-over-
       lapping sphere-shaped objects within the specified MRC image volume,
       and then outputting them as scattered point/spheres to a number of new
       objects in the output model.  Examples of such "sphere-shaped" objects
       in cellular data can include: vesicles, ribosomes, nucleus (if they are
       small and round enough) and gold fiducial particles.

       Before running this program, you should first open the MRC file and
       create a model with at least one "scattered point" object (lets say
       object 1) containing around 5-50 spheres - i.e. points which are cen-
       tered on the center of desired objects and have their radius resized to
       the correct amount using "Edit > Point > Size". You can then run this
       program with:
        "slashfindspheres -o 1 your_mrc_file.mrc your_input_model.mod
       your_output_model.mod"

       When run in this way, the computer stores a 3D area around, and a few
       "gutter" pixels beyond the limits of each sphere and uses these as a
       "template" in a template matching algorithm where each pixel of the
       input image is considered and it's immediate 3D pixel area is compared
       against each template/input sphere to determine which matches best. If
       the best match has a similarity is above a sensible "cutoff" threshold
       (-C), the pixel will be regarded a "candidate" sphere with the same
       radius as the best-matching input sphere. Since this algorithm will
       often yield many candidates in "likely areas" the final pass is to
       eliminate any candidate spheres that overlap a candidate sphere with a
       higher confidence, or if it overlap one of the input spheres or any of
       the spheres in the "extra" objects list (-e).

       By default, up to 10,000 candidate spheres will be output to 5 new
       objects - although these values can be changed easily with -N and -s
       respectively (see below). Objects are colored with heat-map colors
       {red-yellow-green-aqua-blue} from most to least confidence, as
       reflected by the object names, and within the objects the output
       spheres are ordered with the most confident spheres first. After out-
       putting spheres you can open in 3dmod and check them by selecting the
       very last point and hitting they that don't match. Separating them into
       many objects can also help delete large number of bad points at once.


OPTIONS
       -o #/list
              A list of objects to use as "input spheres" (eg: "-o 1,2,4-6").
              These objects should all be scattered point object and contain
              on the order of 5-20 points/spheres representing the spherical
              compartments you want segmented. An 3D area around each pixel in
              the model will be compared against all these input spheres to
              see which sphere (if any) is most similar, and then this point
              will adopt the same radius.  If no list is specified, the pro-
              gram will try to use the first scattered point object in the
              model.

       -e #/list
              A list of "extra" objects which we don't our output spheres to
              overlap. Unlike the input object list, this list can include
              non-scattered point objects (i.e. closed and open contour
              objects) and considers all points in these objects regardless of
              whether they have a sphere size. The program will reject any
              candidate sphere which overlaps any point in these objects. When
              running the program multiple times to find additional spheres,
              you should use this option to make sure the same spheres are not
              segmented again and again. Objects in the input list don't need
              to be included as the program already rejects spheres that over-
              lap these regions, but listing them again here doesn't hurt
              either.  If "-e 0" is entered then ALL objects wil listed (to
              ensure no overlaps).

       -G #   Represents the number of pixels to use as a "gutter" around each
              sphere when generating a template to match. In addition to the
              pixels inside a points radius, pixels in this gutter region are
              also evaluated and since this region is usually where the pixel
              intensities change (eg: just outside the spheres edge it proba-
              bly turns light or dark) it's important to choose a good value.
              The default value is 2, but if you have large spheres (eg: 50
              pixels across) and/or have many pixels of "empty/consistent
              space" outside your radius then you should probably increase
              this value. Lower gutter sizes will likely return more matches.
              As an extreme example: if your gutter was 0 and you were search-
              ing for little black spheres on a white background this program
              is likely to think all the pixels in a huge huge black blob/tube
              match perfectly and thus represent the center of a sphere.
                (default: 2)

       -Z #   Represents the number of pixels to use as a gutter in the Z
              axis. The default value for this is this "z gutter" value is the
              -G (normal gutter) value divided by the input model's z scale
              (under Model > Header). In most electron microscopy volumes (ET,
              SBFSEM, etc) the Z resolution is poorer than X and Y, so it
              makes sense that this value is much lower than -G. In cases
              where X, Y and Z all have the same pixel size, however, the two
              values should be the same.
                (default: G/zScale)

       -C #   Cut off value for cross-correlation, which you can enter as a
              percentage (eg: 80 = 80%).  This "cut-off" value dictates how
              similar a sphere must be to an input sphere (where 100%=identi-
              cal) to be counted. By default, the cutoff value will be deter-
              mined by comparing the similarity between input spheres and
              printed out in results.  A suitable cut-off value will differ
              from image to image to differences in intensities, contrast and
              so on.

       -R #   A range of pixel values by which to scale cross-correlation mea-
              surements. By default this value will get sent to the difference
              between the minimum and maximum pixel value in the image, which
              is typically some number less than 255 and usually a good value
              to use as a measuring stick for deviation.

       -M #   The maximum number of pixels a template will span - meaning any
              pixels outside this diameter will not be included.
                (default value: 30)

       -B #   The maximum number of Z slices to keep in the 'slice buffer' at
              once. The higher this number, the less 'reloads' will be neces-
              sary (meaning faster processing), but if this value is too high
              will take up far more memory and either cause a slow down or a
              crash / segmentation fault if it can't all fit in memory.
                (default value: 30)

       -N #   Maximum number of spheres to add. Since the cutoff value can be
              difficult to estimate this value can be used to help ensure you
              don't add way more spheres than you expect to see in your model.
                (default: 10,000)


       -x #,# Minimum and maximum limit in the X axis of your image to search
              for the center of a sphere. The -x, -y and -z arguments below
              can be used to reduce the search to a sub-volume in each dimen-
              sions. If omitted, all pixels in the image are searched.

       -y #,# Min and max limit in X axis of your image to search for the cen-
              ter of a sphere.
                (example: "-y 0,2000")

       -z #,# Min and max slice or "Z limit" of your image to search for the
              center of a sphere, where 1 represents the bottom-most slice.
              When first running slashfindspheres, it can be helpful to start
              with a small z range to see fast results and decide if you want
              to then run your parameters over the whole image.
                (example: "-z 1,10")


       -i     If entered, the program will "ignore" the z axis and search
              everything in 2D only.  In other words, it will treat each slice
              separately and look for "circle" profiles instead of spheres,
              although can still be surprisingly effective at finding spheres
              as candidate spheres which overlap spheres with higher confi-
              dence still get removed.

       -d     If entered, "duplicate" or overlapping spheres are allowed. In
              other words, "candidate spheres" are not checked to see if they
              overlap input spheres, but are still checked against each other
              and against any "extra" spheres in "-e".

       -t #   A "test radius" used for "early rejection" - a feature used to
              quickly skip pixels which look unlikely to match any of your
              input spheres. This value is 3 by default, meaning that an area
              of 6x6 (on the current slice only) pixels around each pixel is
              averaged together and checked that it has similar intensity to
              the 6x6 areas of the input spheres. What this means is that if
              all your input spheres have dark centers, then areas of light
              pixels will get skipped over quickly without comparing a 3D vol-
              ume of image against all input spheres. To check all pixels you
              can enter "-t 0", but be warned that it will then take much
              longer to process!
                (default: 3)


       -s #   The number of new objects to split new spheres over. Objects
              are, by default, colored using a heat-map color gradient with
              the following colors representing from most to least confident:
              red, yellow, green, aqua, blue. The name of each object will
              also show name of the input object followed by the confidence
              range the object represents. Within the object, spheres are also
              ordered by confidence with contour 1 point 1 being the most con-
              fident.

       -m     Allow "multiple points per contour" such that each new object
              will only have a single contour containing all points. By
              default, there is only point per contour only, making it easier
              in 3dmod to use the Edit >> Contour >> Move dialog to move
              points between objects.

       -c     New objects will be given the same color as the original object
              (from the -o list).  By default, new objects get given "heap-
              map" gradient colors starting at red for most confident then
              progressing through yellow, green, cyan and blue.

       -w #   Write out an intermediate MRC files reflecting confidence value.
              If filters were applied then the result of these filters will
              appear in a second MRC file.

       -p #   Represent a "print level" where the # is 0-10. A '-p 0' prints
              almost nothing while values of 5 will show a lot of output
              information to help in any confusing or debugging situation.
                (default: 2)

       -F keys
              An ordered list of image filters applied in the form 'm5,s'
              where:
               > 0  = no filters
               > m# = median filter of size #
               > s  = sobel edge filter  (useful to highlight the edges around
                      spheres as light)
               > p  = prewitt edge filter (very similar to above)

              The default value is 'm3' - for a single found of median filter,
              but if you want no filters you can enter '-F 0'. Depending on
              the complexity of other structures inside you image the sobel
              filter can be very helpful and you can always type significantly
              increase accuracy, but is generally slower, not because the fil-
              ter takes long, but because far fewer pixels will be subject to
              early rejection (see -t).



AUTHORS
       Andrew Noske and David Mastronarde

SEE ALSO
       imodfindbeads

BUGS
       Email bug reports to mast at colorado dot edu, and CC to
       andrew<DOT>noske<AT>gmail<DOT>com.



IMOD                                 4.9.5                 slashfindspheres(1)