sortbeadsurfs(1) sortbeadsurfs(1)NAMEsortbeadsurfs - preprocess 3D model of gold bead positions for flatten- warpSYNOPSISsortbeadsurfs [options] input_model output_modelDESCRIPTIONSortbeadsurfs can be used to process two different kinds of models of the 3D positions of gold beads to make them suitable to use in Flatten- warp(1) for describing a surface to be flattened. One kind of model would be of gold positions measured directly in the tomogram, such as by Findbeads3d. Here it is essential that if the beads are on two surfaces, each surface be represented by a separate object. Sort- beadsurfs uses the same routine that Tiltalign does to sort the beads into two objects. The second kind of model is the one produced by Tiltalign of the fiducial positions in 3D. Here it is essential that the model be tilted around the X axis by the X axis tilt used to generate the tomogram, that its X and Y coordinates be shifted and/or scaled as appropriate to match the final tomogram, and that the points are in only one object for each surface. If you have a model from Findbead3d(1), you should first edit it to remove points that are obviously not on the surfaces. (Flattenwarp has an option for removing more subtle outlying points, but it is best to get rid of the obvious points beforehand.) Then run this program on the model. Examine the output model to make sure points have been sorted correctly between the two surfaces. If not, and if the failure is because the surface is too warped to analyze all at once, then try the -subarea option to analyze the beads in subareas. If subareas are not suitable, you may have to edit the model to fix errors. Each point in the output model is a separate contour, so it is possible to click on points with the third mouse button in the model view window to select them, and use the Edit_contour-Move dialog to move the points to the right object. If you have a model from Tiltalign, you should run this program on it to apply the X axis tilt that was used when generating the tomogram. The program will attempt to sort the points into two surfaces, but if this creates a problem, use the -already option to skip the sorting if they are already sorted into two surfaces. If fiducials were tracked with multiple objects, the program automatically combines them into two objects based on the colors of the objects. If the beads are on one surface, use the -one option to skip the sorting and combine multiple objects, if any, into one object. The program has a host of options for adjusting for: a full aligned stack bigger or smaller than the original stack; binning of the prealigned stack or of the final aligned stack or tomogram; trimming of the tomogram in X or Y (or alterna- tively, generation of a tomogram that is a subarea in X and Y); or flipping by Y and Z rather than rotation around X in the trimming step. You should be able to load the resulting model on the tomogram to ver- ify that it has the right coordinates. To do so, be sure to use the -rescale option to account for any change in binning and to start 3dmod with the -m option so that it ignores previous scale informa- tion in the model. The points will not be on the right Z planes, so you will have to use the Edit-Model-Offsets dialog to shift the model in Z until it fits.OPTIONSSortbeadsurfs uses the PIP package for input exclusively (see the man- ual page for pip). The following options can be specified either as command line arguments (with the -) or one per line in a command file or parameter file (without the -). Options can be abbreviated to unique letters; the currently valid abbreviations for short names are shown in parentheses.-input(-inp)OR-InputFileFilenameInput model file with scattered points for 3D gold bead posi- tions. If this option is not entered, the first non-option argument will be used for this file.-output(-outp)OR-OutputFileFilenameOutput file for processed model or surface information If this option is not entered, the second non-option argument will be used for this file.-text(-t)OR-TextFileWithSurfacesFilenameOutput a text file with the original contour number and the top/bottom assignments (values 1 and 2) for each point. This is meant to be used by Pickbestseed, so input data should have only one object and only one point per contour.-flipyz(-f)OR-FlipYandZIntegerThis option allows control over whether the Y and Z coordinates of the model are flipped. By default, flipping will be done if the Z dimension (nz) of the modeled volume is greater than the Y dimension (ny). Enter 1 to force flipping even if this is not the case, or 0 to prevent it if this is the case.-subarea(-su)OR-SubareaSizeIntegerSize of subareas over which to analyze for two surfaces. This option is needed only if the area coated with beads is large enough and warped enough that the analysis fails to separate the two surfaces. The area occupied by beads will be divided into non-overlapping subregions of approximately the given size in each dimension. Each will be analyzed separately to sort all of the beads between the two surfaces. Make this value as large as possible, since the analysis can easily fail if there are only ~10 beads in any of the subareas.-pick(-pi)OR-PickAreasMinNumAndSizeTwointegersThe program can divide the analysis in to subareas automatically if this option is used to enter the minimum number of beads required in each area and the minimum subarea size allowed. The program will pick the smallest possible subarea size that fits these constraints.-majority(-m)OR-MajorityObjectOnlyOutput a model with only one object containing the points on the surface that has the most beads. Use this option if there are too few fiducials on one surface to fit a smooth surface to in Flattenwarp.-xaxis(-xa)OR-XAxisTiltFloatingpointThe value of X axis tilt used when the tomogram was generated. This value is needed for a 3D fiducial model output by Tiltal- ign(1) (and only for such a model).-invert(-inv)OR-InvertZAxisInvert the Z coordinates of the points so that they will match a reconstruction that was Y-Z flipped rather than rotated around the X axis. This option is needed only for a 3D fiducial model output by Tiltalign.-already(-alr)OR-AlreadySortedUse this option to skip the analysis that sorts beads between two surfaces, and combine multiple objects by color if there are any. You would use this for a 3D fiducial model from Tiltal- ign(1) if the beads are already correctly sorted into two sur- faces, or if they are on only one surface and in only one object.-one(-on)OR-OneSurfaceUse this option to skip the analysis that sorts beads between two surfaces, and to combine all points into one object. You would use this for a 3D fiducial model from Tiltalign if the beads are all on one surface but in different objects.-aligned(-ali)OR-AlignedSizeXandYTwointegersUnbinned X and Y size of the aligned stack used to make the reconstruction. Use this option if the reconstruction is based on a final aligned stack whose unbinned size is smaller or larger than that of the raw stack, and if you are processing a 3D fiducial model from Tiltalign. If the prealigned stack was binned, you must also enter the -prebin option.-xtrim(-xt)OR-XTrimStartAndEndTwointegersStarting and ending X coordinates of the aligned stack that appear in the final trimmed reconstruction, numbered from 1. See next option.-ytrim(-y)OR-YTrimStartAndEndTwointegersStarting and ending Y coordinates of the aligned stack that appear in the final trimmed reconstruction, numbered from 1. These two options are needed only for a 3D fiducial model from Tiltalign. If you built the full reconstruction (no SLICE or WIDTH and OFFSET entries to Tilt), then the coordinates for these two options are just the ones used to trim the volume with Trimvol. If you built a subset of the reconstruction, the WIDTH and OFFSET entries can be used to derive the X coordi- nates, and the SLICE entries provide the Y coordinates. If you then trimmed the volume, you need to combine the trimming coor- dinates with the one used to build the reconstruction. If you enter these coordinates, you must enter the prealigned and the aligned stack binning if either is different from one.-prebin(-pr)OR-PrealignedBinningIntegerBinning of prealigned stack used to build a 3D fiducial model. This option is needed for a binning other than 1 if you enter the aligned stack size or trimming coordinates, or if you want to rescale to the coordinates of the reconstruction.-recbin(-rec)OR-ReconstructionBinningIntegerBinning of aligned stack used to build the reconstruction. This option is needed for a 3D fiducial model if you are entering trimming coordinates or if you want to rescale coordinates to match the reconstruction.-rescale(-res)OR-RescaleByBinningsRescale the model coordinates to account for binning of the pre- aligned or final aligned stack. By default output coordinates will still have the scaling of the prealigned stack; use this option to rescale them so that they match the scaling of the reconstruction.-check(-c)OR-CheckExistingGroupsCheck that the sorting is the same as in the input model, which must already have points divided into two groups. All other output is suppressed, and if the sorting matches the program just exits with 0 status; if there is a mismatch it prints the number of incorrect points and exits with an error status.-values(-v)OR-ValuesToRestrainSortingIntegerUse the general values of the points or contours in the model to identify a fraction of points as outliers that should be excluded from the initial pairing of points at steep angles to each other. Enter 1 to exclude points with particularly high values (e.g., for mean residual values from Beadtrack), or -1 to exclude points with low values (e.g., for peak values from imodFindBeads(1)).-outlier(-outl)OR-OutlierCriterionDeviationFloatingpointWhen the -values option is entered, the values of points are analyzed to determine the normalized median absolute deviation (MADN) from the median value. Points with an absolute deviation from the median bigger than a criterion times the MADN are iden- tified as outliers and excluded from initial pairing. Use this option to change the criterion, whose default is 2.24.-set(-se)OR-SetSurfaceSortParamTwofloatsSet one parameter specified by the first number to the value specified by the second number in the surfaceSort routine. See the library documentation of surfaceSort (in libcfshr - "Other utilty functions") for an explanation and a list of the parame- ters. To set the verbose level, use "-set 13,1" or "-set 13,2". (Successive entries accumulate)-help(-h)OR-usagePrint help output.-StandardInputRead parameter entries from standard input.HISTORYAdded to IMOD, 12/6/09BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.9.3 sortbeadsurfs(1)