.. include:: substitutions
.. include:: ../apps-substitutions

.. _chapter_grid_comp:

*********************************
GridComp
*********************************

=================================
Overview
=================================

The **GridComp** utility reads grids,
from an OEBinary file (*.oeb* or *.oeb.gz*) generated by
:ref:`chapter_szmap`, or from an individual grid file,
and performs an operation, usually producing a grid file
containing the results. It is designed to make it easy to compare
grids and produce new types of grids by combining others. It handles
grids with different shapes or that do not completely overlap and will
interpolate if the grid points are not aligned.

**GridComp** can compute the sum, difference, average and other
mathematical transformations of grids. The operations *set_above*,
*set_below*, *mask*, and *not_mask* are used to truncate grids.

The operations *total* and *integrate* are the only ones that do
not require an output grid. They write summary statistics describing a grid to
standard output.

The operations *lig_disp* and *prot_disp* take a :ref:`chapter_szmap`
results OEBinary file and produce another OEBinary file containing
additional results for the region in the *apo* pocket displaced by the ligand when the complex
if formed or the region around the ligand displaced by the protein in the complex, respectively.

The operations *mask_all* and *stabilization* also processes an OEBinary file to produce another.

=================================
Example Commands
=================================

A common operation is to append data to :ref:`chapter_szmap` output
for the region in the *apo* protein where the ligand
displaces solvent in the complex:

::

   > grid_comp -op lig_disp -i 4std_stbl.oeb.gz -o 4std_stbl_disp.oeb.gz

:ref:`chapter_szmap` output contains masks that can be used, for example, to define
the region that the *integrate* operation sums over:

::

   > grid_comp integrate my.oeb.gz     free_energy_grid same mask_grid > int.txt
   > grid_comp integrate my.oeb.gz apo_free_energy_grid same mask_grid >>int.txt
   > grid_comp integrate my.oeb.gz lig_free_energy_grid same mask_grid >>int.txt

In the example above, the complex *mask_grid* is used for all integrations
so that the results can be combined to yield a solvent correction to *ZAP bind*:
(*complex* + *bulk*) - (*apo* + *ligand*), 
where *bulk* = 0.0. The free energy grids used,
which are not the same as the *difference* free energy grids,
are only available if **SZMAP** is run with the option ``-results_set max``.
Usually, the grid *file* and the grid *name* are specified in pairs.
The keyword ``same`` used in the example above refers to the same file as the
energy grid, *my.oeb.gz*, and is just used for convenience.

The following command creates a mask file defining regions where the
van der Waals energy in the complex is less than or equal to -2 kcal/mol (*low.grd.gz*)
and applies the mask to the complex neutral difference free energy grid to produce
the file *nddG.grd.gz* containing a subset of that grid:

::

   > grid_comp -leq -2.0 make_mask my.oeb.gz vdw_grid same point_grid low.grd.gz
   > grid_comp mask my.oeb.gz neut_diff_free_energy_grid low.grd.gz na nddG.grd.gz

The keyword ``na`` stands for not-applicable and is a convenience used to skip the grid_name field
(which is not needed because the file *low.grd.gz* contains only one grid),
allowing all the parameters to be specified without having to sprinkle the command line
with a large number of -flags.

=================================
Command Line Help
=================================

A description of the command line interface can be obtained by executing **GridComp**
with the `--help` option.

.. code-block:: console
   
   > grid_comp --help

will generate the following output:

::

   Help functions:
     grid_comp --help simple      : Get a list of simple parameters
     grid_comp --help all         : Get a complete list of parameters
     grid_comp --help defaults    : List the defaults for all parameters
     grid_comp --help <parameter> : Get detailed help on a parameter
     grid_comp --help html        : Create an html help file for this program
     grid_comp --help versions    : List the toolkits and versions used in the application


=================================
Required Parameters
=================================

