plothist

Use the plothist tool to plot the results of w_pdist. This tool uses an hdf5 file as its input (i.e. the output of another analysis tool), and outputs a pdf image.

The plothist tool operates in one of three (mutually exclusive) plotting modes:

evolution: Plots the relevant data as a time evolution over specified number of simulation iterations
average: Plots the relevant data as a time average over a specified number of iterations
instant: Plots the relevant data for a single specified iteration

Overview

The basic usage, independent of plotting mode, is as follows:

usage:

| ``plothist [-h] [-r RCFILE] [--quiet | --verbose | --debug] [--version]``
| ``                          {instant,average,evolution} input ...``

Note that the user must specify a plotting mode (i.e. ‘instant‘, ‘average‘, or ‘evolution‘) and an input file, input.

Therefore, this tool is always called as:

plothist mode input_file [``other`` ``options``]

‘`instant`‘ mode

usage:

| ``plothist instant [-h] input [-o PLOT_OUTPUT]``
| ``                                [--hdf5-output HDF5_OUTPUT] [--text-output TEXT_OUTPUT]``
| ``                                [--title TITLE] [--range RANGE] [--linear | --energy | --log10]``
| ``                                [--iter N_ITER] ``
| ``                                [DIMENSION] [ADDTLDIM]``

‘`average`‘ mode

usage:

| ``plothist average [-h] input [-o PLOT_OUTPUT]``
| ``                                [--hdf5-output HDF5_OUTPUT] [--text-output TEXT_OUTPUT]``
| ``                                [--title TITLE] [--range RANGE] [--linear | --energy | --log10]``
| ``                                [--first-iter N_ITER] [--last-iter N_ITER]                           ``
| ``                                [DIMENSION] [ADDTLDIM]``

‘`evolution`‘ mode

usage:

| ``plothist evolution [-h] input [-o PLOT_OUTPUT]``
| ``                                  [--hdf5-output HDF5_OUTPUT]``
| ``                                  [--title TITLE] [--range RANGE] [--linear | --energy | --log10]``
| ``                                  [--first-iter N_ITER] [--last-iter N_ITER]``
| ``                                  [--step-iter STEP]                                   ``
| ``                                  [DIMENSION]``

Command-Line Options

See the command-line tool index for more information on the general options.

Unless specified (as a Note in the command-line option description), the command-line options below are shared for all three plotting modes

Input/output options

No matter the mode, an input hdf5 file must be specified. There are three possible outputs that are mode or user-specified: A text file, an hdf5 file, and a pdf image.

Specifying input file

*``input``*: Specify the input hdf5 file ‘’input. This is the output file from a previous analysis tool (e.g. ‘pdist.h5’)

Output plot pdf file

``-o ‘’plot_output’’, –plot_output ‘’plot_output’’``: Specify the name of the pdf plot image output (Default: ‘hist.pdf’). Note: You can suppress plotting entirely by specifying an empty string as plot_output (i.e. -o '' or --plot_output '')

Additional output options

Note: plothist provides additional, optional arguments to output the data points used to construct the plot:

``–hdf5-output ‘’hdf5_output’’``: Output plot data hdf5 file 'hdf5_output' (Default: No hdf5 output file)
``–text-output ‘’text_output’’``: Output plot data as a text file named 'text_output' (Default: No text output file) Note: This option is only available for 1 dimensional histogram plots (that is, 'average' and 'instant' modes only)

Plotting options

The following options allow the user to specify a plot title, the type of plot (i.e. energy or probability distribution), whether to apply a log transformation to the data, and the range of data values to include.

``–title ‘’title’’ ``: Optionally specify a title, ``title``, for the plot (Default: No title)
``–range ‘’<nowiki>’</nowiki>LB, UB<nowiki>’</nowiki>’’``: Optionally specify the data range to be plotted as “LB, UB” (e.g. ' --range "-1, 10" ' - note that the quotation marks are necessary if specifying a negative bound). For 1 dimensional histograms, the range affects the y axis. For 2 dimensional plots (e.g. evolution plot with 1 dimensional progress coordinate), it corresponds to the range of the color bar

Mutually exclusive plotting options

The following three options determine how the plotted data is represented (Default: '--energy')

``–energy ``: Plots the probability distribution on an inverted natural log scale (i.e. -ln[P(x)] ), corresponding to the free energy (Default)
``–linear ``: Plots the probability distribution function as a linear scale
``–log10 ``: Plots the (base-10) logarithm of the probability distribution

Iteration selection options

Depending on plotting mode, you can select either a range or a single iteration to plot.

``’instant’`` mode only:

``–iter ‘’n_iter’’ ``: Plot the distribution for iteration ''n_iter'' (Default: Last completed iteration)

``’average’`` and ``’evolution’`` modes only:

