attribute_hist

Compute histograms of a given spatial attribute of an MDAnalysis AtomGroup.

The spatial attribute is selected with --attribute. It is always calculated with respect to the center of mass of the selected compound.

Five histograms are plotted:

  • Three histograms showing the distribution of each spatial dimension of the selected attribute.

  • One histogram showing the combined distribution of all spatial dimensions of the selected attribute.

  • One histogram showing the distribution of Euclidean norms (2-norm) of the attribute vectors.

Options

-f

Trajectory file. See supported coordinate formats of MDAnalysis.

-s

Topology file. See supported topology formats of MDAnalysis.

-o

Five output filenames, one for each histogram. Alternatively, a single filename can be given which will be used as basename for the five histogram files.

-b

First frame to read from the trajectory. Frame numbering starts at zero. Default: 0.

-e

Last frame to read from the trajectory. This is exclusive, i.e. the last frame read is actually END - 1. A value of -1 means to read the very last frame. Default: -1.

--every

Read every n-th frame from the trajectory. Default: 1.

--sel

Selection string to select a group of atoms for the analysis. See MDAnalysis’ selection syntax for possible choices.

--updating-sel

Use an UpdatingAtomGroup for the analysis. Selection expressions of UpdatingAtomGroups are re-evaluated every time step. This is e.g. useful for position-based selections like 'type Li and prop z <= 2.0'.

--cmp

{‘group’, ‘segments’, ‘residues’, ‘molecules’, ‘fragments’, ‘atoms’}

The compounds of the selection group to use for the analysis. Compounds can be ‘group’ (the entire selection group), ‘segments’, ‘residues’, ‘molecules’, ‘fragments’, or ‘atoms’. Refer to the MDAnalysis’ user guide for an explanation of these terms. Note that in any case, even if CMP is e.g. ‘residues’, only the atoms belonging to the selection group are taken into account, even if the compound might comprise additional atoms that are not contained in the selection group. In all cases, the center of mass of the compound is used for the analysis. Note that MDAnalysis always guesses atom masses from the atom types, even if the input file contains the masses. Default: 'atoms'.

--attribute

{‘velocities’, ‘forces’, ‘positions’}

The attribute of the selection group for which to create the histograms. The trajectory must contain information about this attribute. Default: 'velocities'.

--bin-start

First bin edge of the histograms in data units (inclusive). If None, the minimum value of the selected attribute is taken. Default: None.

--bin-stop

Last bin edge of the histograms in data units (inclusive). If None, the maximum value of the selected attribute is taken. Default: None.

--bin-num

Number of bin edges of the histograms (the number of bins is the number of bin edges minus one). If None, the number of bins is estimated according to the “scott” method as described by numpy.histogram_bin_edges():

\[h = \sigma \sqrt[3]{\frac{24 \sqrt{\pi}}{n}}\]

Here, \(\sigma\) is the standard deviation of the data, \(n\) is the number of data points and \(h\) is the bin width. The number of bins is calculated by np.ceil((bin_stop - bin_start) / bin_width).

Notes

All created histograms, except the last one (Euclidean norm), are fitted by Gaussian distribution functions:

\[g(x) = \frac{1}{\sqrt{2\pi\sigma^2}} e^{-\frac{(x - \mu)^2}{2\sigma^2}}\]

If the selected attribute is ‘velocities’, the last histogram (Euclidean norm) is fitted by a Maxwell-Boltzmann speed distribution function:

\[p(v) = 4 \pi (v - u)^2 \left(\frac{1}{2\pi\sigma^2}\right)^{\frac{3}{2}} e^{-\frac{(v - u)^2}{2\sigma^2}}\]

with \(\sigma^2 = \frac{k_B T}{m}\), \(k_B\) being Boltzmann’s constant, \(T\) being the temperature and \(m\) being the average mass of the selected compounds. \(u\) is a drift velocity that simply shifts the distribution to the right. \(\sigma^2\) and \(u\) are used as fit parameters. Afterwards, the temperature is calculated from \(\sigma^2\) according to \(T = m\sigma^2/k_B\), where \(m\) is set to the average mass of all selected compounds.

Usually, it is a bad idea to compute overall histograms of multiple compounds in the trajectory. Instead, better compute separate histograms for each compound. In other words, only select compounds of the same type with --sel and --cmp (e.g. all water molecules or all oxygen atoms belonging to water molecules).