Advanced Usage
For most circumstances, the basic options are all you need. However, if you would really like to dig in to the algorithm, there are several advanced options that can be invoked. Most of these options adjust real space restraints, such as shrinkwrap. We will go through each in turn.
Recenter (Default: On)
The first option we will start with is recentering the particle. For the beginning part of the reconstruction, separate blobs of density often appear causing issues with accurate recentering. Thus, by default, recentering does not begin until after the –enforce_connectivity restraint is invoked. Recentering then occurs a few times afterwards just to make sure the particle stays close to the center while it converges. The particle is recentered by calculating the center of mass of the density and shifting the particle such that it aligns with the center of the grid. However this shift simply rolls the array values so as to avoid excessive interpolation (which can cause artifacts), so the particle is not exactly in the center, but just close to it. You can change during which steps the particle gets recentered by giving a space separated list of steps to the –recenter_steps option, or disable it entirely with the –recenter_off option.
Positivity (Default: On)
Positivity ensures that there are no negative density values throughout the box by making every negative value zero. You can disable this with the –positivity_off option.
Shrink-wrap (Default: On)
Shrink-wrap is one of the most important features of DENSS and is crucial for determining which voxels belong to the support. Every 20 steps shrink-wrap makes a copy of the density* and convolves it with a Gaussian of width sigma (i.e. it “blurs” the density like an image in Photoshop). It then defines the support as all voxels whose blurred density is greater than some minimum threshold (by default set to 20% of the maximum of the blurred density). Towards the start of the reconstruction, most of the density is still approximately uniformly distributed, so the support is pretty much the entire grid. However as the reciprocal space restraints are imposed (i.e. the data), the density becomes more blob-like and globular, causing shrink-wrap to remove more and more voxels from the support, which in turn causes the density to become even more globular, and on and on. Eventually this process converges where the support changes very little when updating it with shrink-wrap.
*NB: shrink-wrap does not change the actual density. It just uses it to determine the support.
Shrink-wrap Sigma
This option determines how much blurring occurs when running shrink-wrap. The value, sigma, is given in voxels. A larger number means greater blurring. At the beginning we don’t have much of a particle yet, so we want the support to change very gradually while we let the data make the density more globular. To do this we use a lot of blurring since that makes the voxel values more similar to their neighbors limiting how many voxels get removed from the support (i.e. –shrinkwrap_sigma_start ~ D/7 in Å by default). As the particle becomes more globular, sigma gradually decreases to a minimum value (–shrinkwrap_sigma_end ~ D/14 in Å by default). The defaults are twice these values in MEMBRANE mode. The rate of decrease is determined by the –shrinkwrap_sigma_decay (default = 0.99). If you want shrink-wrap to be less restrictive to start, increase the sigma_start value. If you want shrink-wrap to converge more slowly, increase the sigma_decay value (maximum of 1). Editing these values will likely result in a slower convergence process requiring more steps, so be sure to increase the -s option to allow enough time for the reconstruction to converge. If you would like to remove the -s option altogether and allow the algorithm to stop only once it has converged (determined by the –chi_end_fraction option), simply give a very large number to the -s option (like 1e8), but be prepared to wait. The total number of steps for updating the support using shrink-wrap (and thus roughly minimum number of steps for convergence) can be calculated as
Shrink-wrap Threshold Fraction (Default: 0.20)
This option sets the minimum threshold, as a fraction of the maximum of the blurred density, that a voxel density must exceed to be a part of the support. If you think shrink-wrap might be chopping off parts of your particle, decrease this value. However, decreasing this value will likely result in noisier maps. If you decrease this value, you may want to add some steps to the –enforce_connectivity_steps option to make sure that you only end up with one connected region of the support. You will also want to increase the maximum number of total steps (-s) allowed for the reconstruction, as decreasing this value may cause the reconstruction to converge more slowly.
Shrink-wrap Iter (Default: 20)
This is the number of steps between updating the support with shrink-wrap. The density should converge a little within this time frame, and then the support should be updated again to more closely reflect the new density. You will likely see some spikes at regular intervals in your final plots. The interval between these spikes is most likely equal to shinkwrap_iter.
Shrink-wrap Minstep (Default: 1000)
This option tells shrink-wrap when to start. It actually doesn’t start at step zero by default, but step 20, since that is the first possible iteration. This is intentional as it gives the density a little time to begin converging based solely on the data and the positivity restraint and become a bit more globular, before shrink-wrap starts removing voxels from the support. If you feel that shrink-wrap may be a bit too aggressive to start with, try increasing this number to a later step to give it more time to converge just with the positivity restraint without removing any voxels from the support (thus performing no solvent flattening). If you do that, you may want to increase the –enforce_connectivity_steps option also to make sure the initial blobs of density have time to form before it cuts them off. That in turn may affect your –recenter_steps option also, so you might want to change that too.
Enforce Connectivity (Default: On)
As the reconstruction progresses, the density become more globular. While shrink-wrap does a pretty good job of eliminating the noise in the solvent, occasionally multiple blobs of density will appear in the final reconstruction. This occurs because the blobs are typically very far apart and only contribute scattering at very low angles and thus do not affect the fit of the scattering profile substantially (each individual blob typically looks similar to the actual particle). However this can obviously cause unwanted artifacts in the density since the combination of blobs are now contributing to the scattering profile. To mitigate this problem, the –enforce_connectivity_on option is enabled by default. This option, after enough iterations have progressed to create particle-like globular densities, evaluates the support to define “features”, i.e. disconnected regions of the support, and eliminates all of the features except the one with the greatest density. It simply eliminates these voxels from the support. This often significantly improves the final reconstruction, particularly for more complex particle shapes.
Enforce Connectivity Steps (Default: shrinkwrap_minstep + 1000)
This option defines which steps to initiate the enforce_connectivity routine. Make sure you give the algorithm enough time to reconstruct useful globular density. If you still find you have multiple blobs at the end of your reconstruction, add more steps to this option as a space separated list of integers.
Chi2 End Fraction (Default: 0.001)
DENSS will stop when either one of the following two things happen: (1) the maximum number of steps has been reached (–steps option) or (2) when convergence has been achieved (-cef option). Here, “convergence” refers to when the chi2 stops changing. Convergence is defined as when the standard deviation of the chi2 over the previous 100 steps is less than some threshold, i.e., when the fluctuations or change in chi2 is small. The threshold is defined as a fraction of the median chi2 from that same previous 100 steps. By default, the threshold fraction (i.e, the -cef option) is set to 0.001. If you find that the program converges and stops earlier than you would like (for example if it stops before first imposing symmetry at step 3000), then you can set the -cef option to be a smaller number. If you would like to remove this convergence criterion completely, such that the program only stops when the maximum number of steps has been reached, then set the -cef option to zero.
Questions?
If you have any questions about any of these options or more generally how to run DENSS, please send an email using the contact form below.