Deploying to gh-pages from @ 4f8a055 🚀

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 44fbe063ef6cbeb1ac0c86e5d26336d0
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/acknowledgments.rst.txt

@@ -0,0 +1,11 @@
+Acknowledgments
+===============
+
+.. _GeoCARET: https://github.com/Reservoir-Research/geocaret
+.. _Google Cloud: https://cloud.google.com/?hl=en
+
+This software and documentation would not have been possible without the joint effort of several people.
+
+In particular, we would like to acknowledge **Dr. Kamilla Harding-Kopec (PhD)** for starting GeoCARET_ and writing most of the initial source-code (in fact all of the code in its current working form in the ``main`` branch of the GeoCARET_'s repository), and for contributing the bulk of the text in this documentation.
+
+We would also like to acknowledge **Dr. James Sinnott (PhD)** for creating the Docker image and for his contribution to this documentation, including writing the pages related to the use of Docker and setting up projects on `Google Cloud`_.

_sources/algorithms.rst.txt

@@ -0,0 +1,8 @@
+Algorithms
+==========
+
+GeoCARET implements various algorithms, e.g. for delineating catchment and reservoirs, snapping dam locations to river sections, etc.
+We will be gradually documenting these algorithms and putting their description here.
+At the moment this section is under construction. Please visit us later.
+
+|under-construction|

_sources/api/geocaret.rst.txt

@@ -0,0 +1,7 @@
+GeoCARET Python API documentation
+=================================
+
+We are currently refactoring the source-code and while we are at, we are also updating the source code documentation.
+It is work in progress. Please visit us soon for updates.
+
+|under-construction|

_sources/config.rst.txt

@@ -0,0 +1,74 @@
+Configuration Options
+=====================
+
+.. _G-Res: https://www.hydropower.org/publications/the-ghg-reservoir-tool-g-res-technical-documentation
+.. _RE-Emission: https://github.com/tomjanus/reemission
+.. _Pfaffstetter: https://proceedings.esri.com/library/userconf/proc01/professional/papers/pap1008/p1008.htm
+.. _GEE: https://earthengine.google.com/
+
+.. note::
+   The following configuration options are related solely to the calculations of inputs to the G-Res_ greenhouse gas emission model and its implementation in our open-source software RE-Emission_ - i.e. the initial and currently the sole utility of GeoCARET. Nevertheless, as we keep re-designing the software and providing new functionalities, configuring new algorithms and functions will be provided to the user as a feature, i.e. the users will be able to add new functionalities and configure them with bespoke configuration settings. Nevertheless, for the time being, the below configuration options are restricted to :doc:`ghg_emissions/index`.
+
+Configuration file ``delineator/heet_config.py`` contains a number of user-specified parameters that affect the way that core calculations are carried out.
+
+.. attention::
+   Please note that changing those parameters is not recommended for an average user. Sensible defaults have been set by default and should work well for most cases; we do not recommend that you change these values unless you understand the impact of doing so.
+
+Jensen Search Radius
+--------------------
+
+Before we can delineate a reservoir created via construction of a dam, we first need to find a point on the river network on wich the dam is created. This is the point at the base of the dam with the lowest elevation. Often the dam location provided in the input file is not 100% precise for calculation purposes. We need to `move` i.e. snap the original (raw) dam location so that it lies exactly on the river network before we can proceed with reservoir delineation. When snapping the raw dam location to the nearest river, in our case the HydroRivers river network, the ``jensen_search_radius`` (m) defines how far from the raw dam location we should search for a river network.
+
+.. note::
+   ``jensen_search_radius`` defaults to 1,000 metres
+
+Upstream Basin Finding Method
+-----------------------------
+
+Finding upstream (sub)basins is used in constructing a catchment of a reservoir from within a pool of smaller (sub)basins - see :doc:`algorithms` for details.
+We curently support three methods.
+
+-  ``upstreamMethod = 1``: Identify basins upstream of the snapped dam by tracing basins upstream sequentially.
+
+-  ``upstreamMethod = 2``: Identify basins upstream of the snapped dam by removing downstream basins.
+
+-  ``upstreamMethod = 3``: Identify basins upstream of the snapped dam by analysis of Pfaffstetter_ IDs.
+
+.. note::
+   By default ``upstreamMethod`` = 3
+
+Use of Digital Elevation Models (DEMs)
+--------------------------------------
+
+We currently support two digital elevation models (DEMs): the hydrologically conditioned HydroSHEDS DEM and SRTM DEM for reservoir delineation and calculation of catchment parameters.
+The DEM for reservoir delineation is set in parameter ``resHydroDEM`` while the DEM for parameter calculations is set in parameter ``paramHydroDEM``.
+
+.. note::
+   A hydrologically conditioned Digital Elevation Model (DEM) is a type of elevation data (most often a raster data) that has been processed to ensure that water flow paths, such as rivers and streams, follow natural drainage patterns without artificial barriers or errors. This conditioning involves modifying the DEM to correct any discrepancies, such as filling in depressions (sinks) or removing obstacles that would disrupt the natural flow of water. The DEM is additionally aligned with the river network (a separate layer of a vector form) such that the river network follows the natural drainage patterns delineated by the DEM.
+
+Setting ``resHydroDEM`` or ``paramHydroDEM`` to ``True`` indicates seletion of the hydrologically conditioned DEM.
+
+The parameter ``hydrodataset`` takes values either “03” or “15” and is used to select the resolution of the hydrologically conditioned DEM (either 3 or 15 Arc seconds). The SRTM DEM is provided at a 30m, (1 Arc second) resolution only.
+
+.. note::
+   Default parametrs are:
+
+   -  ``resHydroDEM`` defaults to True
+   -  ``paramHydroDEM`` defaults to True
+   -  ``hydrodataset`` defaults to “03”
+
+Use of dam location for reservoir delineation
+---------------------------------------------
+
+Parameter ``delineate_snapped`` is used to choose whether the **raw** or **snapped** (see also `Jensen Search Radius`_) dam location is used for reservoir delineation. ``delineate_snapped`` defaults to True.
+
+Export Options
+--------------
+
+Upon finishing calculations the results are located in files on Google Earth Engine (GEE_). The users have an option to export the results to Google Drive automatically after the calculations have finished. The users can also view and analyse the results in the GEE_'s graphical user interface (GUI). See the options below.
+
+-  ``export_to_drive`` is used to choose whether to automatically export results to Google Drive (Defaults to False)
+-  ``direct_to_vis`` is used to choose whether the user is directed to a visualiation script on job completion (Defaults to True)
+
+.. note::
+   The users can also export the results to Google Drive manually using the ``heet_export_cli.py`` script located in the GeoCARET's' root (main) installation folder.

_sources/ghg_emissions/alternative_outputs.rst.txt

@@ -0,0 +1,200 @@
+Alternative Parameters and Definitions
+======================================
+
+.. _G-Res: https://www.hydropower.org/publications/the-ghg-reservoir-tool-g-res-technical-documentation
+
+Some of GeoCARET’s output parameters can be calculated with more than one methododology, i.e. **alternative implementation**, or from different input data, i.e. **alternative data**. 
+What follows, these output parameters have one or more alternative values.
+Where such alternative values are available, these names of those additional output parameters are suffixed with the suffix ``_alt`` followed by a number, e.g. ``_alt1``, ``_alt2`` etc. 
+Further information about the different parameter variants is provided in the description column in :ref:`output_data_specs`.
+
+The parameters with alternative values are discussed below.
+
+.. note::
+   * Some alternative parameter values are currently implemented in the code, but are not output to users as they have been withdrawn. These are designated as **DEPRECATED**. Nevertheless, they may be of interest to future developers.
+   * Alternative values are implemented in the code for some parameters, but they are automatically assigned a value of UD (undefined) for the reason being that they are still under development. These paramters are designated as **DEV**. As in the previous point, they may be of interest to future developers.
+
+1. Mean Annual Runoff
+---------------------
+
+.. hint::
+   Catchment parameter
+
+Three alternative methods are supported:
+
+Default Definition
+~~~~~~~~~~~~~~~~~~
+
+By deafault, mean annual runoff, ``c_mar_mm`` [mm/year] is extracted and spatially averaged from the global composite runoff fields provided by `Fekete(2002) <https://www.compositerunoff.sr.unh.edu/>`__.
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+   DEPRECATED
+
+``c_mar_mm_alt1`` is the long term mean annual total runoff (sum of of storm surface runoff, baseflow-groundwater runoff and snow melt) provided in `GLDAS <https://developers.google.com/earth-engine/datasets/catalog/NASA_GLDAS_V021_NOAH_G025_T3H#bands>`__.
+
+This calculation method has been deprecated due to long calculation times due to the dataset's very fine temporal resolution.
+The dataset in the form of time series is provided at a 3hr period, what adds to the computational burden during aggregation over many years. 
+
+.. note::
+   The data uses calendar, NOT hydrological year.
+
+Alternative Definition 2
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``c_mar_mm_alt2`` is the long term annual mean (2000-2019) of the runoff variable in [mm] provided by `TerraClimate <https://developers.google.com/earth-engine/datasets/catalog/IDAHO_EPSCOR_TERRACLIMATE#citations>`__
+
+.. note::
+   The data uses calendar, NOT hydrological year.
+
+2. Maximum Depth
+----------------
+
+.. hint::
+   Reservoir parameter
+
+Three alternative methods are supported:
+
+Default Definition 1
+~~~~~~~~~~~~~~~~~~~~
+
+The default calculation of the maximum depth of the reservoir, ``r_max_depth`` uses the following approach:
+
+.. math:: 
+   :nowrap:
+   
+   \begin{equation}
+     Maximum \; Depth = \textrm{Max}(Water \; Surface \; Elevation - Land \; Elevation)
+   \end{equation}
+   
+where:
+
+.. math:: Water \; Surface \; Elevation = Elevation_{dam} + Water \; Level_{reservoir}
+
+The elevation of the reservoir water surface is estimated from either:
+
+(i) full supply level (m.a.s.l) 
+(ii) the elevation of the base of the dam + the dam height.
+
+.. hint::
+   For some hydroelectric dams, we can back-calculate the dam height from the power equation if e.g. flow and power production are given.
+
+The depth at each point on the reservoir is determined by subtracting the land elevation from the water surface elevation at each pixel.
+The maximum depth is then taken as the maximum of theses values.
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this alternative implementation (``r_max_depth_alt1``), the deepest location on the reservoir is assumed to be at the dam wall. 
+
+.. note:: 
+   This assumption is also made in the calculation of reservoir's 'maximum depth in G-Res_. 
+
+The minimum elevation at the dam point location is subtracted from the maximum elevation over the area of the reservoir to provide the maximum depth of the reservoir:
+
+.. math:: 
+   Maximum \; Depth = Maximum \; Elevation_{reservoir} - Elevation_{dam}
+
+.. _alternative-definition-2-1:
+
+Alternative Definition 2
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this alternative implementation (```r_max_depth_alt2``), the deepest location on the reservoir is taken as the difference between the highest and the lowest elevation determined over the area of the reservoir:
+
+.. math:: 
+   Maximum \; Depth = Maximum \; Elevation_{reservoir} - Minimum \; Elevation_{reservoir}
+
+This calculation should provide identical results to the default calculation methods, but at the benefit of requiring a simpler Earth Engine calculation method. 
+
+.. hint::
+   Developers should consider replacing ``r_max_depth_alt`` with ``r_max_depth_alt2``.
+
+3. Mean Global Horizontal Radiance
+----------------------------------
+
+.. hint::
+   Reservoir parameter
+
+Two different implementations of mean annual global horizontal radiance are supported:
+
+.. _default-definition-2:
+
+Default Definition
+~~~~~~~~~~~~~~~~~~
+
+By default the mean annual global horizontal radiance (``r_mghr_*``) values are extracted from the NASA/SSE Irradiance Data 1983-2005 GIS layer.
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+   DEV
+
+The alternative definition of mean annual global horizontal radiance (``r_mghr_*_alt1``) is calculated as the MGHR [:math:`kWh\;m^{-2}\;d^{-1}`] from the long term annual mean (2000-2019) of downward surface shortwave radiation (srad) [:math:`W/m^{2}`] from TerraClimate. The procedure requires a series of unit conversions.
+
+4. Soil Moisture
+----------------
+
+.. hint::
+   Catchment parameter
+
+Calculation of soil moisture is done with two alternative methods that use two different data sources.
+
+.. _default-definition-3:
+
+Default Definition
+~~~~~~~~~~~~~~~~~~
+
+``c_masm_mm``, i.e. mean annual soil moisture, is calculated as a long term mean (2000-2019) of monthly values from the soil field of TerraClimate *“Soil moisture, derived using a one-dimensional soil water balance model”* [mm/m].
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+   DEPRECATED
+
+This alternative definition (``c_masm_mm_alt1``) calculates the mean annual soil moisture as the long term mean (2016-2021) of monthly values from the ``smp`` field (Soil moisture profile (fraction)) of the NASA-USDA Enhanced SMAP Global Soil Moisture Dataset.
+
+5. Precipitation
+----------------
+
+.. hint::
+   Catchment parameter
+
+.. _default-definition-4:
+
+Default Definition
+~~~~~~~~~~~~~~~~~~
+
+By default, the mean annual precipitation ``c_map_mm`` is calculated from mean monthly WorldClim2 bioclimatic variables.
+
+.. _alternative-definition-1-1:
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The alternative for the mean annual precipitation (``c_map_mm_alt1``) is calculated as the long term mean (2000-2019) of monthly values from the Precipitation accumulation field of TerraClimate.
+
+6. Evapotranspiration
+---------------------
+
+.. hint::
+   Catchment parameter
+
+.. _default-definition-5:
+
+Default Definition
+~~~~~~~~~~~~~~~~~~
+
+By default, mean annual evapotranspiration ``c_mpet_mm`` is calculated as a long term mean (2000-2019) of monthly values
+from Reference evapotranspiration (ASCE Penman-Montieth) field of TerraClimate.
+
+.. _alternative-definition-1-2:
+
+Alternative Definition 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This alternative (``c_mpet_mm_alt1``) is calculated from Regridded Monthly Terrestrial Water Balance Climatologies from the University of Delaware http://climate.geog.udel.edu/~climate/html_pages/download_whc150_2.html