Skip to content

Commit 52d9949

Browse files
mt-digitalmt-digital
committed
added CLI docs
1 parent db842af commit 52d9949

3 files changed

Lines changed: 144 additions & 8 deletions

File tree

‎docs/source/_static/nash-sutcliffe.png‎

241 KB
Loading

‎docs/source/cli.rst‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
Command-Line Interface
2+
======================
3+
4+
If you installed using ``pip``, you should now be able to access the
5+
PRMS-Python Command-Line Interface (CLI) through the ``prmspy`` command. You can
6+
run the `prmspy` command
7+
8+
.. code-block:: sh
9+
10+
prmspy
11+
12+
and you should see the following help message
13+
14+
.. code-block:: none
15+
16+
Usage: prmspy [OPTIONS] COMMAND [ARGS]...
17+
18+
access PRMS-Python functionality from the command line
19+
20+
Options:
21+
--help Show this message and exit.
22+
23+
Commands:
24+
nash_sutcliffe_matrix Save a PDF of the Nash-Sutcliffe created from...
25+
param_scale_sim Provide params and scaling values; run PRMS...
26+
27+
28+
You can get help messages for the commands by typing them in after `prmspy`:
29+
30+
.. code-block:: sh
31+
32+
prmspy param_scale_sim
33+
34+
.. code-block:: sh
35+
36+
prmspy nash_sutcliffe_matrix
37+
38+
39+
Commands
40+
--------
41+
42+
The CLI provides two commands, ``param_scale_sim`` and
43+
``nash_sutcliffe_matrix``. They are rather cryptically named, so we will explain
44+
these names.
45+
46+
47+
``param_scale_sim``
48+
```````````````````
49+
50+
``param_scale_sim`` performs a parameter-scaling experiment. The user can
51+
pass in any number of parameters and a list of scaling values to use for
52+
each parameter. ``prmspy`` will modify base parameter data as requested,
53+
doing the data management for you, and placing all "scenario" inputs into
54+
a UUID4-named directory. ``prmspy`` tracks which directories belong to which
55+
combination of scaling values, and writes this information on disk in
56+
JSON-formatted metadata saved to the same parent directory as the scenario
57+
input and output data.
58+
59+
Below is an example using ``prmspy param_scale_sim`` to create 121 different
60+
scenarios by co-varying two parameters, ``rad_trncf`` and ``snow_adj`` both
61+
across eleven values, 0.5 to 1.5 in 0.1 increments. We provide a title,
62+
"Testing prmspy with rad_trncf and snow_adj adjustments", use eight
63+
processors (``-n8``), run PRMS instead of simply building scenario input data,
64+
and write all data to the directory ``test-run-series``.
65+
66+
.. code-block:: sh
67+
68+
prmspy param_scale_sim prms_python/models/lbcd \
69+
-p rad_trncf \
70+
-s"[0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5]" \
71+
-p snow_adj \
72+
-s"[0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5]" \
73+
-t"Testing prmspy with rad_trncf and snow_adj adjustments" \
74+
-n8 \
75+
-o test-run-series \
76+
--run-prms
77+
78+
It's a lot to type in, but it's actually pretty clear.
79+
80+
What to do with all that data? Move on to the next section to see an option
81+
for analyzing the fit of modeled data to observed data as these parameters vary.
82+
83+
84+
``nash_sutcliffe_matrix``
85+
`````````````````````````
86+
87+
The Nash-Sutcliffe model efficiency is one of many measures of how well a
88+
model output matches known observational data. For this, we are comparing the
89+
predicted streamflow matches the observed streamflow.
90+
91+
Mathematically, the Nash-Sutcliffe efficiency (NSE), :math:`E` is defined as
92+
93+
.. math::
94+
95+
E = 1 - \frac
96+
{\sum_{t=1}^{T}\left(Q_o^t - Q_m^t\right)^2}
97+
{\sum_{t=1}^{T}\left(Q_o^t - \overline{Q_o}\right)^2}
98+
99+
where for us :math:`Q_o^t` is the observed streamflow at time :math:`t`,
100+
:math:`Q_m^t` is the modeled streamflow at time :math:`t`, and
101+
:math:`\overline{Q_o}` the time average of the observed streamflow.
102+
103+
The Nash-Sutcliffe efficiency can be at most 1 which happens in the
104+
unlikely case that the modeled streamflow exactly matches the
105+
observed streamflow. The NSE has no lower bound. An NSE of zero means that the
106+
time-average would do just as well at predicting the timeseries as the model
107+
did. An NSE below zero means that the time-average as a predictor would
108+
be a better predictor than the model.
109+
110+
We can calculate a matrix of Nash-Sutcliffe values whose coordinates correspond
111+
to combinations of parameter scalings given to ``prmspy param_scale_sim``
112+
above.
113+
114+
To build a PDF with a visualization of this image, run the following
115+
116+
.. code-block:: sh
117+
118+
prmspy nash_sutcliffe_matrix test-run-series nash-sutcliffe.pdf
119+
120+
Open ``nash-sutcliffe.pdf`` and you should see something just like this:
121+
122+
.. figure:: _static/nash-sutcliffe.png
123+
124+

‎docs/source/index.rst‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,33 +14,45 @@ filesystem with metadata. A series of scenarios (``ScenarioSeries``) are stored
1414
in a single root directory for each new series with metadata for later
1515
analysis.
1616

17-
Below are some examples. For more details, see the :doc:`/api`.
1817

19-
Installation
20-
------------
18+
Install
19+
-------
2120

22-
Currently this is only available through cloning on GitHub.
21+
``pip install prms-python``
22+
23+
Developer Install
24+
`````````````````
25+
26+
27+
Clone from GitHub
2328

2429
.. code-block:: sh
2530
26-
git clone https://github.com/mtpain/PRMS-Python.git
31+
git clone https://github.com/mtpain/PRMS-Python.git && cd PRMS-Python
2732
28-
Then install dependencies
33+
Then install dependencies and executable
2934

3035
.. code-block:: sh
3136
32-
pip install -r requirements.txt
37+
pip install --editable .
3338
3439
3540
Usage
3641
-----
3742

38-
Please see the :doc:`tutorial` page for usage recipes and examples, and consult the
43+
If you want to dive right in, modify some parameters and run some scenarios,
44+
go on to the :doc:`cli` page. There you'll learn how to run `prmspy`, the
45+
command-line interface to the PRMS-Python tools.
46+
47+
If instead you would rather get acquainted with the Python API for direct use,
48+
see the :doc:`tutorial` page for usage recipes and examples, and consult the
3949
:doc:`api` for more details.
4050

51+
4152
.. toctree::
4253
:includehidden:
4354
:maxdepth: 2
4455

56+
cli
4557
tutorial
4658
api

0 commit comments

Comments
 (0)