hist | histogram

Calculate N-dimensional histogram for N given data sets.

hist <dataset_name>[,<min>,<max>,<step>,<bins>] ... [free <temperature>] [norm | normint] [gnu] [circular] out <filename> [amd <amdboost_data>] [name <outputset name>] [traj3d <file> [trajfmt <format>] [parmout <file>]] [min <min>] [max <max>] [step <step>] [bins <bins>] [nativeout]

<dataset_name>[,<min>,<max>,<step>,<bins>] Dataset(s) to be histogrammed. Optionally, the min, max, step, and/or number of bins can be specified for this dimension after the dataset name separated by commas. It is only necessary to specify the step or number of bins, an asterisk ’*’ indicates the value should be calculated from available data.
[free <temperature>] If specified, estimate free energy from bin populations using , where is Boltzmann’s constant, T is the temperature specified by <temperature>, is the population of bin and is the population of the most populated bin. Bins with no population are given an artificial barrier equivalent to a population of 0.5.
[norm] If specified, normalize bin populations so the sum over all bins equals 1.0.
[normint] Normalize bin populations so the integral over them is 1.0.
[gnu] Internal output only; data will be gnuplot-readable, i.e. a space will be printed after the highest order coordinate cycles.
[circular] Internal output only; data will wrap, i.e. an extra bin will be printed before min and after max in each direction. Useful for e.g. dihedral angles.
out <filename> Write results to file named <filename>.
[amd <amdboost_data>] Reweight bins using AMD boost energies in data set <amdboost_data> (in KT).
[name <outputset name>] Output histogram data set name.
[traj3d <file> [trajfmt <format>]] (3D histograms only) Write a pseudo-trajectory of the 3 data sets (1 atom) to <file> with format <format>.
[parmout <file>] (3D histograms only) Write a topology corresponding to the pseudo-trajectory to <file>.
[min <min>] Default minimum to bin if not specified.
[max <max>] Default max to use if not specified.
[step <step>] Default step size to use if not specified.
[bins <bins>] Default bin size to use if not specified.
[nativeout] Do not use cpptraj data file framework; only necessary for writing out histograms with > 3 dimensions.

Create an N-dimensional histrogram, where N is the number of datasets specified. For 1-dimensional histograms the xmgrace ’.agr’ file format is recommended; for 2-dimensional hisograms the gnuplot ’.gnu’ file format is recommended; for all other dimensions plot formatting is disabled and the routine uses its own internal output format; this is also enabled if gnu or circular is specified.

For example, to create a two dimensional histogram of two datasets ’phi’ and ’psi’:

dihedral phi :2@C :3@N :3@CA :3@C
dihedral psi :3@N :3@CA :3@C :4@N
hist phi,-180,180,*,72 psi,-180,180,*,72 out hist.gnu

In this case the number of bins (72) has been specified for each dimension and ’*’ has been given for the step size, indicating it should be calculated based on min/max/bins. The following ’hist’ command is equivalent:

hist phi psi min -180 max 180 bins 72 out hist.gnu