.. option:: -operation <value>
   -op <value>

   [keyless parameter 1]

   Operation to be performed on grid(s). The *scale* operation
   scales by :option:`-scale`. Operations *set_above*
   and *set_below* use cutoff values of :option:`-cutoff`
   and set values to :option:`-new_value`. The *total* and *integrate*
   operations treat :option:`-input_file2` / :option:`-grid2`
   as a mask (mask values above
   :option:`-masked_point_cutoff` are summed) and write the result
   to standard output. If an optional third (point) grid is supplied
   for *total* and *integrate*, the second grid is treated as an energy
   grid and the mask is built on-the-fly.

   ============= ====== ============================================
   Value         Type   Operation                                   
   ============= ====== ============================================
   sum           binary Sum of the two grid values                  
   ------------- ------ --------------------------------------------
   diff          binary Difference of the two grid values           
   ------------- ------ --------------------------------------------
   min           binary Minimum of the two grid values              
   ------------- ------ --------------------------------------------
   max           binary Maximum of the two grid values              
   ------------- ------ --------------------------------------------
   avg           binary Average of the two grid values              
   ------------- ------ --------------------------------------------
   mul           binary Multiply the two grid values                
   ------------- ------ --------------------------------------------
   total         binary Display total of values within mask         
   ------------- ------ --------------------------------------------
   integrate     binary Display integral of values within mask      
   ------------- ------ --------------------------------------------
   make_mask     binary Build a mask from value and point grids     
   ------------- ------ --------------------------------------------
   mask          binary Keep values only in masked regions          
   ------------- ------ --------------------------------------------
   not_mask      binary Keep values only outside of masked regions  
   ------------- ------ --------------------------------------------
   lig_disp      binary Add apo data displaced in complex by ligand 
   ------------- ------ --------------------------------------------
   prot_disp     binary Add lig data displaced in complex by protein
   ------------- ------ --------------------------------------------
   scale         unary  Multiply values by scale factor             
   ------------- ------ --------------------------------------------
   offset        unary  Add an offset to each grid value            
   ------------- ------ --------------------------------------------
   set_above     unary  Modify values that are above cutoff         
   ------------- ------ --------------------------------------------
   set_below     unary  Modify values that are below cutoff         
   ------------- ------ --------------------------------------------
   largest       unary  Grid subset within the largest contour      
   ------------- ------ --------------------------------------------
   stabilization unary  Calculate stabilization grids               
   ------------- ------ --------------------------------------------
   mask_all      unary  Build and apply a mask to all grids         
   ============= ====== ============================================

   Binary operations require two grids and unary operations
   require only one. The *lig_disp*, *prot_disp*, *mask_all*,
   and *stabilization* operations work on the entire
   set of grids in the *.oeb* input file and do not take
   a grid name. They do, however, require the output file to
   be an *.oeb* file.

   The operations *total* and *integrate* send numerical results to
   *standard-out* but can also optionally write an output grid if a
   mask is calculated on-the-fly.

   The operation *largest* makes contour surfaces based on :option:`-cutoff`
   and suppresses values outside of the largest contour region.

.. option:: -input_file1 <filename>
   -in1 <filename>
   -i <filename>

   [keyless parameter 2]

   Grid file to operate on. If an OEBinary file is used,
   :option:`-grid1` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid1`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================



=================================
Optional Parameters
=================================

Grid Options
------------

.. option:: -grid1 <name>

   [keyless parameter 3]

   Grid in OEBinary input_file1 to operate on. 
   
   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is in a separate grid file and not attached to an OEBinary file.

.. option:: -input_file2 <filename>
   -in2 <filename>

   [keyless parameter 4]

   Grid file to operate on. If an OEBinary file is used,
   :option:`-grid2` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid2`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================

   A value of *same* is used to refer to the same file as :option:`-input_file1`.

   A value of *na* is used with keyless options when :option:`-input_file2`
   is not required.

.. option:: -grid2 <name>

   [keyless parameter 5]

   Grid in OEBinary input_file2 to operate on.

   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is not an OEBinary file or the grid will not be used.

