Introduction

We here present a new computer program called HBonanza (hydrogen-bond analyzer) that aids the analysis and visualization of hydrogen-bond networks. HBonanza, which can be used to analyze single structures or the many structures of a molecular dynamics simulation, is open source and python implemented, making it easily editable, customizable, and platform independent. Additionally, the algorithm is fast and easy to use. Unlike many other freely available hydrogen-bond analysis tools, HBonanza provides not only a text-based table describing the hydrogen-bond network, but also a Tcl script file to facilitate visualization in VMD, a popular molecular visualization program. Visualization in other programs is also possible.

Download

HBonanza is a Python script, and so requires a Python interpreter. The program has been tested on Linux, Mac OSX, and Windows. Download a copy of HBonanza here.

Tutorial

Introduction

HBonanza is a computer program that can be used to perform hydrogen-bond analyses of molecular dynamics trajectories. It accepts a PDB file of the trajectory as input, and outputs a TCL visualization script that can be loaded into VMD using either the Tk Console or the -e option from the command line. Trajectory files in other formats can be converted to the PDB format easily using VMD's "Save Coordinates..." option. The generated TCL file also contains comments to aid the user if he or she wishes to use other molecular visualization software.


Command-line Parameters

A number of command-line options are available:

-help Displays this help documentation.
-trajectory_filename The filename containing the trajectory, in PDB format.
-output_basename The initial string used to begin the names of all output files.
-single_frame_filename The filename of a PDB containing a single frame, onto which hydrogen bond visualization will be mapped.
-number_processors The number of processors to use when performing the hydrogen-bond analysis of the trajectory. By default, all processors on the system are used.
-hydrogen_bond_frequency_cutoff In creating visualization files, discard all hydrogen bonds that are formed less frequently than this value.
-hydrogen_bond_distance_cutoff Consider only hydrogen bonds whose donor-acceptor distances are less than or equal to this value.
-hydrogen_bond_angle_cutoff Consider only hydrogen bonds whose hydrogen-donor-acceptor angles are less than or equal to this value.
-just_immediate_connections Rather than branching out recursively to identify the entire hydrogen-bond network that supports the seed residues, consider only those residues that are immediately connected to the seeds via hydrogen bonds.
-seed_residues or -seed_residue Consider only hydrogen bonds connected to residues with these IDs, or connecting residues that connect to these residues through hydrogen bonds. Multiple seed residues can be specified by evoking this tag multiple times (see example below). If no seed residues are specified, the program will visualize all hydrogen bonds, regardless of connectivity.
-write_column The program writes a PDB file containing the hydrogen-bond frequencies in either the occupancy or beta columns. If this tag is set to "O", the frequencies are written to the occupancy column. If set to "B", they are written to the beta column.
-low_frequency_color_r Hydrogen bonds are colored according to frequency. Colors are specified using RGB (red, green, blue) values. This tag specifies the R value of the color associated with the lowest frequency displayed (given by -hydrogen_bond_frequency_cutoff). Valid values range from 0 to 255.
-low_frequency_color_g The G value of the color associated with the lowest frequency displayed. Valid values range from 0 to 255.
-low_frequency_color_b The B value of the color associated with the lowest frequency displayed. Valid values range from 0 to 255.
-high_frequency_color_r The R value of the color associated with 100% persistent hydrogen bonds. Valid values range from 0 to 255.
-high_frequency_color_g The G value of the color associated with 100% persistent hydrogen bonds. Valid values range from 0 to 255.
-high_frequency_color_b The B value of the color associated with 100% persistent hydrogen bonds. Valid values range from 0 to 255.

Description of Output Files

Assuming the command-line parameter -output_basename is set to "output.", the following files will be created:

output.average_hbonds A two-column text file describing all hydrogen bonds in the trajectory, regardless of the -hydrogen_bond_frequency_cutoff tag. The first column is a triplet indicating the atom indices of the atoms that form each hydrogen bond, and the second column is the frequency with which that particular hydrogen bonds occurs across all the frames of the trajectory.
output.frame_by_frame_hbonds.csv A comma-separated-values file (CSV file) indicating which hydrogen bonds are present in each of the frames of the trajectory. CSV files can be loaded by a number of popular spreadsheet programs, including Microsoft Excel and Open Office Calc.
output.hbond_averages_in_occupancy_column.pdb
OR
output.hbond_averages_in_beta_column.pdb
A pdb file identical to the file specified by the -single_frame_filename tag, except that the average frequencies with which relevant hydrogen-bond atoms appear in hydrogen bonds across the trajectory are written in the occupancy or beta column, depending on the value given by the -write_column tag. This file may facilitate visualization in programs other than VMD, if desired.

