.. _faq_difference_maps:

Difference FragMaps
-------------------

The difference between SILCS FragMaps of structurally similar proteins can 
provide insights into differences in their activities. The SilcsBio software 
provides a utility in the command line interface (CLI) to calculate the difference 
between two SILCS FragMaps. The resulting difference FragMaps are a powerful 
tool to qualitatively analyze the difference between the functional group affinity
pattern on two similar proteins including, but not limited to, kinases, BCL2 proteins, 
and mutants of the same protein. 

A qualitiative analysis to investigate the differences in similar proteins may be 
accomplished by visualizing the difference FragMaps, which will offer
insights into regions of the protein more favorable or less favorable for
certain functional groups. Such information may be used to design molecules
highly specific for only one protein (or dual specific for both proteins)
or facilitate the identification and design of agonists versus antagonists,
such as for GPCRs. 
See references :cite:`Lakkaraju:2015` or :cite:`Lanning:2016` for example
applications of difference FragMaps. The two-step procedure for calculating difference 
FragMaps is described below.

1. Copy the two ``silcs_fragmaps_<protein PDB>`` directories you wish to use to a new directory 
   in which the difference calculations will be performed.

   Please make sure that the FragMaps meet *one* of the following criteria:

   - Both sets of FragMaps have the same grid setup, which means the
     header of the ``silcs_fragmaps_<protein PDB>/maps/*.map`` files are the same.
   - Both sets of FragMaps have were created relative to proteins having the
     same rotational and translational alignments. If the input proteins were
     not aligned to each other prior to running SILCS, you must use the **"ref="**
     option with the ``2b_gen_maps`` command to ensure alignment. A map cutting
     algorithm will be used to make the FragMaps compatible, with the smaller
     dimensions of the two grids used to calculate the difference FragMaps.

   .. warning::

      It is imperative that the two SILCS FragMaps used to calculate 
      difference FragMaps are oriented to structurally aligned proteins. 
      Difference FragMaps that result from incompatible FragMaps will not 
      provide any useful insights. 


2. Generate the difference FragMaps using the following command:

   ::

      $SILCSBIODIR/utils/calc_difference_maps.sh <silcs_fragmaps_#1> <silcs_fragmaps_#2>

   The difference FragMaps will be saved in a directory
   ``DIFF_MAPS_<fragmap#1>_VS_<fragmap#2>`` and can be visualized in the same way
   as standard FragMaps (:ref:`visualize_fragmaps`). 

.. tip::

   The difference in GFE values are calculated as ``<silcs_fragmap_#1>`` - ``<silcs_fragmap_#2>``.
   In the difference FragMaps, if the value at a grid point is negative, the
   grid free energy (GFE) of the grid point in ``<silcs_fragmap_#1>`` is more favorable
   than in ``<silcs_fragmap_#2>`` and if it is positive, then ``<silcs_fragmap_#2>`` is more favorable
   than ``<silcs_fragmap_#1>``.

.. note::

   The difference FragMaps are intended *ONLY* for visualization and *NOT* for any
   quantitative calculations.