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

.. _chapter_szmap_grid:

*********************************
SzmapGrid
*********************************

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

The :program:`szmap_grid` utility reads an OEBinary (*.oeb* or *.oeb.gz*) file
generated by :ref:`chapter_szmap` and displays information about the grids within.
If atom property tags from a :ref:`chapter_szmap` ``-at_coords`` calculation are found,
it will list the all property names.

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

::

   > szmap_grid 4std_stbl.oeb.gz 

   szmap-meta-data attached to molecule 1, 'complex: PROTEIN (SCYTALONE DEHYDRATASE) + residue 'BFS''.
   'mask_grid' dimensions: 38 29 33
   'neut_diff_free_energy_grid' dimensions: 38 29 33
   'vdw_grid' dimensions: 38 29 33
   'order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 2, 'ligand: residue 'BFS''.
   'lig_mask_grid' dimensions: 38 29 33
   'neut_diff_lig_free_energy_grid' dimensions: 38 29 33
   'lig_vdw_grid' dimensions: 38 29 33
   'lig_order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 3, 'apo: PROTEIN (SCYTALONE DEHYDRATASE)'.
   'apo_mask_grid' dimensions: 38 29 33
   'neut_diff_apo_free_energy_grid' dimensions: 38 29 33
   'apo_vdw_grid' dimensions: 38 29 33
   'apo_order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 4, 'stabilization'.
   'stbl_mask_grid' dimensions: 38 29 33
   'neut_diff_stbl_free_energy_grid' dimensions: 38 29 33
   'stbl_vdw_grid' dimensions: 38 29 33
   'stbl_order_grid' dimensions: 38 29 33

   Input appears to be the results file from a SZMAP grid calculation.
   SZMAP grids but no -at_coords property tags in input file.

   > szmap_grid 2w3a_coords.oeb.gz 

   szmap-meta-data attached to molecule 1, 'apo: TOP'.
   atom property tags: szmap_mask, szmap_neut_diff_free_energy, szmap_neut_diff_enthalpy,
   szmap_neut_diff_entropy, szmap_vdw, szmap_order, szmap_vac_diff_free_energy,
   szmap_vac_diff_enthalpy, szmap_vac_diff_entropy, szmap_free_energy, szmap_enthalpy,
   szmap_entropy, szmap_neutral_free_energy, szmap_neutral_enthalpy,
   szmap_neutral_entropy, szmap_interaction, szmap_psolv, szmap_wsolv, szmap_intvdw,
   szmap_probe_burial, szmap_clash

   szmap-meta-data attached to molecule 2, 'apo: DIHYDROFOLATE REDUCTASE+ion+cofact'.

   Input appears to be the results file from a SZMAP -at_coords calculation.
   SZMAP -at_coords property tags but no grids in input file.


:program:`szmap_grid` can also split a given grid out into a separate grid file. The
output grid can be in OEBinary, Grasp, CCP4, or ascii format. Since *PyMOL*
can read Grasp *.phi* maps, they provide a way to transfer grids from :ref:`chapter_szmap` to *PyMOL*.

::

   > szmap_grid 4std_stbl.oeb.gz neut_diff_apo_free_energy_grid 4std_nddG.phi

The options ``-output_all_format`` and ``-prefix`` will generate a separate grid file
for all grids in the :ref:`chapter_szmap` results.

::

   > szmap_grid -output_all_format .phi -prefix 4std 4std_stbl.oeb.gz

If the :program:`szmap_grid` option ``-at_coords`` is used,
the specified grid's values will be interpolated
at the coordinates of any atoms in the input coordinates file and written out attached to those atoms
in a file defined by :option:`-mol` for use by other tools.
A tab-delimited table of these results is written to *standard-output*.

::

   > szmap_grid -at_coords coords.sdf -mol out.oeb szmap.oeb.gz vdw_grid >table.txt

.. note::

   A direct calculation at these coordinates using
   :ref:`chapter_szmap` will be superior to these interpolated values.

Meta-data
================================================================================

:ref:`chapter_szmap` attaches meta-data to molecules in the results file that documents run conditions.
This data is displayed when the :program:`szmap_grid` option :option:`-verbose` is used.