Examples of Usage

Example 1: Load in a trajectory named "traj.pdb". Define hydrogen bonds to be those that 1) have donor-acceptor distances less than or equal to 3.0 angstroms, 2) have hydrogen-donor-acceptor angles less than or equal to 30 degrees, and 3) are formed in at least 50% of the trajectory frames. Show the visualization based on the coordinates in the single-frame PDB file "first_frame.pdb". Write output files using filenames that start with "output." One of these output filenames will be a PDB file with the hydrogen-bond frequencies listed in the occupancy column. Because no seed residues are specified, all hydrogen bonds in the trajectory will be visualized. Hydrogen bonds that appear in 50% of the trajectory frames will appear white, and those that appear in 100% of the trajectories frames will be green. The program output will be directed to the file "visualize.tcl" (in UNIX-based systems), which can then be visualized in VMD.

python HBonanza.py -trajectory_filename traj.pdb -hydrogen_bond_distance_cutoff 3.0 -hydrogen_bond_angle_cutoff 30 -hydrogen_bond_frequency_cutoff 0.5 -single_frame_filename first_frame.pdb -output_basename output. -write_column O -low_frequency_color_r 255 -low_frequency_color_g 255 -low_frequency_color_b 255 -high_frequency_color_r 0 -high_frequency_color_g 255 -high_frequency_color_b 0 > visualize.tcl

/path/to/VMD/executable/VMD -e visualize.tcl



Example 2: Same as above, except only hydrogen bonds connected to residues with IDs 156 and 234, or connecting residues that connect to these residues through hydrogen bonds, will be visualized.

python HBonanza.py -trajectory_filename traj.pdb -hydrogen_bond_distance_cutoff 3.0 -hydrogen_bond_angle_cutoff 30 -hydrogen_bond_frequency_cutoff 0.5 -single_frame_filename first_frame.pdb -output_basename output. -write_column O -low_frequency_color_r 255 -low_frequency_color_g 255 -low_frequency_color_b 255 -high_frequency_color_r 0 -high_frequency_color_g 255 -high_frequency_color_b 0 -seed_residue 156 -seed_residues 234 > visualize.tcl



Example 3: If the -single_frame tag is not specified, the program will automatically use the first frame from the trajectory specified by the -trajectory_filename tag.

python HBonanza.py -trajectory_filename traj.pdb -hydrogen_bond_distance_cutoff 3.0 -hydrogen_bond_angle_cutoff 30 -hydrogen_bond_frequency_cutoff 0.5 -output_basename output. -write_column O -low_frequency_color_r 255 -low_frequency_color_g 255 -low_frequency_color_b 255 -high_frequency_color_r 0 -high_frequency_color_g 255 -high_frequency_color_b 0 -seed_residue 156 -seed_residues 234 > visualize.tcl



Example 4: If an analysis has been performed previously, it's not necessary to specify the -single_frame and -trajectory_filename tags, as long as the same -output_basename and -write_column tags are used. The trajectory hydrogen-bond information will be read from the previously created file "{output_basename}.average_hbonds", and the -single_frame tag will be automatically set to the previously created "{output_basename}.hbond_averages_in_{write_column}*_column.pdb" file.

python HBonanza.py -hydrogen_bond_distance_cutoff 3.0 -hydrogen_bond_angle_cutoff 30 -hydrogen_bond_frequency_cutoff 0.5 -output_basename output. -write_column O -low_frequency_color_r 255 -low_frequency_color_g 255 -low_frequency_color_b 255 -high_frequency_color_r 0 -high_frequency_color_g 255 -high_frequency_color_b 0 -seed_residue 156 -seed_residues 234 > visualize.tcl

Sample Visualization

With only minor modifications, the default HBonanza output visualization file can be rendered as below. The ligand is shown in thick licorice, protein residues thought to participate in hydrogen-bond networks involving the ligand are shown in thin licorice, and the entire protein is shown in cartoon, colored according to secondary structure. Hydrogen bonds are colored in shades of green according to the frequency with which they appear in the many frames of the MD trajectory. The coloring ranges from white, those bonds present in 75% of the MD frames, to green, those bonds present in 100% of the frames.