Metadata-Version: 2.4
Name: nwm_explorer
Version: 1.5.0
Summary: A web-based application used to explore National Water Model output and evaluation metrics.
Author-email: "Jason A. Regina" <jregina@duck.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/jarq6c/nwm-explorer
Project-URL: Documentation, https://jarq6c.github.io/nwm-explorer
Project-URL: Repository, https://github.com/jarq6c/nwm-explorer
Project-URL: Bug Tracker, https://github.com/jarq6c/nwm-explorer/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: pandas
Requires-Dist: polars
Requires-Dist: xarray
Requires-Dist: aiohttp
Requires-Dist: aiofiles
Requires-Dist: numba
Requires-Dist: pyarrow
Requires-Dist: netcdf4
Requires-Dist: dask
Requires-Dist: panel
Requires-Dist: geopandas
Requires-Dist: plotly
Requires-Dist: colorcet
Requires-Dist: arch
Requires-Dist: us
Requires-Dist: h5netcdf
Requires-Dist: pydantic
Requires-Dist: cartopy
Provides-Extra: develop
Requires-Dist: pytest; extra == "develop"
Dynamic: license-file

# National Water Model Evaluation Explorer

A web-based application used to explore National Water Model output and evaluation metrics. This package includes a command-line interface (CLI) for data retrieval and analysis, as well as a graphical user interface (GUI) for exploring evaluation results. The primary intended use-case is generating ad-hoc evaluations of National Water Model forecasts and analyses.

## Installation
```bash
$ python3 -m venv env
$ source env/bin/activate
(env) $ pip install -U pip wheel
(env) $ pip install nwm_explorer
```

## Command-line Interface
Once installed, the CLI is accessible from an activated python environment using `nwm-explorer`. For example,
```bash
$ nwm-explorer --help
```
```console
 Usage: nwm-explorer [OPTIONS] COMMAND [ARGS]...                                                                                                   
                                                                                                                                                   
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                                                         │
│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                                  │
│ --help                        Show this message and exit.                                                                                       │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ download   Download and process NWM and USGS data for evaluations.                                                                              │
│ pair       Resample and pair NWM predictions to USGS observations.                                                                              │
│ compute    Compute evaluation metrics for NWM-USGS pairs.                                                                                       │
│ evaluate   Run standard evaluation including download, pair, and compute. Parameters set in configuration file.                                 │
│ export     Export evaluation metrics to CSV.                                                                                                    │
│ display    Launch graphical application in the browser. Shutdown the application using ctrl+c.                                                  │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

```
Note that each command (`download`, `pair`, `compute`, etc. will show additional information using `--help`)

### Standard Usage
Generally, users will want to run the `evaluate` and `display` commands in sequence to generate and explore NWM evaluations. The `evaluate` command will run generate standard evaluation metrics given the parameters in the JSON configuration file. For example, the configuration snippet below will run an evaluation labeled `test_run_1` on National Water Model forecasts and analyses from 2024-10-01 to 2024-10-03. Running `nwm-explorer evaluate` will `download` NWM and USGS time series, `pair` time series, and `compute` evaluation metrics. After `compute` completes, metrics can be explored using the GUI by running `nwm-explorer display`.
```json
    "evaluations": [
        {
            "label": "test_run_1",
            "start_time": "2024-10-01",
            "end_time": "2024-10-03"
        }
    ],
```

## Graphical User Interface

The GUI includes many options for exploring evaluation results including mapping of metrics, filtering by lead time or aggregation, regional CDFs, hydrographs, and site information.

![GUI](https://raw.githubusercontent.com/jarq6c/nwm-explorer/main/images/gui.png)
