# Job: Symmetry search utility

Symmetry search utility.

Search a volume for candidate helical symmetry parameters, by comparing the mean squared error across symmetry-related positions for different symmetry parameters.

- Volume
- Mask (optional)

- 2D and 1D plots of the mean squared error surface
- Tables of candidate symmetry pairs
- Symmetry candidates (
`.cs`

file)

This job performs a low-level searching operation over symmetry parameters, similar to the search in helical refinement, except with more diagnostic plots and allowing for larger search ranges. Be sure to read the page detailing

**how helical symmetry is treated in CryoSPARC**for more information on the various characterizations of helical symmetry used by this job, including the differences between the "pitch" and "rise" modes.`Search over pitch/number of subunits, or rise/twist?`

- This parameter controls the "mode" that the searching is done in. Specifically, the search grid can operate in two modes:
- "pitch" mode, where the search grid is a 2D grid of$(n,p)$values (for a specified hand), or
- "rise" mode, where the search grid is a a 2D grid of$(\Delta \phi, \Delta z)$values.

- Generally, it's more informative to run this job "pitch" mode, as the job will search the volume over both left and right handed symmetry parameters, as well as writing additional 1D error plots where only one variable (n, or p) is allowed to vary. The exception to this is helices with very large asymmetric units, where the asymmetric units don't actually form a helical lattice so the "pitch" view is less interpretable

**Search grid sizes**(number of grid points)- This controls the number of grid points to use in the 2D search. Generally, it is not necessary to change these from the defaults. For faster computation time, these can be decreased. For large search ranges, these could be increased to increase the fineness of the search (up to a maximum of 512).

`Override the number of asymmetric units to search`

- Number of asymmetric units (i.e. helical rises) to search over. If left as None, will be calculated automatically in the same way as in helical refinement.

**Override outer (inner) filament diameter for search (Å)**- The inner and outer diameters to search over can be forced to specific values in Angstroms. If these are left as None, these will be calculated automatically from the radial extent of a mask (either passed to the job, or generated within the job).

**Maximum number of local minima**- The two parameters
`Maximum number of local minima to display in the stream log`

and`Maximum number of local minima to output`

can be increased to return more of the local minima ("symmetry candidates") in the streamlog and in the outputs, respectively

- Search grid extents over helical pitch (Å) and number of subunits per turn
- The
`Search min and max over helical pitch (A)`

and`Search min and max over number of subunits per turn`

should be set to a pair in the form`x,y`

(e.g.`10,20`

) where x is the lower search range and y is the upper search range. As per cryoSPARC's helical symmetry conventions, both values are expected to be positive.

- Helical hand
- Since the pitch mode description doesn't specify the hand of the helix, this parameter can be used to set which hand to search over. By default, both right and left handed paths will be searched. Note that we always recommend to inspect the map to be searched before running this job, in order to see which hand the helical symmetry has. Be sure to read the page detailing how helical symmetry is treated in cryoSPARC for notes on the ambiguities in the hand of helical symmetry

- Search grid extents over helical rise (Å) and twist (degrees)
- Similar to the search extents in the pitch mode, these should be set to a pair in the form
`x,y`

where x is the lower search range and y is the upper search range - As per cryoSPARC's helical symmetry conventions, the rise is expected to be positive. Note that the first endpoint of the search ranges should always be the lesser of the two, e.g. for searching twists between -30º and -20º, use the ordering
`-30, -20`

- Lowpass resolution (Å), filter type, and order
- Optionally, the volume can be lowpass filtered using either a butterworth filter (with specified order) or boxcar lowpass filter, to a given resolution

- Which map to search
- This parameter can be set to search either the raw
`map`

or the sharpened`map_sharp`

The primary use case of the search utility is after ab-initio reconstruction or helical refinement, to determine what helical symmetry exists in the reconstructed volume. The job is useful for searching over a relatively large search range of symmetry parameters, and reporting the best fit, which can be used as input symmetry parameters to a subsequent helical refinement. For each helical hand searched over, a table of local optima of the error are printed out, ranked by their MSE values; the global optimum is the first entry on the table. If both left and right hands are searched over, the first job checkpoint will show plots and tables for right handed symmetry parameters, and the second job checkpoint for left handed symmetry parameters. Note that due to the the maximum helical rise searched over is constrained by the box size of the volume, thus excessively large search ranges may not be allowed by the job.

