# 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 $latex G_i = -K_B T \left( \frac{N_i}{N_{Max}} \right)$, where $latex K_B$ is Boltzmann’s constant, T is the temperature specified by <temperature>, $latex N_i$ is the population of bin $latex i$ and $latex N_{Max}$ 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