.. option:: -input_file3 <filename>
   -in3 <filename>

   Grid file to operate on. Contains the (point) grid
   required when :option:`-leq_mask` or :option:`-geq_mask`
   is used with operation ``total`` or ``integrate``
   to create the mask on the fly.

   If an OEBinary file is used,
   :option:`-grid3` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid3`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================

   A value of *same* is used to refer to the same file as :option:`-input_file2`.

   A value of *na* is used with keyless options when :option:`-input_file3`
   is not required.

.. option:: -grid3 <name>

   Grid in OEBinary input_file3 to operate on.

   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is not an OEBinary file or the grid will not be used.

.. option:: -output_grid <filename>
   -o <filename>

   [keyless parameter 6]

   Not used with the operations: *total* and *integrate*.

   The file format of the output grid file is automatically determined from
   the file extension.

   =============== ===========================
   File type       Extension                  
   =============== ===========================
   OE grid         .grd .grd.gz               
   --------------- ---------------------------
   Grasp grid      .phi .phi.gz               
   --------------- ---------------------------
   Ascii grid      .agd .agd.gz               
   --------------- ---------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz  
   .ccp4 .ccp4.gz                            
   =============== ===========================

   For ``remask`` operation, the file must be in OEBinary format (with extension .oeb or .oeb.gz).

Parameter Options
-----------------

.. option:: -leq_mask <number>
   -leq <number>

   When generating a mask for the operations ``total`` and
   ``integrate``,
   values in grid2 equal to or less than this are counted as
   in the mask if the value of the corresponding point in grid3 is > 
   :option:`-masked_point_cutoff`.
   Grid2 is often the ``intvdw_grid`` and grid3 is often ``point_grid``.

   When used with the operation ``make_mask``, values of grid1 equal to
   or less than this are counted in the mask if the value of the 
   corresponding point
   in grid2 is > :option:`-masked_point_cutoff`.

   When used with the operation ``mask_all``, values of *intvdw_grid*,
   *apo_intvdw_grid* and *lig_intvdw_grid* equal to
   or less than this are counted in the mask if the value of the corresponding point
   in *point_grid*, *apo_point_grid* or *lig_point_grid* is greater than :option:`-masked_point_cutoff`.

.. option:: -geq_mask <number>
   -geq <number>

   When generating a mask for the operations ``total`` and
   ``integrate``,
   values in grid2 equal to or greater than this are counted as
   in the mask if the value of the corresponding point in grid3 is 
   > :option:`-masked_point_cutoff`.
   Grid2 is often the ``intvdw_grid`` and grid3 is often ``point_grid``.

   When used with the operation ``make_mask``, values of grid1 equal to
   or greater than this are counted in the mask if the value of the 
   corresponding point
   in grid2 is > :option:`-masked_point_cutoff`.

   When used with the operation ``mask_all``, values of *intvdw_grid*,
   *apo_intvdw_grid* and *lig_intvdw_grid* equal to
   or greater than this are counted in the mask if the value of the corresponding point
   in *point_grid*, *apo_point_grid* or *lig_point_grid* is greater than :option:`-masked_point_cutoff`.

.. option:: -cutoff <number>

   Cutoff value for *set_above*, *set_below*, and *largest* operations.

   [Default=0.0]

.. option:: -masked_point_cutoff <number>

   Cutoff value for the mask. Mask values greater than this are selected.
   The (strict) default selects both calculation (1.01) and solvent (0.99) points.

   [Default=0.98]

.. option:: -new_value <number>
   -to <number>

   Value assigned to values beyond the cutoff with the
   *set_above* and *set_below* operations.

   [Default=0.0]

.. option:: -by <number>
   -scale <number>

   Amount grid values are multiplied by with the *scale* operator
   or amount added to grid values with the *offset* operator.

   [Default=1.0]

.. option:: -default_value <number>
   -default <number>

   Value assigned to points where grids do not overlap
   and assigned to unselected points during *mask* and *mask_all*
   operations.

   [Default=0.0]

.. option:: -int_method <value>
   -method <value>

   Method used when performing the integrate operation.

   ========= ========================================================
   Value     Meaning                                                 
   ========= ========================================================
   voxel     Sum masked values and scale by grid voxel/water volume  
   --------- --------------------------------------------------------
   average   Average masked values and scale by excluded/water volume
   --------- --------------------------------------------------------
   grow      Grow edge values into the excluded volume and average   
   ========= ========================================================

   [Default=voxel]

.. option:: -mask_vdw

   Override behavior of ``mask_all`` operation to use *vdw_grid*
   rather than *intvdw_grid*, etc.

Other Options
-------------

.. option:: -verbose
   -v

   Print additional grid details to *standard-error*.
