xmipp3.protocols.protocol_resolution_deepres module
- class xmipp3.protocols.protocol_resolution_deepres.XmippProtDeepRes(**args)[source]
Bases:
ProtAnalysis3D,XmippProtocolA deep-learning-based method designed to estimate local resolution in cryo-electron microscopy maps. It analyzes 3D structural features directly from the map data to assign local resolution values to beach voxel of a 3D map.. Using models trained on simulated and experimental data, DeepRes provides spatially resolved estimates that reflect variations in structural clarity across the map. The method captures subtle improvements from post-processing steps, offering a refined view of resolution distribution that supports better interpretation and validation of cryo-EM structures.
AI Generated
## Overview
The Local deepRes protocol estimates the local resolution of a cryo-EM map using a deep-learning model.
Local resolution describes how map quality varies across different regions of a 3D reconstruction. Some parts of a structure may be highly resolved, while others may be more flexible, less ordered, or supported by fewer particles. Instead of assigning a single global resolution to the whole map, this protocol produces a 3D resolution map, where each voxel inside the mask is assigned an estimated local resolution value.
The method uses trained DeepRes neural-network models. The user selects the expected resolution range, and the protocol applies the corresponding model to the masked input volume.
The main output is a local-resolution volume at the original sampling rate of the input map.
## Inputs and General Workflow
The protocol requires:
an input volume;
a binary mask;
an expected resolution range.
The mask is first dilated slightly and multiplied by the input volume so that the analysis focuses on the specimen region. The volume and mask are then resized to the sampling rate expected by the selected DeepRes model.
The protocol runs the deep-learning local-resolution estimator and produces a resolution map. This map is then resized back to the original dimensions and sampling rate of the input volume.
Finally, the protocol computes basic resolution statistics and creates a histogram of local-resolution values inside the mask.
## Input Volume
The Input Volume parameter defines the map whose local resolution will be estimated.
This volume should be a 3D cryo-EM reconstruction with a correct sampling rate. The sampling rate is important because the protocol uses it when resizing the map and interpreting resolution values in angstroms.
The input map should correspond to the structure covered by the mask. Strong artifacts, incorrect sharpening, extreme filtering, or poor masking may affect the local-resolution estimates.
## Mask
The Mask parameter is required.
The mask defines which voxels correspond to the specimen and which voxels are background. It should be a binary mask, with the specimen region included inside the mask and the background outside it.
The protocol dilates the mask by one voxel before multiplying it by the input volume. This helps include boundary regions of the specimen during the analysis.
The quality of the mask is important. If the mask is too tight, real density may be excluded and local-resolution estimates near the boundary may be distorted. If it is too loose, background noise may influence the analysis.
## Expected Resolution Range
The Expected resolutions range parameter selects which trained DeepRes model is used.
There are two options:
2.5 Å - 13.0 Å uses the model intended for lower- to medium-resolution maps. In this mode, the protocol works internally at a sampling rate of 1.0 Å.
1.5 Å - 6.0 Å uses the model intended for higher-resolution maps. In this mode, the protocol works internally at a sampling rate of 0.5 Å.
The user should choose the range that best matches the expected resolution of the map. Choosing an inappropriate range may reduce the reliability of the local-resolution estimate.
## Resizing and Internal Sampling
Before running DeepRes, the protocol resizes the input volume and mask to the sampling rate expected by the selected model.
For the 2.5–13.0 Å range, the working sampling is 1.0 Å.
For the 1.5–6.0 Å range, the working sampling is 0.5 Å.
If the input sampling is coarser than the required working sampling, the protocol resizes the data. If the input sampling is finer, it applies low-pass filtering before resizing to avoid aliasing.
After DeepRes finishes, the output resolution map is resized back to the original sampling rate and dimensions of the input volume.
## Thresholding the Mask
After resizing, the protocol thresholds the mask to make it binary again.
Values below 0.15 are selected and substituted using a binarization operation. This step ensures that the mask used by DeepRes clearly separates specimen and background after interpolation and resizing.
A properly binarized mask helps the neural network focus on the relevant map region.
## DeepRes Resolution Estimation
The core step runs the Xmipp DeepRes local-resolution estimator.
The protocol provides the selected trained model, the resized volume, the resized binary mask, the input sampling rate, and the output file name.
The result is a 3D volume in which voxel values represent estimated local resolution in angstroms.
The calculation uses GPU-compatible TensorFlow execution, with GPU memory growth enabled to reduce memory-allocation problems.
## Output Resolution Volume
The main output is resolution_Volume.
This output is the DeepRes local-resolution map resized back to the original sampling rate of the input volume. It is registered as a Scipion Volume and linked to the input volume.
Voxel values inside the mask represent estimated local resolution in angstroms. Lower values correspond to better local resolution, and higher values correspond to worse local resolution.
The output can be visualized as a volume map or used in downstream protocols that analyze local-resolution variation.
## Chimera Visualization Volume
The protocol also creates an auxiliary Chimera-oriented resolution volume.
In this auxiliary map, background voxels with value zero are replaced by the median local-resolution value. This can make visualization in Chimera or ChimeraX easier by avoiding empty or zero-valued regions that may distort the color scale.
This file is mainly a visualization aid. The main scientific output remains the local-resolution volume.
## Histogram and Resolution Statistics
After producing the resolution map, the protocol computes basic statistics inside the nonzero region of the DeepRes output.
The summary reports:
the median resolution;
the highest resolution;
the lowest resolution.
Here, “highest resolution” corresponds to the smallest numerical resolution value in angstroms, while “lowest resolution” corresponds to the largest numerical value.
The protocol also creates a histogram metadata file describing the distribution of local-resolution values inside the mask.
These statistics are useful for summarizing the spatial resolution variation of the map.
## Interpreting the Local-Resolution Map
The local-resolution map should be interpreted as a spatial estimate of map quality.
Regions with lower angstrom values are estimated to contain better-resolved features. Regions with higher values are estimated to be less resolved, which may reflect flexibility, weaker density, preferred orientation effects, compositional heterogeneity, masking problems, or lower local signal.
The map should be interpreted together with the original density, half-map FSC, global resolution, local map features, and biological knowledge.
Local resolution is not a direct atomic certainty measure. It is an estimate of local map quality and should not be overinterpreted at single-voxel level.
## Practical Recommendations
Use a mask that includes the full molecular density but avoids unnecessary background.
Choose the expected resolution range according to the approximate global resolution of the map. Use the 2.5–13.0 Å range for medium/lower-resolution maps and the 1.5–6.0 Å range for high-resolution maps.
Inspect the output resolution map together with the original cryo-EM density. Check whether well-ordered regions show better resolution than flexible or peripheral regions.
Use the median, minimum, and maximum values as summary descriptors, but inspect the spatial distribution rather than relying only on global statistics.
Be cautious near mask boundaries, flexible domains, low-occupancy regions, or areas with strong artifacts.
If the output appears inconsistent with the visual quality of the map, review the mask, selected resolution range, input sampling rate, and map preprocessing.
## Final Perspective
Local deepRes is a deep-learning-based local-resolution estimation protocol.
For biological users, its main value is that it provides a spatial map of resolution variation across the reconstruction. This can help identify rigid well-resolved cores, flexible domains, weaker peripheral regions, and areas where interpretation should be more cautious.
The output should be used as part of a broader validation workflow, together with FSC analysis, map inspection, local model fit, and biological interpretation.
- HIGH_RESOL = 1
- LOW_RESOL = 0