CryoSPARC Guide
Comment on page

Job: Local Refinement

Local refinement.


CryoSPARC v3.1.0+ features an updated re-work of the Legacy Local Refinement job, supporting the new Non-Uniform adaptive regularization present in the Non-Uniform Refinement (NEW) job, along with alignment pose and shift marginalization. In addition, the Local Refinement job supports reconstruction with higher-order CTF parameters, alignment priors (for soft penalization of unlikely poses and shifts), and symmetry enforcement. This page highlights the new features added, and their corresponding parameters. For a description of the Local Refinement job, including when to use Local Refinement, visit the Legacy Local Refinement job page. For information on mask generation, visit the Mask Selection and Generation in UCSF Chimera page.


  • Particles (blob, ctf, alignments3D)
    • Particles can be taken as outputs from a Particle Subtraction job, such that only the signal from the desired region is retained in each particle image
    • Since Local Refinement only enables particle poses to deviate slightly from their initial values, it is unique amongst the refinement jobs in that alignment information is required to compute the particles' initial poses
    • Note that particles must have been previously assigned a gold-standard FSC half-set split, which will be the case if the particles are inputted from any of the refinement jobs
  • Volume (map, map_half_A, and map_half_B)
  • Mask


  • Volume (refined sub-volume)
  • Particles
  • Mask
  • Plots, including overall orientation distributions, and distributions of the deviances from initial poses

Changes from Legacy Local Refinement

Note that in Local Refinement (NEW! BETA), an important convention change is that the volume is no longer shifted to the fulcrum-centered frame. This makes it such that the original reference frame of the volume is maintained at the end of the refinement, enabling Particle Subtraction to be done before or after local refinements. For example, if you have a complex that is comprised of two independently moving subunits, you can first perform separate local refinements on each subunits, using unsubtracted particles. Then, particle subtraction can be done to subtract each subunit away from the particle stack, using the refined alignments from each local refinement. These particles can be used for future local refinements, and this procedure could be iterated.

Mask Troubleshooting

Note: Mask padding and size are among the most common sources of difficulty when using local refinement. Please read the below sections and ensure that the mask is softly padded, and of appropriate size, before running local refinement.

Mask Padding

It is very important that the mask has soft padding, i.e., that the edge of the mask falls off gradually over space from 1 to 0. Masks can be padded using the Volume Tools job, by setting the Threshold and Soft padding width parameters. We typically recommend setting the Soft padding widthparameter to be a voxel value that ensures the resulting padding is several factors larger than the expected resolution of the complex. A good rule of thumb gives the minimum mask softness as 5 * res_angstroms / pixel_size_angstroms.For example, a complex reaching 3.0 Å in resolution with a pixel size of 1.0 Å should be padded to at least 5 * 3.0 / 1.0 = 15 voxels.

Mask Size

For best results, we typically recommend that the mask covers a region of the protein larger than ~150 kDa in mass. When smaller masks must be used, there may not be enough information present to align particles to the masked volume. This may result in overfitting, which typically manifests itself as artefacts in the density (streaks, shells, or high-density "blips").
As an antidote to overfitting, we can regularize the alignment problem by constructing a prior distribution over pose and shift, in order to penalize alignments that are too far away from the original alignments. The implementation uses an isotropic gaussian prior, centered at the current best alignment parameters. This can be done by activating the Use pose/shift gaussian prior during alignment parameter, and by specifying theStandard deviation of prior over rotation/shift parameters.
These standard deviations should reflect the size of movement you expect to see. If you have a complex that undergoes a large amount of motion (e.g. a spliceosome head region, such as in our case study), you may want a larger prior like 20º and 10Å. On the other hand, if you are using local refinement just to try to improve detail in a specific region of the map and don’t think there is much independent motion of that region, much smaller priors, even as small as 3º and 2Å may be optimal.

Common Parameters

