Merge pull request #176 from NOAA-OWP/stac_client

Stac Client IO and Documentation Changes
NOAA-OWP · Dec 31, 2023 · 2eeb8e1 · 2eeb8e1
2 parents 0cb9654 + 0183a9c
commit 2eeb8e1
Show file tree

Hide file tree

Showing 27 changed files with 1,246 additions and 153 deletions.
diff --git a/README.MD b/README.MD
@@ -38,6 +38,8 @@ Or for bleeding edge updates install from the repository:
 
 # Using GVAL
 
+### Categorical Example
+
 An example of running the entire process for two-class categorical
 rasters with one function using minimal arguments is demonstrated below:
 
@@ -55,7 +57,7 @@ benchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_an
                                                    negative_categories=[0, 1])
 ```
 
-### Outputs
+#### Categorical Outputs
 
 `agreement_map`
 
@@ -69,8 +71,112 @@ benchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_an
 
 ![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/metric_table.png)
 
-For more details on how to use this software, check out this [notebook
-tutorial](https://github.com/NOAA-OWP/gval/blob/main/notebooks/Tutorial.ipynb).
+### Continuous Example
+
+The same can be done for rasters with continuous valued statistical data
+types as shown below (in this case only a subset of the default
+statistics will be run):
+
+``` python
+import gval
+import rioxarray as rxr
+
+candidate = rxr.open_rasterio('livneh_2011_precip.tif', mask_and_scale=True) # VIC
+benchmark = rxr.open_rasterio('prism_2011_precip.tif', mask_and_scale=True) # PRISM
+
+agreement, metric_table = candidate.gval.continuous_compare(
+    benchmark,
+    metrics=[
+        "coefficient_of_determination",
+        "mean_percentage_error",
+        "mean_absolute_percentage_error",
+        "mean_normalized_mean_absolute_error"
+    ]
+)
+```
+
+#### Continuous Outputs
+
+`agreement_map`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/continuous_agreement_map.png)
+
+`metric_table`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/continuous_metric_table.png)
+
+### Catalog Example
+
+Entire catalogs can be compared in GVAL, which are represented by
+dataframes of maps. The following is a candidate and benchmark catalog
+for continuous datasets:
+
+`candidate_catalog`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/candidate_catalog.png)
+
+`benchmark_catalog`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/benchmark_catalog.png)
+
+With the following code a comparison of each pair of maps can be run
+with the following code. Since the parameter `agreement_map_field` is
+provided the column `agreement_maps` found in the candidate catalog will
+be used to export the agreement map to that location. (Note the first
+pair of candidate and benchmark maps are single band rasters while the
+second pair are multiband rasters):
+
+``` python
+import pandas as pd
+
+from gval.catalogs.catalogs import catalog_compare
+
+candidate_continuous_catalog = pd.read_csv('candidate_catalog_0.csv')
+benchmark_continuous_catalog = pd.read_csv('benchmark_catalog_0.csv')
+
+arguments = {
+    "candidate_catalog": candidate_continuous_catalog,
+    "benchmark_catalog": benchmark_continuous_catalog,
+    "on": "compare_id",
+    "agreement_map_field": "agreement_maps",
+    "map_ids": "map_id",
+    "how": "inner",
+    "compare_type": "continuous",
+    "compare_kwargs": {
+        "metrics": (
+            "coefficient_of_determination",
+            "mean_absolute_error",
+            "mean_absolute_percentage_error",
+        ),
+        "encode_nodata": True,
+        "nodata": -9999,
+    },
+    "open_kwargs": {
+        "mask_and_scale": True,
+        "masked": True
+    }
+}
+
+agreement_continuous_catalog = catalog_compare(**arguments)
+```
+
+#### Catalog Outputs
+
+`agreement_map`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/catalog_agreement_map.png) ![alt
+text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/catalog_agreement_map2.png)
+
+`catalog_metrics`
+
+![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/catalog_metric_table.png)
+
+(Note that both catalog level attributes in the candidate and benchmark
+catalogs are present in the catalog metrics table.)
+
+For more detailed examples of how to use this software, check out these
+[notebook
+tutorials](https://github.com/NOAA-OWP/gval/blob/main/notebooks).
 
 # Contributing
 

diff --git a/docs/compile_readme_and_arrange_docs.py b/docs/compile_readme_and_arrange_docs.py
@@ -115,6 +115,62 @@ def compile_readme() -> None:
         'width="700" height="180" />',
     )
 
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "continuous_agreement_map.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'continuous_agreement_map.png" '
+        'width="500" height="150" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "continuous_metric_table.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'continuous_metric_table.png" '
+        'width="700" height="180" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "candidate_catalog.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'candidate_catalog.png" '
+        'width="450" height="120" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "benchmark_catalog.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'benchmark_catalog.png" '
+        'width="350" height="120" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "catalog_agreement_map.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'catalog_agreement_map.png" '
+        'width="500" height="150" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "catalog_agreement_map2.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'catalog_agreement_map2.png" '
+        'width="700" height="180" />',
+    )
+
+    sphinx_contents = sphinx_contents.replace(
+        "![alt text](https://github.com/NOAA-OWP/gval/raw/main/docs/images/"
+        "catalog_metric_table.png)",
+        '<img src="https://github.com/NOAA-OWP/gval/raw/main/docs/images/'
+        'catalog_metric_table.png" '
+        'width="700" height="450" />',
+    )
+
     sphinx_contents = sphinx_contents.replace(
         "\nSee the full documentation [here](noaa-owp.github.io/gval/).\n", ""
     )

diff --git a/docs/images/benchmark_catalog.png b/docs/images/benchmark_catalog.png
diff --git a/docs/images/candidate_catalog.png b/docs/images/candidate_catalog.png
diff --git a/docs/images/catalog_agreement_map.png b/docs/images/catalog_agreement_map.png
diff --git a/docs/images/catalog_agreement_map2.png b/docs/images/catalog_agreement_map2.png
diff --git a/docs/images/catalog_metric_table.png b/docs/images/catalog_metric_table.png
diff --git a/docs/images/continuous_agreement_map.png b/docs/images/continuous_agreement_map.png
diff --git a/docs/images/continuous_metric_table.png b/docs/images/continuous_metric_table.png
diff --git a/docs/markdown/04_EXAMPLE.MD b/docs/markdown/04_EXAMPLE.MD
@@ -1,5 +1,6 @@
 # Using GVAL
 
+### Categorical Example
 An example of running the entire process for two-class categorical rasters with one function using minimal arguments is demonstrated below:
 
 ```python
