MASSNORM

Overview

massnorm calculates the relationship between observed electron counts and the specimen's mass density and corrects for electron dose fluctuations during data collection.

The algorithm is:

  1. Find the reference average value A(i) on each projection (these average values would fall along an exponential curve if there was a constant level of illumination for all projections). There are two approaches to calculating the reference average value: It can be beneficial, especially for the average option, to supply massnorm with alignment parameters and restrict the analysis region so the reference values are computed from the same part of the sample.
  2. If exposure times have been recorded in the extended header of the tilt series, normalize the A(i) by them.
  3. Fit an exponential cosine curve to the A(i). The fit can be written to file (see the fit graph parameter), and the contents of that file can be viewed with 2d_plot. The reference values, A(i), and the fit are also saved in the output parameter file.

Here's an example command file for massnorm:

     (time massnorm \
      /mama/weiping/test/cent5r.stk \
      -iprmfile=/mama/weiping/test/cent5r.bprmMn \
      -oprmfile=/mama/weiping/test/cent5r.bprmMn \
      -bckgfit=1 -trange=-60:60 -all \
      -toffset=0 -nhist=400 -oplotfile=none -plot=1 ) \
      > /mama/weiping/emrecon.log

Parameters

Tilt series | NX:NY:NV | Input alignment | Output alignment | Quantity to fit | Tilt range | Analysis region | Analysis region size | Analysis region shift | Reference projection | Tilt offset | Axis orientation | Baseline | Locate jumps | Number of bins | Fit graph | Resolution | Full size | Resolution scale | Reverse tilt axis

Related Priism Topics

Priism | Alignment and reconstruction | Cross-correlation alignment | APPL_PRM | EWBP | TAPIR | Alignment with markers


Tilt Series

This is the name of the file containing the raw projection data stack from the CCD (i.e. measured in terms of electron counts; data stacks with the contrast inverted can not be handled). On the command line, the tilt series file name is the first argument.

Return to the list of parameters


NX:NY:NV

The first two values are, respectively, the x and y dimension of the projections. The third value is the number of projections in the data stack.

Return to the list of parameters


Input Alignment

This is the name of the input alignment parameter file; the file can be generated by the cross-correlation alignment application or the applications for alignment with markers.

To specify the input parameter file from the command line use -iprmfile=filename. none can be used for the file name to signal that no input parameter file is available. If you do not specify an input parameter file, massnorm will try to use the file with the same base name as the tilt series but with a .bprmMn extension.

Return to the list of parameters


Output Alignment

This is the name of the output file in which to store the alignment parameters. This file can be used as input to APPL_PRM and includes the information for converting electron counts to a mass density.

To specify the output parameter file from the command line use -oprmfile=filename. If you do not specify a filename or the name specified is none, massnorm will generate a file with the same base name as the tilt series but with a .bprmMn extension.

Return to the list of parameters


Quantity to Fit

Controls how the reference value for each projection is calculated. For the average intensity option, the reference value is e^(average(log(projection i))). Use this option when there is no clear background in the projections. For the background intensity option, the reference value is the cutoff point for the top five percent of the intensity values.

On the command line, use -bckgfit=1 to use the cutoff from the top five percent of the intensity values and use -bckgfit=0 for the other method. If neither is supplied, the default is to use the cutoff for the top five percent.

Return to the list of parameters


Tilt Range

Sets the range of tilt angles included when fitting the reference average values. The first value is the minimum angle, in degrees, to use; the second is the maximum value.

On the command line specify the range of tilts with -trange=min_angle:max_angle. If the range is not specified on the command line, the full range of tilt angles from the tilt series is included in the fit.

Return to the list of parameters


Analysis Region

In the graphical user interface, the "Analysis region" menu controls the area massnorm uses for computation of the reference average values. There are three options available:

all
massnorm uses the entire area of each projection in the calculation.
common area
massnorm uses the area that is common to all projections within the specified tilt range. If you provide reasonable alignment parameters, then this option is more conservative than the "all" option and is useful when high tilts pull in new features that, if included in the calculations, would substantially change the statistics.
from size & shift
massnorm uses the area specified by the analysis region size, analysis region shift, and reference projection parameters. To set the size and shift, you could use the procedure for selecting a region to reconstruct.

