README.md

WEDAP : weighted ensemble data analysis and plotting (pronounced we-dap)

wedap is primarily used to plot H5 files produced from running WESTPA.

mdap can be used to plot data files from analysis of standard MD simulations.

wekap can be used to plot flux values as rates from a WESTPA created direct.h5 file.

For a demo and summary of features, see this jupyter notebook.

Or view the same demo notebook on the documentation web page.

What's New in v1.1.0

This release modernizes the tooling and adds several requested features. Most changes are backwards-compatible; the breaking items below are limited to environment/dependency requirements and the removal of the deprecated GUI. See CHANGELOG.md for more info.

Breaking changes

• GUI removed. The Gooey-based graphical interface (unmaintained upstream since 2021) and all of its mentions have been removed. Use the CLI or Python API instead. If you relied on the GUI, pin to wedap<1.1.0.
• Python & dependency floors raised. Minimum Python is now 3.9 (numpy 2 floor). The old numpy<2 / matplotlib<=3.7.0 upper caps have been dropped — wedap now supports numpy 2.x and recent matplotlib (tested through numpy 2.5 / matplotlib 3.11 on Python 3.12). If you must stay on an older interpreter, pin to wedap<1.1.0.

Requirements

• numpy
• matplotlib
• h5py
• tqdm
• gif

Installation

pip install wedap

Or install the latest development version from source:

git clone https://github.com/darianyang/wedap.git
cd wedap
pip install -e .

Examples

After installation, to run the CLI version and view available options:

wedap --help

Or:

wedap -h

To visualize the evolution of the pcoord for the example p53.h5 file via CLI:

wedap -h5 wedap/data/p53.h5

To do the same with the API:

import wedap
import matplotlib.pyplot as plt

wedap.H5_Plot(h5="wedap/data/p53.h5", data_type="evolution").plot()
plt.show()

The resulting p53.h5 file evolution plot will look like this:

See the examples directory for more realistic applications using the Python API.

Evolution plots are created by default using the CLI but average and instant probability distribution options are also available. To use one of your auxiliary datasets instead of the progress coordinate, just include the name of the aux dataset from your h5 file in the --Xname or --Yname fields:

wedap -h5 wedap/data/p53.h5 --data_type average --Xname dihedral_10 --Yname dihedral_11

Or:

wedap -h5 wedap/data/p53.h5 -dt average -X dihedral_10 -Y dihedral_11

The resulting p53.h5 file average plot of the dihedral aux datasets will look like this:

If you used a multi-dimensional progress coordinate and you want to use your pcoord for both the X and Y dimensions in a 2D average or instant plot, just use pcoord with the corresponding index set to the appropriate dimension (this also works with aux datasets which may have an additional dimension):

wedap -h5 wedap/data/p53.h5 --data_type average --Xname pcoord --Xindex 0 --Yname pcoord --Yindex 1

Or:

wedap -h5 wedap/data/p53.h5 -dt average -X pcoord -Xi 0 -Y pcoord -Yi 1

Or (since the default X options are the first pcoord, only the second pcoord needs to be specified):

wedap -h5 wedap/data/p53.h5 -dt average -Y pcoord -Yi 1

The resulting p53.h5 file average plot of the pcoord datasets will look like this:

Motivation

WESTPA already comes with some excellent analysis tools for generating probability distributions, so why is wedap needed?

wedap was originally built as a way to simplify the original WESTPA plotting pipeline:

Native WESTPA CLI-based Analysis Tools:

┌───────┐       w_pdist        ┌────────┐        plothist         ┌────────┐
│west.h5├─────────────────────►│pdist.h5├────────────────────────►│plot.pdf│
└───────┘ --construct-dataset  └────────┘ --postprocess-function  └────────┘
               module.py                      plot_settings.py

Analysis using wedap:

┌───────┐     wedap      ┌────────┐
│west.h5├───────────────►│plot.pdf│
└───────┘  CLI/Python    └────────┘

So wedap can generate plots with more flexibilty and less intermediate files, providing an especially useful way to plot aux datasets and explore your h5 file.

• The Python interface allows for advanced users to quickly generate a plot as a matplotlib axes object which can be further customized all in one Python script.
  • For example, the moviepy or gif package can be used with wedap to easily create a gif of your h5 file (see an example of this in wedap/h5_movie.py).
  • The actual data can also be easily extracted and then analyzed (see wedap/h5_cluster.py for an example of k-means clustering using the data from a WESTPA west.h5 file).
• A CLI is also available if using wedap on a system without access to a display.

Since the original implementation of wedap, many more features have been added that are not available using the WESTPA w_pdist and plothist tools, these include the following:

• Easy WE tracing and plotting by inputing an iteration and segment, or by inputing the X and Y value to then query and trace.
• 3D plots that replace the probability with another pcoord or aux dataset (plot_mode="scatter3d").
• Selective basis states (if you have multiple basis states, only plot the probability contributions from specific states).
  • See the skip_basis argument (available through the Python API only currently).
• More to come!

Note that the WESTPA analysis tools have features not available in wedap and may still be of interest to you.

Contributing

Have an idea for a feature to add to wedap? Let me know and I may be able to incorporate it (dty7@pitt.edu).

Or feel free to try developing it yourself! Features should be developed on branches. To create and switch to a branch, use the command:

git checkout -b new_branch_name

To switch to an existing branch, use:

git checkout branch_name

To submit your feature to be incorporated into the main branch, you should submit a Pull Request. The repository maintainers will review your pull request before accepting your changes.

Copyright

Copyright (c) 2021-2026, Darian Yang