Metadata-Version: 2.4
Name: wedap
Version: 1.3.0
Summary: Weighted Ensemble Data Analysis and Plotting
Author-email: "Darian T. Yang" <dty7@pitt.edu>
License: BSD 3-Clause License
        
        Copyright (c) 2021, Darian Yang
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Source, https://github.com/darianyang/wedap
Project-URL: Documentation, https://darianyang.github.io/wedap
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.7
Requires-Dist: h5py
Requires-Dist: gif
Requires-Dist: tqdm
Provides-Extra: web
Requires-Dist: streamlit>=1.39; extra == "web"
Dynamic: license-file

<p align="left">
    <img src="https://github.com/darianyang/wedap/blob/main/docs/_static/wedap_logo.png?raw=true" alt="wedap logo" width="400">
</p>

![tests](https://github.com/darianyang/wedap/actions/workflows/tests.yml/badge.svg)
[![docs](https://img.shields.io/website?label=docs&up_color=brightgreen&up_message=online&url=https%3A%2F%2Fdarianyang.github.io%2Fwedap%2Fdocs%2Fhtml%2Findex.html)](https://darianyang.github.io/wedap/docs/html/index.html)
[![PyPI version](https://badge.fury.io/py/wedap.svg)](https://badge.fury.io/py/wedap)
[![Downloads](https://static.pepy.tech/badge/wedap)](https://pepy.tech/project/wedap)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11051657.svg)]([https://doi.org/10.5281/zenodo.11051657](https://doi.org/10.5281/zenodo.11051657))
[![JCIM Paper](https://img.shields.io/badge/JCIM_Paper-https%3A%2F%2Fdoi.org%2F10.1021%2Facs.jcim.4c00867-crimson)](https://doi.org/10.1021/acs.jcim.4c00867)


**WEDAP** : **w**eighted **e**nsemble **d**ata **a**nalysis and **p**lotting (pronounced we-dap)

`wedap` is primarily used to plot H5 files produced from running [WESTPA](https://github.com/westpa/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](docs/notebook/wedap_demo.ipynb).

Or view the same demo notebook on the [documentation web page](https://darianyang.github.io/wedap/docs/html/notebook/wedap_demo.html).

### What's New in v1.3.0

This release fixes h5 files being left open and locked by wedap (e.g. after an error in a Jupyter notebook), which could block other programs like `w_multi_west` from writing to them (see the [H5 file access](#h5-file-access) section below), along with fixes to the `H5save_out`, `succ_only`, `skip_basis` and multiple h5 file options.

v1.2.0 replaced the previously removed/deprecated gooey-based GUI with a streamlit app (see the [Web app (Streamlit)](#web-app-streamlit) section below). See CHANGELOG.md for more info.

### Requirements

- numpy
- matplotlib
- h5py
- tqdm
- gif

## Installation

``` bash
pip install wedap
```

Or install the latest development version from source:
``` bash
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:
``` bash
wedap --help
```
Or:
``` bash
wedap -h
```
To visualize the evolution of the pcoord for the example p53.h5 file via CLI:
``` bash
wedap -h5 wedap/data/p53.h5
```
To do the same with the API:
``` Python
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:
<p align="left">
    <img src="https://github.com/darianyang/wedap/blob/main/docs/_static/p53_evo.png?raw=true" alt="p53 evo plot" width="400">
</p>

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:
``` bash
wedap -h5 wedap/data/p53.h5 --data_type average --Xname dihedral_10 --Yname dihedral_11
```
Or:
``` bash
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:
<p align="left">
    <img src="https://github.com/darianyang/wedap/blob/main/docs/_static/p53_avg_aux.png?raw=true" alt="p53 avg aux plot" width="400">
</p>

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):
``` bash
wedap -h5 wedap/data/p53.h5 --data_type average --Xname pcoord --Xindex 0 --Yname pcoord --Yindex 1
```
Or:
``` bash
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):
``` bash
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:
<p align="left">
    <img src="https://github.com/darianyang/wedap/blob/main/docs/_static/p53_avg_pcoord.png?raw=true" alt="p53 avg pcoord plot" width="400">
</p>

### H5 file access

wedap only keeps an h5 file open while one of its methods is running (e.g. `pdist()` or
`plot_trace()`), and closes it again afterwards, even if there was an error. So an `H5_Pdist`
or `H5_Plot` object left in a Jupyter notebook does not lock the file or block other programs
like `w_run` or `w_multi_west` from writing to it. If you read from the `h5` attribute of these
objects directly, call `close()` when you are done.

When calling methods many times in a loop (e.g. `get_parents()`), use a `with` block to keep the
file open for the whole loop instead of reopening it for each call, then it is closed at the end:
``` python
pdist = wedap.H5_Pdist(h5="west.h5", data_type="evolution")
with pdist:
    parents = [pdist.get_parents((10, seg)) for seg in range(50)]
```

## Web app (Streamlit)

`wedap` ships with an optional browser-based interface built on [Streamlit](https://streamlit.io/), providing a point-and-click alternative to the CLI (dataset dropdowns, live plot options, a downloadable figure, and a copy-pasteable equivalent Python snippet).

The app bundles all three tools as tabs (each tab keeps its own inputs when you switch between them):
- **wedap** — WESTPA `west.h5` probability distributions and plots (1D/2D/3D, plot tracing, gif making).
- **mdap** — probability distributions and plots from standard MD analysis data files (`.dat`/`.npy`/...).
- **wekap** — WE kinetics: rates/MFPTs from a `direct.h5` file (RED correction, multi-replicate averaging).

Install the optional `web` extra and launch it:
``` bash
pip install "wedap[web]"
wedap-web
```
Or run it directly on the app module:
``` bash
streamlit run wedap/web/app.py
```
This starts a local server (default port `8501`) and opens the app in your browser at `http://localhost:8501`.

### Running on a remote cluster

If you run `wedap-web` on a remote machine (e.g. an HPC login or compute node), the server runs there but your browser is local, so you need to forward the port over SSH.

First launch it headless on the cluster (optionally pick a port to avoid clashes):
``` bash
wedap-web --server.headless true --server.port 8501
```

Then, from your **local** machine, open an SSH tunnel and browse to `http://localhost:8501`:
``` bash
# from a login node:
ssh -L 8501:localhost:8501 user@cluster

# from a compute node (two-hop; cNODE is the node's hostname):
ssh -L 8501:cNODE:8501 user@cluster-login
```
Keep the SSH session open while you use the app. If port `8501` is already in use locally, forward to a different local port, e.g. `-L 8600:localhost:8501`, and browse `http://localhost:8600`.

> **Tip:** For large `west.h5` files, use the app's "Server path" input mode (point it at a path on the cluster) rather than the file uploader, which holds the file in memory.

## 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