@@ -16,7 +17,7 @@ benchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_an
                                                    negative_categories=[0, 1])
 ```
 
-### Outputs
+#### Categorical Outputs
 
 `agreement_map`
 
@@ -30,5 +31,104 @@ benchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_an
 
 ![alt text](../images/metric_table.png)
 
-For more details on how to use this software, check out this
-[notebook tutorial](https://github.com/NOAA-OWP/gval/blob/main/notebooks/Tutorial.ipynb).
+### Continuous Example
+
+The same can be done for rasters with continuous valued statistical data types as shown below (in this case only a
+subset of the default statistics will be run):
+
+```python
+import gval
+import rioxarray as rxr
+
+candidate = rxr.open_rasterio('livneh_2011_precip.tif', mask_and_scale=True) # VIC
+benchmark = rxr.open_rasterio('prism_2011_precip.tif', mask_and_scale=True) # PRISM
+
+agreement, metric_table = candidate.gval.continuous_compare(
+    benchmark,
+    metrics=[
+        "coefficient_of_determination",
+        "mean_percentage_error",
+        "mean_absolute_percentage_error",
+        "mean_normalized_mean_absolute_error"
+    ]
+)
+```
+
+#### Continuous Outputs
+
+`agreement_map`
+
+![alt text](../images/continuous_agreement_map.png)
+
+`metric_table`
+
+![alt text](../images/continuous_metric_table.png)
+
+### Catalog Example
+
+Entire catalogs can be compared in GVAL, which are represented by dataframes of maps.  The following is a candidate
+and benchmark catalog for continuous datasets:
+
+`candidate_catalog`
+
+![alt text](../images/candidate_catalog.png)
+
+`benchmark_catalog`
+
+![alt text](../images/benchmark_catalog.png)
+
+With the following code a comparison of each pair of maps can be run with the following code.  Since the parameter
+`agreement_map_field` is provided the column `agreement_maps` found in the candidate catalog will be used to
+export the agreement map to that location. (Note the first pair of
+candidate and benchmark maps are single band rasters while the second pair are multiband rasters):
+
+```python
+import pandas as pd
+
+from gval.catalogs.catalogs import catalog_compare
+
+candidate_continuous_catalog = pd.read_csv('candidate_catalog_0.csv')
+benchmark_continuous_catalog = pd.read_csv('benchmark_catalog_0.csv')
+
+arguments = {
+    "candidate_catalog": candidate_continuous_catalog,
+    "benchmark_catalog": benchmark_continuous_catalog,
+    "on": "compare_id",
+    "agreement_map_field": "agreement_maps",
+    "map_ids": "map_id",
+    "how": "inner",
+    "compare_type": "continuous",
+    "compare_kwargs": {
+        "metrics": (
+            "coefficient_of_determination",
+            "mean_absolute_error",
+            "mean_absolute_percentage_error",
+        ),
+        "encode_nodata": True,
+        "nodata": -9999,
+    },
+    "open_kwargs": {
+        "mask_and_scale": True,
+        "masked": True
+    }
+}
+
+agreement_continuous_catalog = catalog_compare(**arguments)
+```
+
+#### Catalog Outputs
+
+`agreement_map`
+
+![alt text](../images/catalog_agreement_map.png)
+![alt text](../images/catalog_agreement_map2.png)
+
+`catalog_metrics`
+
+![alt text](../images/catalog_metric_table.png)
+
+(Note that both catalog level attributes in the candidate and benchmark catalogs are present in the catalog metrics
+table.)
+
+For more detailed examples of how to use this software, check out these
+[notebook tutorials](https://github.com/NOAA-OWP/gval/blob/main/notebooks).