Content-type: text/html Manpage of PEET

PEET

Section: User Commands (1)
Index Return to Main Contents
 

NAME

PEET - Particle Estimation for Electron Tomography  

SYNOPSIS

A set of programs for aligning and averaging 3D volumes.  

DESCRIPTION

Most programs take a parameter file as their first argument. The parameter file is a MATLAB readable text file that specifies the parameter values in MATLAB syntax. See below for a description of common parameter options and syntax. Additional, program-specific parameters are described on the individual program's man pages. Sample parameter files are available in $PARTICLE_DIR/templates.  

PARAMETER FILE OPTIONS

alignedBaseName = string
The basename for the aligned particle MRC files (default: '').
CCMode = int
The cross correlation measure to use:
0: Local energy normalized cross correlation - a less accurate approximation to normalized cross-correlation. tiltRange and flgWedgeWeight will be ignored.
1: True local correlation coefficient, aka normalized cross-correlation (default). CCMode=1 is required for missing wedge compensation during averaging and alignment.
cylinderHeight = nonnegative number or NaN (default)
The mask height in voxels when maskType is "cylinder".
debugLevel = int
How much debugging information to print <0|1|2|3>
0 - no debug text
1 - general function level messages
2 - particle level messages
3 - rotation angle level messages% (default: 0).
duplicateAngularTolerance = array of integers
The maximum angle in degrees between orientations at which particles can be considered duplicates at each iteration.
duplicateShiftTolerance = array of integers
The maximum X, Y, and Z distances in pixels at which particles can be considered 'duplicates' at each iteration. The same tolerance is applied separately to X, Y, and Z in tomogram coordinates. I.e. the region in which a particle may be considered a duplicate is a cube rather than a sphere.
dPhi
dTheta
dPsi = cell array of floating point vectors
Angular search intervals in degrees for each of the three rotation angles Phi, Theta, and Psi used for the alignment search. Phi is the rotation around the particle's Y axis, determined by the parameter "yaxisType", above. Corresponding X and Z axes are deduced from the Y axis to define a right-handed coordinate system. Theta and Psi are rotations around the particle's Z and X axes, respectively. For example,
dPhi = {[-12:3:12], [-6:2:6], [-3:1:3]}
dTheta = {[-12:3:12], [-6:2:6], [-3:1:3]}
dPsi = {[0], [0], [0]}
will specify three iterations with the given search ranges.
edgeShift = int
The number of pixels to shift the edge of the wedge mask to ensure that all of the frequency information is included (default: 0).
flgAbsValue = < 0 | 1 >
If 1 (default), maximize the absolute value of the cross-correlation during alignment, rather than the raw cross-correlation. Use of the absolute value reduces the chance of pure noise reinforcing to match the reference, but can prevent proper alignment of some highly repetitive patterns (e.g. checkerboard or zebra stripe patterns) in which in which in- and out-of-phase alignments become indistinguishable.
flgFairReference = < 0 | 1 >
If 0 or omitted, use either a single-particle or a user-supplied volume as the initial reference, depending the reference settting, below. If 1, construct a multi-particle reference.
flgFRM = < 0 | 1 > or array of zeros and one
0 disables and 1 enables use of fast rotational matching. (DEFAULT = 1). Either a single value, to be applied globally, or a value for each iteration can be specified. If enabled, fast rotational matching may be used (at PEET's discretion) for rotation-only searches.
flgNormalize = < 0 | 1 >
If 1, adjust individual subvolumes to zero-mean and unit variance prior to averaging, clustering, or calculating variance maps or resolution estimates. The default (0) is to use the original, unscaled subvolumes.
flgNoCleanupOutputFiles = < 0 | 1 >
To avoid possible confusion, PEET deletes previous output files (with 1 level of backup) at the start of each new run. To suppress this behavior, set flgNoCleanupOutputFiles = 1.
flgNoReferenceRefinement = < 0 | 1 >
If 1, use the initial reference for all iterations. If 0 (the default), a refined estimate of the the reference will be generated at each iteration.
flgRandomize = < 0 | 1 >
By default,PEET preferentially selects subvolumes with higher cross-correlation score for inclusion in averages, etc. Setting flgRandomize to 1 disables this preference and selects particles pseudo-randomly. Note that randomized particle selection disables missing wedge compensation during alignment.
flgRemoveDuplicates = < 0 | 1 >
If 1 (default: 0), search for any duplicate particles after each round of alignment, and remove them from further consideration. Two particles will be considered duplicates only if their separation exceeds neither duplicateShiftTolerance nor duplicateAngularTolerance (see above). Particles removed as duplicates will be assigned to the the duplicate class (ID -9999). AverageAll and calcSSNR ignore members of this class when flgRemoveDuplicates is set. CalcFSC does also, unless -9999 is explicitly added to selectClassID. PEET stores particle class in column 20 of the motive list, with a default of 0.
flgStrictSearchLimits = < 0 | 1 >
If 1, enforce strict limits on rotations and shifts resulting from alignment search. E.g. suppose the search radii were 10, 5, and 2 for iterations 1, 2, and 3. If flgStrictSearchLimits is 0 (and always, prior to 1.8.0), an maximum translational shift of 10 + 5 + 2 = 17 could result in each tomogram coordinate. If flgStrictSearchLimits is 1, shifts larger than max(10, 5, 2) = 10 are disallowed and ignored. Similar limits apply to angular searches.
flgVolNamesAreTemplates = < 0 | 1 >
When set to 1, entries in fnVolume, fnModParticle, initMOTL and tiltRange will be (optionally) interpreted as "templates" to be automatically expanded rather than individual filenames.

For example, when working with many sequentially-numbered, similarly-named volumes in the same directory, it can be inconvenient to create separate entries for each. E.g., this occurs when working with previously boxed-out particles or small subregions of a larger volume. Given myVol1.rec, myVol2.rec .. mvVol99.rec in directory ../dirA and m yVol001.rec .. myVol999 in ../dirB you could set flgVolNamesAreTemplates=1 and

fnVolume = {'../dirA/myVol1-99.rec', '../dirB/myVol001-999'}.

(Note the use of leading zeros in the 2nd case).

Another situation where templates can be helpful is when it is desired to apply multiple initial motive lists to copies of the same volume... e.g. during symmetrization.

Templates must end in <start number>-<stop number> followed by an optional suffix. Conversely, when flgVolNamesAreTemplates is true, filenames for which template expansion is not desired must not end in <start-number>-<stop number>.<suffix>. Templates can be used for initMOTL and tiltRange only when using external files as initial motive lists and wedge masks, respectively. Corresponding templated entries must all expand to the same number of entries. (E.g. you can not use fnVolume = ['v1-10.mrc'] in conjunction with fnModParticle = ['m1-20.mrc'], since the former expands to 10 volumes and the latter to 20 models). Non-template entries will be taken as as applying to each expanded template.

When using templated names in conjunction with a single particle reference, the volume and particle numbers used to specify the reference refer to actual (expanded) volumes rather than templates.

flgWedgeWeight = < 0 | 1 >
Apply missing wedge compensation to the alignment search (default: 0). This option takes effect only when CCMode=1.
0: do not apply missing wedge compensation during alignment.
1: apply missing wedge compensation during alignment.
fnModParticle = string cell array
The file names of the IMOD model files indicating approximate locations of the centers of the particles / subvolumes to be aligned and averaged.
fnOutput = string
The base name of the output files for the average volumes, the reference volumes, and the transformation parameters,
fnVolume = string cell array
The file names of the MRC image volumes containing the particles.
initMOTL = < string cell array | int >
A cell array of strings specifying the filenames of the initial alignments (motive lists) loaded to start the alignment search or an integer code specifying how to create the initial alignment (default: 0):
0: Set all rotational values to zero
1: Use particle and reference model points to initialize rotation around the particle's Z axis.
2: Use particle and reference model points to initialize rotations around the particle's X and Z axes.
3: Uniform random rotations.
4: Random axial rotations.
insideMaskRadius = < float >
Voxels of the reference volume residing inside this radius will be masked out.
lstFlagAllTom = < 0 | 1 >
Specify how to generate the average volume.
0: use equal number of particles from each tomogram, if possible. (Unequal numbers can still be used, if necessary to achieve the requested number of particles).
1: use particles with best correlation scores among all particles from all tomograms.
lowCutoff, hiCutoff = < cell array of floats or float arrays >
The frequency domain cutoff parameters for prefiltering the particles and reference, in cycles/pixel. lowCutoff <= 0 prevents low frequency filtering, hiCutoff >= 0.866 prevents high frequency filtering. An optional second parameter defines the transition width of the respective filter. The cell array will specify unique values for each iteration.
lstThresholds = integer vector
The list of thresholds to use for computing the final volumes. An average volume is generated for each value in this vector. The format of the average volume file name is

fnOutput_AvgVol_##P###.mrc.

where ## is the iteration number and ### is the number of particles included. The number of particles will have leading zeros so that all filenames will have the same number of digits.

maskModelPts = [Z Y]
Allow manual specification of cylindrical mask orientation. Z and Y are Slicer angles specifying rotations in integer degrees around the tomogram Z- and Y- axes. These rotation (1st Z, then Y) will be applied to an initial vector along the Y-axis. If empty PEET will attempt to choose an appropriate axis automatically. This parameter has no effect unless cylindrical masking is in use.
maskType = < 'none' | 'sphere' | 'cylinder' | filename >
A string specifying a mask type or a filename of a user-supplied mask volume in MRC format.

none: do not use any masking.

sphere: use a spherical mask centering at the reference volume. The inside of the reference volume specified by option insideMaskRadius will be masked out. The outside of the reference volume specified by option outsideMaskRadius will also be masked out.

cylinder: use a cylindrical mask centering at the reference volume. The inside of the reference volume specified by option insideMaskRadius will be masked out. The outside of the reference volume specified by option outsideMaskRadius will also be masked out. By default, the cylinder's axis will be oriented along the reference particle's Y axis.

filename: use the volume specified by the filename to mask the reference. A voxel of reference volume is masked out if the value of its corresponding voxel in the mask is zero. The dimensions of the mask volume can be smaller than the dimensions of the reference volume. In this case, voxel values outside the mask are determined by the value of the majority of 8 corner voxels of the mask. A convenient way to generate a mask is to use imod program imodmop.
maskBlurStdDev = float
If zero or missing, any PEET-generated or user supplied masks will be treated as binary... i.e. will have abrupt edges. If maskBlurStdDev is greater than zero, it specifies the standard deviation of a Gaussian with which the edge will be smoothed / convolved. The resulting smoothed mask will have a response of 0.5 at the original edge location and will require roughly 2.5 standard deviations on either side of that location to reach 99% of the max / min value. Small values of maskBlurStdDev typically suffice as a result. E.g. a value of 3.0 yields an edge which requires ~15 voxels for a complete transition, although it may appear more narrow than this by eye.
nWeightGroup = int
If greater than 1, particles will be grouped into the specified number of groups according to their missing wedge orientation. Cross-correlation scores within each group will then be scaled so that their medians match. This can help minimize bias when choosing particles to be averaged, or when computing FSC, SSNR, or variance. While the appropriate value for nWeightGroup must typically be determined empirically, higher settings typically require more particles, since 10 or more particles per group are preferred.
outsideMaskRadius = < float >
Voxels of the reference volume residing outside this radius will be masked out.
particlePerCPU = integer
How many particles to distribute to each CPU for parallel processing.
reference = < int vector | string >
Controls the initial reference particle(s) or volume

If flgFairReference is 1, an integer, k, specifying that 2^k particles should be used to generate a multi-particle reference.

If flgFairReference is 0 or omitted, either:

a vector of 2 integers, specifying the model number and the index within that model, respectively, of the particle to be used as an initial reference. If using templated volume names (see flgVolNamesAreTemplates above) model number refers to the number in the expanded list of models/volumes rather than in the original entries.

or

a string specifying the filename of an MRC image file to be used as the initial reference. The user is responsible for ensuring that the supplied reference is sufficiently large. Ideally the supplied volume should be a cube large enough to fully contain the particle plus twice the maximum search distance in any orientation. The Y axis of the user-supplied reference will be assumed to lie along the volume Y coordinate unless a different axis is specified in file <stripped_reference>_Axis.csv in the current project directory, where <stripped_reference> is the <reference> with any leading directories and trailing suffix removed; if present, this file should contain 3 comma-separated numbers representing the volume X, Y, and Z coordinates of the desired vector. If missing wedge compensation is desired (flgWedgeWeight = 1), the binary wedge mask corresponding to this reference should be provided in MRC file <reference>_WGT.mrc in the same directory as the user-supplied reference volume.
refFlagAllTom = < 0 | 1 >
Defines how the subsequent reference volume is generated.

0: use equal number of particles from each tomo, if possible. (Unequal numbers can still be used, if necessary to achieve the requested number of particles).

1: use particles with best correlation scores among all particles of all tomograms.
refThreshold = array of integers
Determines the number of particles used to generate the reference volume for each iteration. If >= 1, it directly specifies the number of particles. If < 1, it corresponds to a cross-correlation threshold; particles with correlation coefficients greater than or equal to this threshold will be included.
relativeOrient = cell array of float arrays (NO LONGER SUPPORTED)
Prior to 1.8.0, defined, for each tomogram, Slicer angles to be applied to all of the particles therein. As of 1.8.0, this parameter is no longer supported. Use initial motive lists instead. Programs Slicer2MOTL and modifyMotiveList can be used to construct and modify initial motive lists.
sampleInterval = < float >
Equitorial samplng interval in degrees for spherical sampling of Psi. The sampling interval will decrease at higher and lower lattitudes so that there will be only a single point at each pole. We recommend setting this parameter to match the Phi search interval. See dPhi, below.
sampleSphere = < 'none'| 'full' | 'half' >
Specify if the optimized spherical angular search should be used for the first iteration. This option only affects the first iteration.
none: Do not use optimized spherical angular search. Angular search will be controlled by parameters dPhi, dTheta, and dPsi.
full: -90 to 90 degree search in Theta, and -180 to 180 degree search in Psi.
half: -90 to 90 degree search in both Theta and Psi.
For both half- and full- spherical searches, dPhi (below) should be set from -180 to +180 degrees in steps of the desired size (typically = sampleInterval).
searchRadius = cell array of integers or integer vectors
The search range in tomogram pixels for each iteration. A single integer specifies the same search radius for X, Y, and Z. A vector of 3 integers specifies X, Y, and Z search radii separately in tomogram coordinates. E.g. searchRadius={4, 5} is equivalent to searchRadius={[4 4 4], [5 5 5]}.
szVol = integer vector
The size of the volume around each particle to excise and average [nX, nY, nZ]. Note: prior to 1.9.0 it was required that szVol be padded by at least twice the searchRadius. This is no longer necessary and not recommended. Extra padding will now impair both speed and accuracy.
tiltRange = cell array of float arrays or strings
The tilt range used to acquire each of the tomograms, [min max]. This will compensate for the missing wedge in the averages if CCMode=1, and when generating the alignment if CCMode=1 and flgWedgeWeight is 1. A cell array of strings can also be used for dual / multiple tilt axes, with each string containing the path to an appropriate binary mask file. An empty cell array, {}, specifies not to account for the missing wedge (and use more efficient space domain averaging) (default: {}).
userCommands = <string | cell array of strings>
Shell commands to be executed after each iteration. If a single string, that command will be executed after every iteration. If a cell array, the number of entires must equal the number of iterations, and the ith entry will be executed after the ith iteration. Empty strings or arrays are ignored.
yaxisType = < 0 | 1 | 2 | 3 >
An integer defines the orientation of the particle's Y axis.
0: use the original, tomogram Y axis.
1: Use the vector between adjacent model points as the Y axis.
2: use the vector between the ends of the contour containing the particle as the Y axis.
3: User-defined Y axes. Rotation axes for volume <n>will be read either from file <fnOutput>_Tom<n>_RotAxes.csv in the PEET project directory or from file <volumeName>_RotAxes.csv in the directory containing volume <n>. (The former takes precedence). The ith line of this file should contain 3 comma-separated values specifying the tomogram x, y, and z coordinates of the ith particle's rotation axis. Suitable files can be generated manually or using programs spikeInit or stalkInit.
yAxisSymmetry = array of integers
An optional array with one entry per iteration allowing imposition of axial symmetry. If the ith entry is n, where n > 1, both particles and the reference will be symmetrized before performing the ith alignment search, and the ith search will be in Phi only from -180/n to 180/n degrees in steps of dPhi. This parameter is not currently supported by the eTomo gui and must be manually entered in the prm file.
 

PARAMETER FILE SYNTAX

The parameter file is read in by the MATLAB parser and thus needs to be in MATLAB command format. This is a simple format of the form

name = value

where name specifies parameter being set and value is the value to set the parameter to. value can be an integer, floating point number, complex number, string, vector or cell array. String are constructed using single quotes. Vectors are specified by white space or comma delimited values surrounded by square brackets i.e.

[1 2 3 4:7 -2:-2:-10]

the colon operator allows for the specification of uniform sequences with the first number being the start, the second number is the step and the final number is the end value of the sequence. If there are only two numbers separated by a colon, the step is assumed to be 1. Cell arrays are similar to vectors but each element can hold a value of any type including vectors and other cell arrays. Cell arrays are specified using curly brackets, for example, a cell array can be specified by

{'string', 1, 3.4, [1 2 3], variable}  

FILES

Sample parameter files are available in $PARTICLE_DIR/templates.  

AUTHORS

Rick Gaudette
Quanren Xiong
John Heumann  

SEE ALSO

alignSubset(1), averageAll(1), calcFSC(1), calcSSNR(1), dualAxisMask(1), mergeEM(1), multiTiltMask(1), prepareEM(1), prepareRef(1), prmParser(1), removeDuplicates(1),


 

Index

NAME
SYNOPSIS
DESCRIPTION
PARAMETER FILE OPTIONS
PARAMETER FILE SYNTAX
FILES
AUTHORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 21:10:05 GMT, March 20, 2017