Alignment Parameters

  • Rotation search extent (deg): This controls the rotational extent, in degrees, to which particles are allowed to deviate from their initial poses.
  • Shift search extent (A): This controls the translational extent, in pixels, to which particles are allowed to deviate from their initial shifts.
  • Standard deviation (deg) of prior over rotation: This can be set to a number in degrees, corresponding to the desired standard deviation of an isotropic Gaussian prior over rotation. This has the effect of softly penalizing poses that are far away from the initial poses, rather than strictly cutting off the search beyond a specific point. Note that by default, the rotational search extent will be set to three times this value, but both parameters can be independently specified if desired.
  • Standard deviation (A) of prior over shifts: This can be set to a number in Angstroms, corresponding to the desired standard deviation of an isotropic Gaussian prior over shifts. This behaves similarly to the Gaussian prior over rotation. Note that the "Use pose/shift gaussian prior during alignment" parameter must be set to true to activate both priors.
  • Default fulcrum location: Local Refinement uses a default fulcrum centered at the center of mass of the mask input to the job. This can be changed to use the center of the box (i.e. the rotation center used by all other refinements). Optionally, the fulcrum can be manually overwritten by typing comma-separated coordinate values in the "Override fulcrum coordinates (pix)" parameter, which corresponds to the grid index of the desired fulcrum in x, y, z order, indexed relative to the corner of the box.
  • Re-center rotations/shifts each iteration?: Local Refinement allows for the pose and shift search grids to drift between each iteration, so that the alignment search grids can be re-centered on the previous iteration's optimal pose/shift. If these parameters are activated, it is recommended to also activate the gaussian prior, as poses and shifts may stray too far in early iterations from the true optima. Note that when re-centering is active, both the rotation/shift search grids as well as the rotation/shift gaussian priors will be re-centered at each iteration.
  • Maximum alignment resolution (degrees): This specifies the finest alignment search grid spacing to use, which will be enforced by the final branch-and-bound iteration

Refinement Parameters

  • Marginalization: This enables efficient pose and shift marginalization over particle alignments during reconstruction steps. Marginalization can improve 3D structure quality on smaller proteins, decrease overfitting, and sometimes limit the influence of outlier images.
  • Non-Uniform Refinement Enable: Non-Uniform Refinement can be enabled to help resolve molecules with spatially-varying local resolution. This is particularly useful for membrane proteins, or any proteins with disordered regions (e.g. micelles).
    • Non-uniform filter order: This controls the order of the butterworth filter used for cross-validation-optimal regularization.
    • Non-uniform AWF: Adaptive Window Factor for cross-validation-optimal regularization. Trade off between fast transitions between regions (AWF should be lower) and more accurate local cross-validation test (AWF should be higher).
  • Symmetry: Local refinement supports enforced point-group symmetry around the object origin (i.e. the center of box, not the fulcrum). Note that this parameter, should not be changed if the particles have previously been symmetry expanded. For most use cases, symmetry expansion is still preferred over enfirced symmetry, as it incorporates symmetry while also allowing particle alignments between each asymmetric unit to vary slightly, which can account for flexibility between asymmetric units.
  • Mask (dynamic, static): This can be set to dynamic to re-generate a dynamic mask at each iteration of the refinement, or instead to static to use the unmodified input mask at each iteration. Note that we generally recommend static masks to be use, as we have seen that dynamic masks can result in mask-based overfitting.
    • If dynamic masking is enabled, the following parameters control the mask:
      • Dynamic mask threshold (0-1): The level-set threshold for selecting regions to include in the dynamic mask
      • Dynamic mask near (A): The distance to dilate the dynamic mask to, after thresholding
      • Dynamic mask far (A): The distance at which the mask becomes 0.0
      • Note that the width of the soft padding is equal to the difference between the far and near distances. For smaller masks, it is often desirable to make the masks softer (by increasing the padding width) in order to limit overfitting
  • Minimize over per-particle scale: This allows the per-particle scale factor to be optimized at each refinement iteration. For most use cases of Local Refinement, this should be kept off, as the comparison between a masked subregion and each particle image may not be accurate if the mask excludes a large portion of the volume.
For tips on the tuning of these parameters, please see the Fulcrum Selection and Search Extents sections in the Legacy Local Refinement job page.


Magnitude of alignment changes

Magnitude of alignment changes plot produced by local refinement. Generally, distributions that peak near 0 and decay for large alignment changes are expected; distributions that grow as the alignment change increases may indicate poor regularization, potentially caused by too small or too tight masks. Note that these plots display the magnitude of the difference between the optimal pose and shift, compared to the center of the search grids. This means that if “Re-center rotations/shifts each iteration” is off, it will plot the cumulative change in the poses/shifts from the initial alignments at the start of the job. Conversely, if “Re-center rotations each iteration” is on, it will plot the per-iteration change (not cumulative across iterations).

Example Workflow