``–first-iter ‘’first_iter’’ ``: Begin averaging or plotting at iteration ``first_iter`` (Default: 1)
``–last-iter ‘’last_iter’’ ``: Average or plot up to and including ``last_iter`` (Default: Last completed iteration)

``’evolution’`` mode only:

``–iter_step ‘’n_step’’ ``: Average every ``n_step`` iterations together when plotting in 'evolution' mode (Default: 1 - i.e. plot each iteration)

Specifying progress coordinate dimension

For progress coordinates with dimensions greater than 1, you can specify the dimension of the progress coordinate to use, the of progress coordinate values to include, and the progress coordinate axis label with a single positional argument:

``dimension ``: Specify 'dimension' as ‘int[:[LB,UB]:label]‘, where ‘int‘ specifies the dimension (starting at 0), and, optionally, ‘LB,UB‘ specifies the lower and upper range bounds, and/or ‘label‘ specifies the axis label (Default: int = 0, full range, default label is ‘dimension int’; e.g ‘dimension 0’)

For 'average' and 'instant' modes, you can plot two dimensions at once using a color map if this positional argument is specified:

``addtl_dimension ``: Specify the other dimension to include as 'addtl_dimension'

Examples

These examples assume the input file is created using w_pdist and is named ‘pdist.h5’

Basic plotting

Plot the energy ( -ln(P(x)) ) for the last iteration

plothist instant pdist.h5

Plot the evolution of the log10 of the probability distribution over all iterations

``plothist evolution pdist.h5 –log10 ``

Plot the average linear probability distribution over all iterations

plothist average pdist.h5 --linear

Specifying progress coordinate

Plot the average probability distribution as the energy, label the x-axis ‘pcoord’, over the entire range of the progress coordinate

plothist average pdist.h5 0::pcoord

Same as above, but only plot the energies for with progress coordinate between 0 and 10

plothist average pdist.h5 '0:0,10:pcoord'

(Note: the quotes are needed if specifying a range that includes a negative bound)

(For a simulation that uses at least 2 progress coordinates) plot the probability distribution for the 5th iteration, representing the first two progress coordinates as a heatmap

plothist instant pdist.h5 0 1 --iter 5 --linear

westpa.cli.tools.plothist module

class westpa.cli.tools.plothist.NonUniformImage(ax, *, interpolation='nearest', **kwargs)

Bases: AxesImage

Parameters:

ax (~matplotlib.axes.Axes) – The axes the image will belong to.
interpolation ({'nearest', 'bilinear'}, default: 'nearest') – The interpolation scheme used in the resampling.
**kwargs – All other keyword arguments are identical to those of .AxesImage.

mouseover = False

make_image(renderer, magnification=1.0, unsampled=False)

Normalize, rescale, and colormap this image’s data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns:

image ((M, N, 4) numpy.uint8 array) – The RGBA image, resampled unless unsampled is True.
x, y (float) – The upper left corner where the image should be drawn, in pixel space.
trans (~matplotlib.transforms.Affine2D) – The affine transformation from image to pixel space.

set_data(x, y, A)

Set the grid for the pixel centers, and the pixel values.

Parameters:

x (1D array-like) – Monotonic arrays of shapes (N,) and (M,), respectively, specifying pixel centers.
y (1D array-like) – Monotonic arrays of shapes (N,) and (M,), respectively, specifying pixel centers.
A (array-like) – (M, N) ~numpy.ndarray or masked array of values to be colormapped, or (M, N, 3) RGB array, or (M, N, 4) RGBA array.

set_array(*args)

Retained for backwards compatibility - use set_data instead.

Parameters:: A (array-like)

set_interpolation(s)

Parameters:: s ({'nearest', 'bilinear'} or None) – If None, use :rc:`image.interpolation`.

get_extent(): Return the image extent as tuple (left, right, bottom, top).

set_filternorm(filternorm)

Set whether the resize filter normalizes the weights.

See help for ~.Axes.imshow.

Parameters:: filternorm (bool)

set_filterrad(filterrad)

Set the resize filter radius only applicable to some interpolation schemes – see help for imshow

Parameters:: filterrad (positive float)

set_norm(norm)

Set the normalization instance.

Parameters:: norm (.Normalize or str or None)

Notes

If there are any colorbars using the mappable for this norm, setting the norm of the mappable will reset the norm, locator, and formatters on the colorbar to default.

set_cmap(cmap)

Set the colormap for luminance data.

Parameters:: cmap (.Colormap or str or None)

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, extent=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or 2D array-like or None animated: bool array: unknown clim: (vmin: float, vmax: float) clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: unknown data: unknown extent: 4-tuple of float figure: ~matplotlib.figure.Figure filternorm: unknown filterrad: unknown gid: str in_layout: bool interpolation: {‘nearest’, ‘bilinear’} or None interpolation_stage: {‘data’, ‘rgba’} or None label: object mouseover: bool norm: unknown path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool resample: bool or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

class westpa.cli.tools.plothist.WESTMasterCommand

