Structure blurring
******************

All functions used to generate simulated maps from
protein models, and to generate other 3D volumes, such as masks are found in
TEMPy.protein.structure_blurrer.

TEMPy contains multiple methods for generating (or blurring) simulated maps.
Most of these methods generate simulated maps by modelling density around each
atom as a 3D gaussian; a simulated map is generated by summing the guassians
for all atoms in a model. This calculation can be done in fourier space using
:meth:`gaussian_blur <TEMPy.protein.structure_blurrer.StructureBlurrer.gaussian_blur>`
, or in real space using
:meth:`gaussian_blur_real_space <TEMPy.protein.structure_blurrer.StructureBlurrer.gaussian_blur_real_space>`
.

In version 2.0.0, we introduced a new implementation for TEMPy real space
blurring, using the `voxcov library <https://pypi.org/project/voxcov/>`_.
This implementation is significantly faster to calculate than the original
method for better than 10A maps. To use this new implementation, initialise a StructureBlurrer
object with the :code:`with_vc` keyword argument set to True (see below).

Structure Blurring Code Example
++++++++++++++++++++++++++++++++++++

For example, to score a model (here GroEL model 7bpx.pdb, from map EMDB entry
EMD-13308 solved at 3.4 A resolution) by CCC, one can use
guassian_blur_real_space to generate a simulated map (see below) which is used
to calculate the CCC using TEMPy's implementation:

.. doctest::
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
  
   >>> from TEMPy.protein.structure_parser import PDBParser
   >>> from TEMPy.maps.map_parser import MapParser
   >>> from TEMPy.protein.scoring_functions import ScoringFunctions
   >>> from TEMPy.protein.structure_blurrer import StructureBlurrer
   >>>
   >>> model = PDBParser.read_PDB_file("1CS4", "../tests/test_data/1CS4.pdb")
   >>> exp_map = MapParser.readMRC("../tests/test_data/1CS4.mrc")
   >>> map_resolution = 8.0
   >>> blurrer = StructureBlurrer(with_vc=True)  # use fast real-space blurring
   >>> sim_map = blurrer.gaussian_blur_real_space(
   ...     model,
   ...     map_resolution,
   ...     exp_map
   ... )
   >>>
   >>> # The simulated map should have the same dimensions as the experimental map
   >>> sim_map.box_size() == exp_map.box_size()
   True
   >>>
   >>> sim_map.apix == exp_map.apix
   array([ True,  True,  True])
   >>>
   >>> # We can now see how well the simulated map correlates with the experimental map
   >>> scorer = ScoringFunctions()
   >>> ccc_score = scorer.CCC(exp_map, sim_map)

For now, all simulated maps are generated using a single, global resolution
value. Future updates will introduce the capability to blur maps based on
atom B-factors, or based on local resolution in cryo-EM maps.



Note on real space blurring:
++++++++++++++++++++++++++++++++++++

All real space blurring functions require a :code:`sigma_coeff` argument, that
defines the width of the Gaussian (multiplied by the map resolution) for each
atom. In TEMPy, there are multiple options for the :code:`sigma_coeff` value,
each derived from a specific publication. When no :code:`sigma_coeff` value is
provided 0.356 is typically used.

Available :code:`sigma_coeff` values:

    * 0.187R corresponding with the Gaussian width of the Fourier
      transform falling to half the maximum at 1/resolution, as
      used in Situs (Wriggers et al, 1999);

    * 0.225R which makes the Fourier transform of the
      distribution fall to 1/e of its maximum value at wavenumber
      1/resolution the default in Chimera (Petterson et al, 2004)

    * 0.356R corresponding to the Gaussian width at 1/e maximum
      height equaling the resolution, an option in Chimera
      (Petterson et al, 2004);

    * 0.425R the fullwidth half maximum being equal to the
      resolution, as used by FlexEM (Topf et al, 2008);

    * 0.5R the distance between the two inflection points being
      the same length as the resolution, an option in Chimera
      (Petterson et al, 2004);

    * 1R where the sigma value simply equal to the resolution,
      as used by NMFF (Tama et al, 2004).

For more details refer to the API reference: Link.