Further, note that large search ranges may be redundant in the sense that they sample the same symmetries more than once. The simplest example of this is when comparing MSE between a given twist, rise pair of

$(\Delta \phi_0, \Delta z_0)$

, and a pair where the twist and rise are both doubled, $(2 \Delta \phi_0, 2 \Delta z_0)$

. In this case, the second pair results in searching over the same helical "trajectory", but skipping over every other asymmetric unit. These two pairs will likely produce similar MSE scores, however if we launched a helical refinement with the doubled pair, the algorithm would only use each image half as many times as it could be. *Ultimately, it is important to ensure that redundancy is considered, and that any symmetry estimates from this job are taken into account alongside a manual inspection of the input volume*.The symmetry search utility prints plots of the error surface to the streamlog. By default, it will print 1D plots of the mean squared error along constant

$p$

and $n$

values (two for each hand). It will also print 2D error surface plots (one for each hand). If mode is set to "rise", it will instead print only one 2D error surface plot. Below shows an example of the error plots for a reconstruction of EMPIAR-10267 (CFA/I pili). In the 2D plots, horizontal/vertical gray dashed lines intersect at the global optimum for each hand. It is important to compare the MSE scale bars across both plots: here, we see on the left that the global minima is at around 600, whereas on the right the global minima is much lower, at 6. Within a single job, MSE values are always comparable to each other – thus, we can conclude that within these ranges, right-handed symmetry parameters of

$n \approx 3.15$

and $p \approx 27 \; Å$

fit the volume best.To obtain exact values of the global minima, we can then navigate to the first job checkpoint (showing right-handed symmetry parameters), and scroll down to the printout of the list of local minima. Below, the first three are shown. From the MSE values, symmetry parameters of

$p = 27.059 \; Å$

and $n = 3.176$

, equivalent to a rise of $\Delta z = 8.519 \; Å$

and twist of $\Delta \phi = 113.333º$

best fit the volume.Showing the 20 best local minima.

No. | p (A) | n | dz (A) | dphi (deg) | mse

-------------------------------------------------------------------------

00 | 027.059 | 003.176 | 008.519 | +113.333 | 6.163

01 | 027.118 | 002.118 | 012.806 | +170.000 | 524.423

02 | 019.647 | 003.129 | 006.278 | +115.038 | 629.372

Finally, the symmetry search utility also outputs 1D error surface plots. These plots show the error as a function of

$p$

(evaluated at the best $n$

value), and vice versa. They are the same as extracting lines out of the 2D MSE plot along the horizontal and vertical dashed gray lines. For the above example, the error over $p$

shows a fairly broad minima about the best result, and the error over $n$

shows a narrow minima, with a few shallow local minima on either side.MSE as a function of "pitch"

MSE as a function of "number of subunits per turn"

The symmetry search utility uses components of a BSD-licensed cubic B-spline interpolation implementation in CUDA, originally authored by Danny Ruijters. Following is the required copyright and license notice.

/*--------------------------------------------------------------------------*\

Copyright (c) 2008-2010, Danny Ruijters. All rights reserved.

http://www.dannyruijters.nl/cubicinterpolation/

This file is part of CUDA Cubic B-Spline Interpolation (CI).

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the

documentation and/or other materials provided with the distribution.

* Neither the name of the copyright holders nor the names of its

contributors may be used to endorse or promote products derived from

this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are

those of the authors and should not be interpreted as representing official

policies, either expressed or implied.

When using this code in a scientific project, please cite one or all of the

following papers:

* Daniel Ruijters and Philippe Thévenaz,

GPU Prefilter for Accurate Cubic B-Spline Interpolation,

The Computer Journal, vol. 55, no. 1, pp. 15-20, January 2012.

http://dannyruijters.nl/docs/cudaPrefilter3.pdf

* Daniel Ruijters, Bart M. ter Haar Romeny, and Paul Suetens,

Efficient GPU-Based Texture Interpolation using Uniform B-Splines,

Journal of Graphics Tools, vol. 13, no. 4, pp. 61-69, 2008.

\*--------------------------------------------------------------------------*/

Last modified 5mo ago