# GridComp¶

## Overview¶

The GridComp utility reads grids, from an OEBinary file (.oeb or .oeb.gz) generated by 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 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 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


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.

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

-operation <value>
-op <value>

[keyless parameter 1]

Operation to be performed on grid(s). The scale operation scales by -scale_factor. Operations set_above and set_below use cutoff values of -cutoff and set values to -new_value. The total and integrate operations treat -input_file2 / -grid2 as a mask (mask values above -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
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

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 -cutoff and suppresses values outside of the largest contour region.

-input_file1 <filename>
-in1 <filename>
-i <filename>

[keyless parameter 2]

Grid file to operate on. If an OEBinary file is used, -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 -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¶

-grid1 <name>

[keyless parameter 3]

Grid in OEBinary input_file1 to operate on.

Name must be one of the grid names listed in Appendix 1: SZMAP Grids.

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.

-input_file2 <filename>
-in2 <filename>

[keyless parameter 4]

Grid file to operate on. If an OEBinary file is used, -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 -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 -input_file1.

A value of na is used with keyless options when -input_file2 is not required.

-grid2 <name>

[keyless parameter 5]

Grid in OEBinary input_file2 to operate on.

Name must be one of the grid names listed in Appendix 1: SZMAP Grids.

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

-input_file3 <filename>
-in3 <filename>

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

If an OEBinary file is used, -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 -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 -input_file2.

A value of na is used with keyless options when -input_file3 is not required.

-grid3 <name>

Grid in OEBinary input_file3 to operate on.

Name must be one of the grid names listed in Appendix 1: SZMAP Grids.

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

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

-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 > -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 > -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 -masked_point_cutoff.

-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 > -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 > -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 -masked_point_cutoff.

-cutoff <number>

Cutoff value for set_above, set_below, and largest operations.

[default = 0.0]

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]

-new_value <number>
-to <number>

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

[default = 0.0]

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

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

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

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

### Other Options¶

-verbose
-v

Print additional grid details to standard-error.