Bases: WESTTool

Base class for command-line tools that employ subcommands

subparsers_title = None

subcommands = None

include_help_command = True

add_args(parser): Add arguments specific to this tool to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this tool and deal with them appropriately (setting instance variables, etc)

go(): Perform the analysis associated with this tool.

class westpa.cli.tools.plothist.WESTSubcommand(parent)

Bases: WESTToolComponent

Base class for command-line tool subcommands. A little sugar for making this more uniform.

subcommand = None

help_text = None

description = None

add_to_subparsers(subparsers)

go()

property work_manager: The work manager for this tool. Raises AttributeError if this is not a parallel tool.

westpa.cli.tools.plothist.normhistnd(hist, binbounds): Normalize the N-dimensional histogram hist with corresponding bin boundaries binbounds. Modifies hist in place and returns the normalization factor used.

westpa.cli.tools.plothist.get_object(object_name, path=None): Attempt to load the given object, using additional path information if given.

westpa.cli.tools.plothist.sum_except_along(array, axes): Reduce the given array by addition over all axes except those listed in the scalar or iterable axes

class westpa.cli.tools.plothist.PlotHistBase(parent)

Bases: WESTSubcommand

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

parse_dimspec(dimspec)

parse_range(rangespec)

class westpa.cli.tools.plothist.PlotSupports2D(parent)

Bases: PlotHistBase

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

class westpa.cli.tools.plothist.InstantPlotHist(parent)

Bases: PlotSupports2D

subcommand = 'instant'

help_text = 'plot probability distribution for a single WE iteration'

description = 'Plot a probability distribution for a single WE iteration. The probability\ndistribution must have been previously extracted with ``w_pdist`` (or, at\nleast, must be compatible with the output format of ``w_pdist``; see\n``w_pdist --help`` for more information).\n'

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

do_instant_plot_1d(): Plot the histogram for iteration self.n_iter

do_instant_plot_2d(): Plot the histogram for iteration self.n_iter

go()

class westpa.cli.tools.plothist.AveragePlotHist(parent)

Bases: PlotSupports2D

subcommand = 'average'

help_text = 'plot average of a probability distribution over a WE simulation'

description = 'Plot a probability distribution averaged over multiple iterations. The\nprobability distribution must have been previously extracted with ``w_pdist``\n(or, at least, must be compatible with the output format of ``w_pdist``; see\n``w_pdist --help`` for more information).\n'

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

do_average_plot_1d(): Plot the average histogram for iterations self.iter_start to self.iter_stop

do_average_plot_2d(): Plot the histogram for iteration self.n_iter

go()

class westpa.cli.tools.plothist.EvolutionPlotHist(parent)

Bases: PlotHistBase

subcommand = 'evolution'

help_text = 'plot evolution of a probability distribution over the course of a WE simulation'

description = 'Plot a probability distribution as it evolves over iterations. The\nprobability distribution must have been previously extracted with ``w_pdist``\n(or, at least, must be compatible with the output format of ``w_pdist``; see\n``w_pdist --help`` for more information).\n'

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

go(): Plot the evolution of the histogram for iterations self.iter_start to self.iter_stop

class westpa.cli.tools.plothist.PlotHistTool

Bases: WESTMasterCommand

prog = 'plothist'

subparsers_title = 'plotting modes'

subcommands = [<class 'westpa.cli.tools.plothist.InstantPlotHist'>, <class 'westpa.cli.tools.plothist.AveragePlotHist'>, <class 'westpa.cli.tools.plothist.EvolutionPlotHist'>]

description = 'Plot probability density functions (histograms) generated by w_pdist or other\nprograms conforming to the same output format. This program operates in one of\nthree modes:\n\n instant\n Plot 1-D and 2-D histograms for an individual iteration. See\n ``plothist instant --help`` for more information.\n\n average\n Plot 1-D and 2-D histograms, averaged over several iterations. See\n ``plothist average --help`` for more information.\n\n evolution\n Plot the time evolution 1-D histograms as waterfall (heat map) plots.\n See ``plothist evolution --help`` for more information.\n\nThis program takes the output of ``w_pdist`` as input (see ``w_pdist --help``\nfor more information), and can generate any kind of graphical output that\nmatplotlib supports.\n\n\n------------------------------------------------------------------------------\nCommand-line options\n------------------------------------------------------------------------------\n'

westpa.cli.tools.plothist.entry_point()

plothist

Overview

‘instant‘ mode

‘average‘ mode

‘evolution‘ mode

Command-Line Options

Input/output options

Specifying input file

Output plot pdf file

Additional output options

Plotting options

Mutually exclusive plotting options

Iteration selection options

Specifying progress coordinate dimension

Examples

Basic plotting

Specifying progress coordinate

westpa.cli.tools.plothist module

‘`instant`‘ mode

‘`average`‘ mode

‘`evolution`‘ mode