::

   szmap-meta-data attached to molecule 1, 'complex: PROTEIN (SCYTALONE DEHYDRATASE) + residue 'BFS''.

   points: grid
   system: complex
   prot-title: PROTEIN (SCYTALONE DEHYDRATASE)
   prot-num-atoms: 2680
   prot-num-bonds: 2720
   lig-title: residue 'BFS'
   lig-num-atoms: 33
   lig-num-bonds: 34
   dielectric-model: gaussian
   eps-outer: 80
   eps-inner: 1
   salt-conc: 0.05M
   probe-type: water
   orientations: 60
   rotation-matrices: symmetrical
   mask-cutoff: 0
   mask: calculation=1.01
   mask: bulk solvent=0.99
   mask: clash=0
   grid-spacing: 0.5A
   zap-spacing: 0.5A
   zap-iters: 5
   run-date: Jan 23 2013
   run-time: 10:48:03
   version: 20130123
   release: 1.1.1
   arch: redhat-RHEL5-x64
   platform: redhat-RHEL5-g++4.1-x64
   licensee: Initech
   site: Austin

The meta-data includes the version and release of :ref:`chapter_szmap` used to generate
the results. Early releases used a different format, ``version: 110`` for version 1.1.0.

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

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

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

will generate the following output:

::

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


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

.. option:: -input_mol <filename>
   -i <filename>

   [keyless parameter 1]

   OEBinary input file (*.oeb* or *.oeb.gz*), with calculated
   grids attached to copy input molecule(s).



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

Grid Options
==============

.. option:: -grid <name>
   -g <name>

   [keyless parameter 2]

   Grid to extract or display information about. Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   If not specified, information will be displayed about all grids.

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

   [keyless parameter 3]

   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                            
   ============== ===========================

   Use :option:`-output_all_format` instead to write all grids into separate files.

.. option:: -output_all_format <format>
   -all <format>

   Write out every grid to individual files in the specified format.
   Used in conjunction with :option:`-prefix`.

   ============== ===========================
   File type      Format                     
   ============== ===========================
   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                            
   ============== ===========================

.. option:: -prefix <text>

   Filename prefix for grid files written when :option:`-output_all_format` is specified.
   Can include file path in addition to the beginning portion of the filename.

   [Default=szmap_grid]

.. option:: -slice

   Print grid values to *standard-output* as a series of 2D tabular slices.

.. option:: -std_box <filename>

   Write *standard* (complex) grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -lig_box <filename>

   Write *ligand* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -apo_box <filename>

   Write *apo* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -box_mol <filename>

   Write *box_mol* bounding box to
   output 'box molecule' coordinate file,
   if a *box_mol* is found in the input *.oeb*
   file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

Interpolation Options
=======================

.. option:: -at_coords <filename>
   -coords <filename>

   Interpolate the values of the selected grid
   (and the corresponding mask grid) at the coordinates
   of atoms in any molecules in the file. Write
   those molecules, with the (masked) results attached
   to the atoms, to the output file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   One of the following tags will be used when assigning
   values to atoms (without any ``apo_`` or ``lig_``):
   
   + *szmap_mask*
   + *szmap_neut_diff_free_energy*
   + *szmap_neut_diff_enthalpy*
   + *szmap_neut_diff_entropy*
   + *szmap_vac_diff_free_energy*
   + *szmap_vac_diff_enthalpy*
   + *szmap_vac_diff_entropy*
   + *szmap_free_energy*
   + *szmap_enthalpy*
   + *szmap_entropy*
   + *szmap_neutral_free_energy*
   + *szmap_neutral_enthalpy*
   + *szmap_neutral_entropy*
   + *szmap_interaction*
   + *szmap_psolv*
   + *szmap_wsolv*
   + *szmap_vdw*
   + *szmap_intvdw*
   + *szmap_probe_burial*

.. option:: -output_mol <filename>
   -mol <filename>

   OEBinary output file (*.oeb* or *.oeb.gz*), with interpolated
   grid values attached to :option:`-at_coords` molecule's atoms.

   [Default=szmap_grid_interp.oeb.gz]

.. option:: -no_table

   Do not print a tab-delimited table of interpolated grid values to
   *standard-output* when :option:`-at_coords` is the selection.

.. option:: -mask_cutoff <number>

   Points where interpolated mask values are less than or equal to this cutoff
   will have values attached to atoms set to 0.0. The default
   value tries to account for the edges of the masked area where
   interpolation can generate distorted results.

   [Default=0.8]

Other Options
===============

.. option:: -verbose
   -v

   Print additional grid details (and *SZMAP* meta-data) to *standard-output*.
