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.
Extrapolate (Default: On)
Oftentimes the experimental data do not go to the high resolution limit defined by the voxel size. For example, the default voxel size is 5 Å, corresponding to a maximum q value of 1.26 Å-1 (2π/voxel). SAXS data doesn’t typically extend to such high q values, though WAXS often exceeds this. To ensure realistic values for intensities in reciprocal space at q values higher than that which is provided by the experimental data, the profile is extrapolated using Porod’s law (I(q) ∝ q-4). You may disable this option with –extrapolate_off.
Limit Dmax (Default: Off)
This option removes any grid points outside of a sphere of radius Dmax/2 (actually 0.6*Dmax for some wiggle room) from the center of the grid from the support, effectively setting all voxels outside of this boundary to be zero. Provided your particle is properly centered inside the box, and does not extend beyond this boundary, this helps to prevent noise far out in the solvent region. However, this option is discouraged as it may chop off parts of the particle during the early stages, biasing further convergence (which is what the –dmax_start_step option is for). Hence it is disabled by default. If you really want to use it, but are concerned your particle may get cut off because your Dmax is too small, increase Dmax with the -d option. But if for some reason you would like to keep the same box size, decrease the oversampling with the -os option (which accepts non-integer values).
But, just don’t… Shrink-wrap coupled with –enforce_connectivity will do the job and do it much better. This is really just here for legacy reasons.
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.
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 = 3 by default). As the particle becomes more globular, sigma gradually decreases to a minimum value (–shrinkwrap_sigma_end = 1.5 by default). 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) 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 (Defaults: SLOW=5000; FAST=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 (Defaults: SLOW=6000; FAST=2000)
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. When doing so, you will probably also want to adjust the –recenter_steps accordingly to makes sure the remaining large blob of density gets moved to the center.
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.