From 6277b80ed98ac68a45061d6c073c43609576a950 Mon Sep 17 00:00:00 2001 From: RY4GIT <400mhs2@gmail.com> Date: Thu, 23 Jan 2025 15:20:12 -0800 Subject: [PATCH] add usage notes page --- docs/_static/usages/params_overlandflow.csv | 25 ++++++++ docs/_static/usages/params_recession.csv | 3 + docs/_static/usages/ws_code.csv | 14 ++++ docs/index.rst | 3 +- docs/make.bat | 11 +++- docs/p3_examples.rst | 2 +- docs/p4_usage_notes.rst | 71 +++++++++++++++++++++ docs/{p4_contact.rst => p5_contact.rst} | 2 +- 8 files changed, 127 insertions(+), 4 deletions(-) create mode 100644 docs/_static/usages/params_overlandflow.csv create mode 100644 docs/_static/usages/params_recession.csv create mode 100644 docs/_static/usages/ws_code.csv create mode 100644 docs/p4_usage_notes.rst rename docs/{p4_contact.rst => p5_contact.rst} (96%) diff --git a/docs/_static/usages/params_overlandflow.csv b/docs/_static/usages/params_overlandflow.csv new file mode 100644 index 0000000..0076db2 --- /dev/null +++ b/docs/_static/usages/params_overlandflow.csv @@ -0,0 +1,25 @@ +ws_code,min_termination,min_duration,min_intensity_day,min_intensity_day_during,max_recessiondays +1,72,24,7.2,7.2,8 +2,72,24,7.2,7.2,8 +3,72,24,7.2,7.2,8 +4,48,24,4.8,4.8,8 +5,48,24,4.8,4.8,8 +6,48,24,4.8,4.8,8 +7,48,24,4.8,4.8,8 +8,48,24,4.8,4.8,8 +9,48,24,2.4,2.4,8 +10,48,24,2.4,2.4,8 +11,48,24,2.4,2.4,8 +12,72,24,4.8,4.8,8 +13,72,24,4.8,4.8,8 +14,48,24,4.8,4.8,8 +18,48,24,9.6,9.6,8 +20,48,24,4.8,4.8,8 +22,48,24,4.8,4.8,8 +26,48,24,4.8,4.8,8 +27,72,24,4.8,4.8,8 +28,72,24,4.8,4.8,8 +30,48,24,4.8,4.8,8 +36,48,24,4.8,4.8,8 +39,48,24,4.8,4.8,8 +90,48,24,4.8,4.8,8 diff --git a/docs/_static/usages/params_recession.csv b/docs/_static/usages/params_recession.csv new file mode 100644 index 0000000..97a121d --- /dev/null +++ b/docs/_static/usages/params_recession.csv @@ -0,0 +1,3 @@ +flow,recession_length,n_start,eps,filter_par +normal,5,0,0.08,0.925 +low,10,0,0.02,0.925 diff --git a/docs/_static/usages/ws_code.csv b/docs/_static/usages/ws_code.csv new file mode 100644 index 0000000..7406772 --- /dev/null +++ b/docs/_static/usages/ws_code.csv @@ -0,0 +1,14 @@ +01,North Atlantic slope basins +02,South Atlantic slope basins +03,Ohio, Cumberland, and Tennessee River basins +04,St. Lawrence River basin +05,Hudson Bay and Upper Mississippi River basin +06,Missouri River basin +07,Lower Mississippi River basin +08,Western Gulf of Mexico basins +09,Colorado River basin +10,The Great Basin +11,Pacific slope basins in California +12,Pacific slope basins in Washington and upper Columbia River basin +13,Snake River basin +14,Pacific slope basins in Oregon and lower Columbia River basin \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index a53d7d4..9f9112c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,8 @@ TOSSH is a Matlab toolbox that provides accessible, standardised signature calcu p1_overview p2_signatures p3_examples - p4_contact + p4_usage_notes + p5_contact diff --git a/docs/make.bat b/docs/make.bat index fe068b8..05bf113 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -36,8 +36,17 @@ popd :: Building the Documentation Locally before pushing to GitHub +:: (A) [Recommended] Steps to Enable Real-Time Updates + +:: (1) Install sphinx, sphinx-rtd-theme, and sphinx-autobuild in your conda environment +:: (2) Navigate to the docs directory +:: (3) Run the make.bat file with the html option: make.bat html +:: (3) Start a local HTTP Server ``` sphinx-autobuild . _build/html```. This starts a server at http://127.0.0.1:8000 + +:: (B) Build it static + :: (1) Install sphinx and phinx-rtd-theme in your conda environment :: (2) Navigate to the docs directory :: (3) Run the make.bat file with the html option: make.bat html :: (4) Navigate to the _build/html directory -:: (5) Start a local HTTP Server python -m http.server. This starts a server at http://localhost:8000 \ No newline at end of file +:: (5) Start a local HTTP Server ``` python -m http.server ```. This starts a server at http://localhost:8000 diff --git a/docs/p3_examples.rst b/docs/p3_examples.rst index ca5d593..87b7626 100644 --- a/docs/p3_examples.rst +++ b/docs/p3_examples.rst @@ -226,7 +226,7 @@ For each signature, we also provide small examples in the description of each m- % Q_mean = sig_Q_mean(Q,t); [...] -If any of the examples, errors or warnings are unclear, please :ref:`contact ` us. +If any of the examples, errors or warnings are unclear, please :ref:`contact ` us. References diff --git a/docs/p4_usage_notes.rst b/docs/p4_usage_notes.rst new file mode 100644 index 0000000..0e392ae --- /dev/null +++ b/docs/p4_usage_notes.rst @@ -0,0 +1,71 @@ +.. _p4_usage_notes: + +Usage Notes +======== + +Understanding Signature Parameters +---------------- + +Example parameters +^^^^^^^^^ +Hydrologic signatures often need customized input parameters because rainfall patterns vary by region and time resolutions vary by dataset [1]_. +The following lists example parameter files to help you get started. +These parameters have been manually tuned for select signatures and U.S. gages at a **daily timestep**, using the CAMELS and HYSETS datasets in Caravan [2]_. + + +1. Overlandflow signatures + +- Parameter file: `params_overlandflow.csv `_ + +- Use these parameters for the event separation algorithm `util_EventSeparation.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/utility_functions/util_EventSeparation.html>`_ + +- Parameters included: ``min_termination``, ``min_duration``, ``min_intensity_day``, ``min_intensity_day_during``, ``max_recessiondays`` per CONUS region + +- In the table, ``ws_code`` column categorizes the CONUS regions using the first two digits of the USGS `gauge_id` from the CAMELS/HYSETS datasets. This classification is based on the downstream order system (see https://help.waterdata.usgs.gov/faq/sites/do-station-numbers-have-any-particular-meaning) + +2. Recession-related signatures + +- Parameter file: `params_recession.csv `_ + +- Use these parameters for the recession delineation algorithm `util_RecessionSegments.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/utility_functions/util_RecessionSegments.html>`_ + +- Parameters included: ``recession_length``, ``n_start``, ``eps``, ``filter_par`` for low or high rainfall area + +**Note:** For tuning, we evaluated the parameter performance using approximately ten watersheds that have drainage area close to the median of each CONUS region. While these settings are a good starting point, please review and adjust them as needed for your specific application. + +How to Adjust Parameters Yourself +^^^^^^^^^ +If the provided parameters don't suit your dataset, here are some guidelines for tuning key parameters. +We highly recommend using TOSSH visualization tools (`sig_EventGraphThresholds.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/signature_functions/sig_EventGraphThresholds.html>`_ and `sig_RecessionAnalysis.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/signature_functions/sig_RecessionAnalysis.html>`_) to inspect how well the parameters fit your time series. + +- Key parameters for `util_EventSeparation.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/utility_functions/util_EventSeparation.html>`_: + - ``min_termination``: + - This parameter controls how long the shortest storm event should be. The default value can be set to **48 hours** for daily data. With this, once-in-3-days rainfall is being separated as the new event. + - For persistent rainfall or slower-responding watersheds, increase the values (e.g., **72 hours**). + - ``min_intensity_day`` and ``min_intensity_day_during``: + - This parameter controls the minimum duration of the shortest storm event. The default value can be set to **4.8 mm/day** for daily data (derived from 0.2 mm/hr × 24 hours). + - Adjust this value based on the region's rainfall intensity (e.g., use higher values for areas with significant rainfall). Selecting a small value for regions with high rainfall may result in small, noisy rainfall being detected at the start of an event. + - ``max_recessiondays``: + - The default value can be set to **8 days** (no tuning is generally required). + - Increasing this value helps capture long recession tails when no subsequent rainfall occurs. Allowing a larger ``max_recessiondays`` does no harm, as the ``min_termination`` parameter will start a new event when subsequent rainfall occurs. + - ``min_duration``: + - The default value can be set to **1 day** (no tuning is required for daily data). + +- Key parameters for `util_RecessionSegments.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/utility_functions/util_RecessionSegments.html>`_: + - ``recession_length``: + - The default value can be set to **5 days** with ``eps=0.08`` for most cases. + - For low-flow conditions, use longer thresholds (e.g., **10 days** with ``eps=0.01``). + - For quick recessions after rainfall, reduce the value to **3 days** (but avoid including noisy recessions). + + - ``filter_par``: + - The default value can be set to **0.925** (no tuning needed; used for smoothing). + + - ``n_start``: + - The default value can be set to **0** for daily data. For hourly data, increase this value to mask flow immediately after the peak. + +References +---------- + +.. [1] McMillan, H. K., Coxon, G., Araki, R., Salwey, S., Kelleher, C., Zheng, Y., et al. (2023). When good signatures go bad: Applying hydrologic signatures in large sample studies. Hydrological Processes, 37(9). https://doi.org/10.1002/hyp.14987 + +.. [2] Kratzert, F., Nearing, G., Addor, N., Erickson, T., Gauch, M., Gilon, O., Gudmundsson, L., Hassidim, A., Klotz, D., Nevo, S., Shalev, G., & Matias, Y. (2024). Caravan - A global community dataset for large-sample hydrology (1.4) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.10968468 \ No newline at end of file diff --git a/docs/p4_contact.rst b/docs/p5_contact.rst similarity index 96% rename from docs/p4_contact.rst rename to docs/p5_contact.rst index 1da1ae4..38a6e91 100644 --- a/docs/p4_contact.rst +++ b/docs/p5_contact.rst @@ -1,4 +1,4 @@ -.. _p4_contact: +.. _p5_contact: Contact =======