On the command line, include -all in the options to cause massnorm to use the entire area of each projection. Include -common and do not include -all in the options to cause massnorm to use the area common to all projections within the selected tilt range. To specify the area by the size and shift, do not include -all or -common in the options and specify at least one of the -dimxy, -shxyz, or -iref options.

Return to the list of parameters


Analysis Region Size

If you are using the "from size & shift" option for the analysis region, the analysis region size parameters set the x and y dimensions for the area used to estimate the reference average values. These dimensions are for a projection with a tilt of zero degrees; the area chosen on a projection with tilt t is nx * cos(t) by ny where nx and ny are the dimensions at a tilt of zero degrees.

On the command line, specify these dimensions with -dimxy=nx:ny. If no dimensions are specified, massnorm uses the dimensions of the input projections.

Return to the list of parameters


Analysis Region Shift

If you are using the "from size & shift" option for the analysis region, the analysis region shift parameters shift the imaginary 3D tilt axis of the projection data from and thus shift the region of analysis. All three values have units of pixels. The default orientation of the 3D tilt axis has it pass through the point whose x and y coordinates are the center of the reference projection.

Use -shxyz=x_shift:y_shift:z_shift to set the shifts on the command line. If the shifts are not specified, massnorm uses a shift of zero pixels in each direction.

Return to the list of parameters


Reference Projection

For calculating the effect of the x and y shifts (see the analysis region center parameter), massnorm uses the center of the reference projection. Specify the reference projection by its zero-based index in the file (i.e. a value between zero and the number of projections minus one) or use a value of negative one to select the projection whose tilt angle is closest to zero.

The reference projection can be set on the command line with -iref=index. If it is not specified or index is less than zero or greater than or equal to the number of projections in the input file, massnorm uses the projection whose tilt angle is closest to zero.

Return to the list of parameters


Tilt Offset

If the tilt offset is not 90, it is the offset in degrees massnorm adds to the input tilt angles to get the tilt angles written to the output alignment parameter file. If tilt offset is 90, massnorm computes an offset from a fit to the intensities and adds that offset to the input tilt angles to get the tilt angles written to the output alignment parameter file.

Use the tilt offset to correct for cases where the tilt angles in the extended header are offset from the true values. Normally, you would set the tilt offset to zero (i.e. the extended header values are known to be correct) or to 90.

To specify the offset on the command line, use -toffset=offset. If you do not set the offset via the command line, massnorm determines the offset from the fit to the intensities.

Return to the list of parameters


Baseline

When massnorm fits the exponential cosine curve, you have the option to model a contribution to the observed intensities, the baseline intensity level, that does not vary with tilt angle. Starting with Priism version 4.2.1, the default behavior of massnorm is to not model the baseline intensity level because modeling the baseline value proved to be unreliable for many data sets. The massnorm in previous versions of Priism 4 always modeled the baseline intensity level. To turn on modeling of the baseline intensity level in massnorm, turn on the toggle button labeled "Baseline" in massnorm's special parameters dialog. When you run massnorm directly on the command line, include the option -basefit=i, where i is an integer greater than or equal to one, to turn on modeling of the baseline intensity level. To not model the baseline intensity level, do not include the -basefit= option on the command line or use it with an integer argument less one. In the current implementation, modeling of the baseline intensity level is not compatible with the option to identify and fit abrupt changes in the intensities.

Return to the list of parameters


Locate Jumps

Because a tomographic data set is frequently collected in two passes (one for a range of tilts from near zero to the upper tilt angle limit and another for the remaining tilt angles) or an interruption occurred during the time necessary to collect the data set, some data sets have abrupt changes in the image intensities as a function of tilt angle. For those cases, massnorm has an option to automatically identify the ranges of tilt angles collected under different conditions and, with the exception of the tilt angle offset, use different fitting parameters for each range. To enable that option, turn on the "Locate jumps" toggle button in massnorm's special parameters dialog. When you run massnorm directly on the command line, include the option -findjumps=i, where i is an integer greater than or equal to one, to turn on the option to identify abrupt changes in the parameters. As currently implemented, massnorm can not simultaneously model the baseline intensity and identify abrupt parameter changes. When you turn on modeling of the baseline intensity that takes precedence and massnorm will not attempt to identify abrupt parameter changes. Also, massnorm only attempts to identify abrupt parameter changes in the range of tilt angles you included in the fit.

Return to the list of parameters


Axis Orientation

