# **************************************************************************
# *
# * Authors: Carlos Oscar S. Sorzano (coss@cnb.csic.es)
# *
# * Unidad de Bioinformatica of Centro Nacional de Biotecnologia , CSIC
# *
# * This program is free software; you can redistribute it and/or modify
# * it under the terms of the GNU General Public License as published by
# * the Free Software Foundation; either version 2 of the License, or
# * (at your option) any later version.
# *
# * This program is distributed in the hope that it will be useful,
# * but WITHOUT ANY WARRANTY; without even the implied warranty of
# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# * GNU General Public License for more details.
# *
# * You should have received a copy of the GNU General Public License
# * along with this program; if not, write to the Free Software
# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
# * 02111-1307 USA
# *
# * All comments concerning this program package may be sent to the
# * e-mail address 'scipion@cnb.csic.es'
# *
# **************************************************************************
import os
from pyworkflow import VERSION_1_1
from pwem.protocols import ProtAnalysis3D
from pyworkflow.protocol.params import MultiPointerParam
from pwem import emlib
[docs]class XmippProtNormalizeStrain(ProtAnalysis3D):
"""
Normalize the local strain and rotations amongst several runs.
AI Generated
## Overview
The Normalize Strain protocol prepares consistent visualizations for several
previous volume-strain analyses.
Volume-strain analysis can produce maps describing local deformation and local
rotation between two volumes. When several strain calculations are performed,
for example for different maps, different conformational transitions, or
different processing conditions, each run may have its own numerical range of
strain or rotation values.
If each result is visualized with an automatically chosen color scale, the same
color may represent different numerical values in different runs. This can make
comparisons misleading.
The purpose of this protocol is to normalize the visualization ranges across
several strain-analysis runs. It finds the global minimum and maximum values
across all selected runs and writes ChimeraX command files that use the same
color scale for all of them.
The protocol does not recompute strain or local rotations. It only harmonizes
the visualization of existing results.
## Inputs and General Workflow
The input is a set of previous **Xmipp volume strain** protocol runs.
For each selected run, the protocol reads the strain and local-rotation result
maps produced by that run. It computes the overall minimum and maximum values
across all selected runs.
It then creates ChimeraX command files for each run. These files open the
corresponding final volume and the associated strain or local-rotation map, and
apply a common rainbow color scale using the global minimum and maximum values.
This produces comparable visualizations across all selected strain analyses.
## Input Strain Calculations
The **input strain calculations** parameter should contain several completed
Xmipp volume-strain runs.
Each selected run is expected to contain the standard output files generated by
the strain protocol, including:
- the final volume used for visualization;
- the local-rotation map;
- the strain map.
This protocol assumes that those files already exist. If one of the selected
runs is incomplete or does not contain the expected output files, the
normalization cannot be performed correctly.
The selected runs should be comparable in biological and processing terms. For
example, they may correspond to different conformational transitions of the
same molecular system or to different reconstructions analyzed with the same
strain workflow.
## Local Rotation Normalization
The protocol first normalizes the visualization of the **local rotation** maps.
For all selected runs, it reads the local-rotation result volume and determines
the global minimum and maximum values. These values define a common color range
for all local-rotation visualizations.
The resulting ChimeraX files make it possible to inspect local rotation across
different runs using the same color scale.
This is important because local rotations can otherwise appear artificially
larger or smaller depending only on the automatic scaling used in the viewer.
## Strain Normalization
The protocol also normalizes the visualization of the **strain** maps.
As with local rotation, it reads the strain result volume from each selected
run and computes the overall minimum and maximum values across all runs. These
global limits are then used to generate ChimeraX visualization commands.
This makes strain patterns visually comparable. A given color corresponds to
the same strain value in all selected runs.
This is particularly useful when comparing whether one conformational change
shows stronger local deformation than another, or whether strain is localized
in similar regions across different analyses.
## ChimeraX Output Files
For each selected strain-analysis run and for each quantity, local rotation and
strain, the protocol writes a ChimeraX command file.
Each command file opens the corresponding final volume and the associated
strain or local-rotation map. The scalar map is hidden as a separate volume and
used to color the final volume surface with a common color scale.
The color map is a rainbow scale, applied over the global minimum and maximum
range computed from all selected runs. Colors are reversed so that the visual
convention is consistent with the command generated by the protocol.
These ChimeraX files are the main practical output of the protocol.
## Why Common Color Scaling Matters
Common color scaling is essential when comparing several scalar maps.
If two strain maps are displayed with independent automatic scales, a red
region in one map may correspond to a very different numerical value from a red
region in another map. This can lead to incorrect visual conclusions.
By forcing all selected runs to use the same minimum and maximum range, this
protocol makes visual comparison more meaningful.
The protocol is therefore especially useful for figures, reports, qualitative
comparisons, and exploratory interpretation of multiple strain analyses.
## Interpretation of the Results
The protocol does not change the underlying strain or local-rotation values.
It only changes how they are visualized.
After normalization, differences in color intensity between runs more directly
reflect differences in the numerical values of the corresponding scalar maps.
However, interpretation still requires care. Stronger colors may reflect larger
computed strain or rotation, but the biological meaning depends on the quality
of the input volumes, the reliability of the deformation analysis, and the
validity of comparing the selected runs.
## Practical Recommendations
Use this protocol after running several volume-strain analyses that you want to
compare visually.
Select only runs that are biologically and methodologically comparable. Mixing
unrelated systems or very different processing conditions may make the common
scale difficult to interpret.
Use the generated ChimeraX command files to produce consistent figures across
all selected runs.
Remember that this protocol normalizes visualization ranges, not the data
themselves. The original strain and local-rotation maps remain unchanged.
Inspect both the strain and local-rotation visualizations. They describe
different aspects of the deformation field and may highlight different
regions.
## Final Perspective
Normalize Strain is a visualization-normalization protocol for comparing
several previous strain-analysis results.
For biological users, its main value is interpretability. It ensures that color
differences across multiple strain or local-rotation maps correspond to a
shared numerical scale rather than to independent viewer settings.
This makes the protocol particularly useful when preparing comparative
figures, evaluating multiple conformational transitions, or presenting strain
analysis results in a consistent and visually reliable way.
"""
_label = 'normalize strain'
_lastUpdateVersion = VERSION_1_1
def __init__(self, **args):
ProtAnalysis3D.__init__(self, **args)
def _defineParams(self, form):
form.addSection(label='Input')
form.addParam('inputRuns', MultiPointerParam, pointerClass='XmippProtVolumeStrain',
label="input strain calculations",
help='Select the runs of strain calculations to be normalized')
#--------------------------- INSERT steps functions --------------------------------------------
def _insertAllSteps(self):
self._insertFunctionStep('normalize',"localrot")
self._insertFunctionStep('normalize',"strain")
[docs] def normalize(self,what):
# Get overall minimum and maximum
V=emlib.Image()
minAll=1e38
maxAll=-1e38
for prot in self.inputRuns:
protId=prot.get().getObjId()
protDir=prot.get()._getPath('')
fnVol=os.path.join(protDir,"extra","result_%s.mrc"%what)
V.read(fnVol)
_, _, minVal, maxVal = V.computeStats()
minAll = min(minAll,minVal)
maxAll = max(maxAll,maxVal)
# Write the Chimera file
for prot in self.inputRuns:
protId=prot.get().getObjId()
protDir=prot.get()._getPath('')
fnRoot=os.path.relpath(os.path.join(protDir,"extra","result"),self._getPath(''))
scriptFile = self._getPath('%d_result_%s_chimera.cxc'%(protId,what))
fhCmd = open(scriptFile, 'w')
fhCmd.write("open %s\n" % (fnRoot+"_final.mrc"))
fhCmd.write("open %s\n" % (fnRoot+"_%s.mrc"%what))
fhCmd.write("vol #1 hide\n")
fhCmd.write("scolor #0 volume #1 cmap rainbow cmapRange %f,%f reverseColors True\n"%(minAll,maxAll))
fhCmd.close()