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

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

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

-mask_vdw

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.