If you do not use an input parameter file, or you turn on the "overwrite input" toggle button next to the "Axis orientation" field, you can use the "Axis orientation" field to specify the angle, in degrees, that the tilt axis makes with the vertical axis of the images as displayed in Priism. If the angle is positive, the images have to be rotated clockwise to make the tilt axis vertical.

On the command line, specify the orientation angle for the tilt axis with the option

    -axis=angle_value

The command-line option to override the tilt axis orientation in the input parameter file is

    -overwrite_axis

If you do not specify -axis and either do not supply an input parameter file or specify -overwrite_axis, the tilt axis will be assumed to be vertical.

Return to the list of parameters


Number of Bins

This parameter sets the number of bins in the histograms in the optional graph output file; it does not affect the internal calculations of the projection reference values.

The syntax for specifying this parameter on the command line is -nhist=n. If you do not specify a number of bins, massnorm will generate graphs with 400 bins.

Return to the list of parameters


Fit Graph

This is the name of the output file to generate with the projection reference values and the corresponding fitted values from the absorption model. You can view line plots of this data by loading the file into 2d_plot. This file is not used by any other part of the EM reconstruction package.

To specify the name of the plot file on the command line, use -oplotfile=filename. If -oplotfile is not supplied or filename is none, then no output plot file is generated.

massnorm has the option to automatically display the graph generated. If you change the pulldown menu in the Special Parameters dialog, from save only to show and save, these results will be automatically displayed with 2d_plot On the command line, use -plot=0 to automatically display the fit results (this is the default setting); otherwise, use -plot=1.

Return to the list of parameters


Resolution

The resolution parameter selects which resolution to process from the input tilt series. 0 is the highest (full) resolution. From the user interface, you would normally select the resolution from the main EMTAR dialog and allow the software to propagate the setting to the individual processing stages. You can also set the resolution to process specifically for the calculation of the mass-normalization parameters from the special parameters dialog for the mass-normalization step.

On the command line, use

    -res=i

to have the calculation of the mass-normalization parameters performed on the ith resolution. When run from the command line and no resolution is selected, the calculations will use the the highest resolution present in the input tilt series.

Two other parameters, the full size and resolution scale, affect the handling of resolution.

Return to the list of parameters


Full Size

Use the full size parameter to specify the dimensions, in pixels, of the full resolution tilt series corresponding to the input tilt series. In the typical case where you select a resolution level to process from the main dialog of EMTAR, the graphical interface will automatically fill in these values correctly. In the case where you are performing the mass normalization calculations on a downsampled file but the input and output alignment parameters are for the full resolution data set, you should adjust the full size parameters to be the dimensions of the full resolution data set.

On the command line, use

    -fullsize=nx:ny

to specify the dimensions, in pixels, of the full resolution data set. When run from the command line without the -fullsize option, the calculation of the mass-normalization parameters will use the dimensions of the highest resolution present in the input tilt series for the full size.

Two other parameters, the resolution and resolution scale, affect the handling of resolution.

Return to the list of parameters


Resolution Scale

The resolution scale parameter controls the scale factor applied to the alignment parameters and, when you use a size and shift to specify the region for analysis, the size and shift parameters for the analysis region. In the typical case where you select a resolution level to process from the main dialog of EMTAR, the graphical interface will automatically fill in the resolution scale correctly. In the case where you are calculating the mass-normalization parameters from a downsampled file but the input alignment parameters are for the full resolution data set, you should set the resolution scale to be the same as the downsampling factor (if the data is scaled down by a factor of four set the resolution scale parameter to four).

On the command line, use

    -rscale=i

to set the resolution scale to be i. When run from the command line without the -rscale option, the calculation of the mass-normalization parameters will use a resolution scale factor equal to two raised to the power of the resolution level selected with -res.

Two other parameters, the resolution and full size, affect the handling of resolution.

Return to the list of parameters


Reverse Tilt Axis

massnorm can add 180 degrees to the input rotation parameters (which set the tilt axis orientation) whether those parameters are derived from the input alignment parameter file or the axis orientation parameter). The usual reason for doing so would be to match your experimental conditions with the geometry conventions used to compute the defocus in CTF correction and generate reconstructions.

From the graphical user interface, turn on the toggle button labeled "Reverse tilt axis" to add 180 degrees to the rotation parameters. That toggle button is in the special parameters dialog. On the command line, include -revaxis in the options to add 180 degrees to the rotation parameters.

Return to the list of parameters