xmipp3.protocols.protocol_helical_parameters module
- class xmipp3.protocols.protocol_helical_parameters.XmippProtHelicalParameters(**kwargs)[source]
Bases:
ProtPreprocessVolumes,HelicalFinderEstimates the helical symmetry and parameters of a structure. Helical symmetry is defined mathematically as V(r,rot,z)=V(r,rot+k*DeltaRot,z+k*Deltaz) and applied to improve the reconstruction of the volume specimens inthe processing. You can limit the radios of the helix, apply dihedral symmetry and apply Cn symmetry
AI Generated
## Overview
The Helical Symmetry protocol estimates the helical parameters of a 3D volume and uses them to produce a symmetrized version of the structure.
Helical symmetry describes structures that repeat by a combination of rotation and translation along an axis. In this protocol, the helix is assumed to be oriented along the Z axis of the input volume. The repeated unit is described by two main parameters:
DeltaRot, the rotation angle between consecutive helical repeats;
DeltaZ, the axial displacement, or rise, between consecutive repeats.
In mathematical terms, the density is expected to satisfy a relation of the form:
[ V(r, heta,z) pprox V(r, heta + k Delta heta, z + k Delta z) ]
for integer values of (k), where (Delta heta) is the helical twist and (Delta z) is the helical rise.
The protocol first searches for the helical parameters that best explain the input volume. It then applies the estimated symmetry to generate a symmetrized output volume. This can improve the signal-to-noise ratio and produce a more consistent reconstruction when the sample truly follows helical symmetry.
## Inputs and General Workflow
The main input is a 3D volume representing a helical specimen. The volume should already be approximately aligned so that the helical axis corresponds to the Z axis.
The protocol proceeds in several conceptual steps.
First, it prepares the input volume. If requested, it may apply an initial dihedral symmetry operation before searching for the helical parameters.
Second, it performs a coarse search over the user-defined ranges of rotation and axial shift. This step explores the possible helical twists and rises.
Third, it performs a fine search around the best candidates found in the coarse search. This refines the estimated helical parameters.
Finally, the protocol symmetrizes the volume using the refined helical parameters and produces an output volume. It also reports the estimated DeltaRot and DeltaZ values.
## Input Volume
The Input volume should be a 3D reconstruction of a helical structure.
For the search to be meaningful, the helical axis should be approximately aligned with the Z axis. If the helix is tilted or strongly off-center, the estimated parameters may be unreliable.
The input volume should also contain enough visible helical signal. Very noisy volumes, volumes with strong distortions, or volumes dominated by non-helical features may lead to incorrect estimates.
This protocol is most appropriate when the user already has a preliminary helical reconstruction and wants to estimate or refine its symmetry parameters.
## Helical Rise and Twist
The two most important outputs are DeltaZ and DeltaRot.
DeltaZ is the axial translation between consecutive helical repeats. It is reported in angstroms. In the summary, it may also be expressed in voxels by dividing by the sampling rate.
DeltaRot is the rotation angle, in degrees, between consecutive helical repeats.
Together, these two values define the helical operation. Repeated application of this operation should map one subunit or repeating density element onto the next one along the helix.
Biologically, these parameters describe the architecture of the filament. They are related to the pitch, number of subunits per turn, and repeat organization of the assembly.
## Cylinder Inner and Outer Radius
The Cylinder inner radius and Cylinder outer radius restrict the radial region of the volume used for symmetry estimation and symmetrization.
The helix is assumed to occupy a cylindrical region around the Z axis. By specifying inner and outer radii, the user can tell the protocol which part of the volume should contribute to the search.
If both values are left as -1, the whole volume is used.
Using a cylindrical restriction can be useful when the volume contains central noise, peripheral artifacts, solvent density, or regions that should not contribute to the symmetry search. It can also help focus the search on the part of the map where the helical signal is strongest.
The radii are given in voxels. Users should choose them according to the size and position of the filament in the box.
## Height Fraction
The Height fraction controls how much of the volume height is used to estimate the helical parameters.
A value of 1 uses the full height of the volume. Values below 1 use only a central fraction of the volume. This is useful because the top and bottom planes of a reconstruction are often less reliable, affected by edge effects, or less well resolved.
The default value excludes a small fraction of the extremes while keeping most of the helix. This is usually a sensible choice.
If the full volume is well resolved and free of edge artifacts, a value of 1 can also be appropriate. If the ends of the helix are noisy or distorted, a smaller fraction may improve the robustness of the search.
## Search Limits for Rotation
The parameters Minimum rotational angle, Maximum rotational angle, and Angular step define the coarse search range for DeltaRot.
The protocol explores rotational angles in this interval using the specified step size. A smaller angular step gives a finer search but increases computation time. A larger step is faster but may miss the best value or give a less accurate starting point for the fine search.
If little is known about the helix, a broad range such as 0 to 360 degrees may be used. If approximate helical symmetry is known from prior information, literature, indexing, or visual analysis, the range can be narrowed to make the search more efficient and less ambiguous.
## Search Limits for Axial Shift
The parameters Minimum shift Z, Maximum shift Z, and Shift step define the search range for DeltaZ.
These values are expressed in angstroms. The minimum axial shift must be positive. A zero or negative value is not meaningful for the helical rise and is rejected by the protocol.
As with the rotational search, a smaller step gives a finer exploration but requires more computation. A broader range is useful when the rise is unknown, whereas a narrower range is preferable when prior structural information is available.
The selected range should contain the expected rise between neighboring repeating units. If the true rise lies outside the search interval, the protocol cannot recover the correct helical parameters.
## Coarse and Fine Search
The protocol performs two searches.
The coarse search explores the user-defined range of rotations and axial shifts. Its purpose is to identify promising helical parameters.
The fine search refines the result from the coarse search. It uses the coarse-search output as a starting point and estimates more accurate values for DeltaRot and DeltaZ.
This two-stage strategy is useful because helical symmetry searches can be ambiguous. A broad coarse search reduces the risk of missing the correct region, whereas a fine search improves the final parameter estimate.
## Dihedral Symmetry
The option Apply dihedral symmetry applies dihedral symmetry during the preparation and search.
Dihedral symmetry may be appropriate for some helical assemblies that have an additional twofold relationship perpendicular to the helical axis. When this symmetry is biologically justified, applying it can improve the signal and make the helical search more stable.
However, dihedral symmetry should not be applied simply because it improves the appearance of the map. If the specimen does not truly have this symmetry, forcing it may introduce artificial density and distort the biological interpretation.
The advanced option Force the dihedral axis to be in X assumes that the dihedral axis is around X instead of searching for it. This should only be used when the orientation of the volume is known and the user is confident that this constraint is correct.
## Additional Cn Symmetry
The option Apply Cn symmetry allows the user to impose an additional cyclic symmetry around the helical axis.
For example, C2 symmetry means that the structure is expected to have a twofold rotational symmetry around the relevant axis. Other Cn values may be specified according to the biological symmetry of the assembly.
This option should be used only when there is prior evidence for the additional cyclic symmetry. Applying an incorrect Cn symmetry can average together non-equivalent features and damage the interpretation of the map.
If no additional cyclic symmetry is required, the protocol uses C1, meaning no extra cyclic symmetry.
## Symmetrized Output Volume
The main output is a symmetrized volume.
This volume is produced by applying the estimated helical parameters to the input volume. If additional dihedral or Cn symmetry was requested, those symmetry operations are also included.
The output volume keeps the sampling information from the input volume. It can be used for visualization, further interpretation, or as an improved reference in subsequent processing steps.
The symmetrized volume should be inspected carefully. Symmetry application can increase signal-to-noise ratio and improve the clarity of repeating features, but it can also amplify errors if the estimated parameters or imposed symmetries are wrong.
## Output Helical Parameters
In addition to the symmetrized volume, the protocol reports:
DeltaRot, the estimated helical rotation in degrees;
DeltaZ, the estimated helical rise in angstroms.
These values summarize the helical symmetry found by the protocol. They are important not only as processing parameters, but also as structural descriptors of the specimen.
Users should compare these values with prior biological knowledge, expected repeat distances, known filament geometry, or independent estimates when available.
## Practical Recommendations
Before running the protocol, make sure that the helix is approximately centered and aligned with the Z axis. This is one of the most important practical conditions for a reliable result.
Use broad search ranges when the helical parameters are unknown. Use narrower ranges when prior information is available, because this reduces ambiguity and computation time.
Keep the height fraction below 1 if the ends of the volume are noisy or poorly resolved. Use 1 only when the full height of the reconstruction is reliable.
Use cylinder radii to focus the search on the meaningful helical density, especially when the box contains strong solvent noise, artifacts, or regions that should not contribute to symmetry estimation.
Apply dihedral or Cn symmetry only when it is biologically justified. Incorrect extra symmetry can produce attractive but misleading maps.
After the protocol finishes, inspect the symmetrized volume and verify that the main structural features are improved rather than artificially smeared or duplicated. Also check that the estimated DeltaZ and DeltaRot are physically reasonable for the specimen.
## Final Perspective
The Helical Symmetry protocol estimates the rise and twist that best describe a helical volume and uses those parameters to generate a symmetrized map.
For biological users, this protocol connects image processing with structural interpretation. The estimated helical parameters describe how the molecular subunits repeat along the filament, while the symmetrized volume can improve the visibility of recurring structural features.
The protocol is most powerful when used with a well-centered, Z-aligned preliminary reconstruction and with search ranges guided by biological or structural expectations. Used carefully, it can improve both the quality of the map and the understanding of the helical organization of the specimen.