[](https://badge.fury.io/py/gval)
GVAL (pronounced "g-val") is a high-level Python framework to evaluate
the skill of geospatial datasets by comparing candidates to benchmark
maps producing agreement maps and metrics.
GVAL is intended to work on raster and vector files as xarray and
geopandas objects, respectively. Abilities to prepare or homogenize maps
for comparison are included. The comparisons are based on scoring
philosophies for three statistical data types including categorical,
continuous, and probabilistic.
See the full [documentation](https://noaa-owp.github.io/gval/).
WARNING:
- Our current public API and output formats are likely to change in the
future.
- Software is provided "AS-IS" without any guarantees. Please QA/QC your
metrics carefully until this project matures.
# Installation
## General Use
To use this package:
`pip install gval`
Or for bleeding edge updates install from the repository:
`pip install 'git+https://github.com/NOAA-OWP/gval'`
# 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
import gval
import rioxarray as rxr
candidate = rxr.open_rasterio('candidate_map_two_class_categorical.tif', mask_and_scale=True)
benchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_and_scale=True)
(agreement_map,
crosstab_table,
metric_table) = candidate.gval.categorical_compare(benchmark,
positive_categories=[2],
negative_categories=[0, 1])
```
#### Categorical Outputs
`agreement_map`
`crosstab_table`
`metric_table`
### 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`
`metric_table`
### 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`
`benchmark_catalog`
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`
 
`catalog_metrics`
(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
Guidelines for contributing to this repository can be found at
[CONTRIBUTING](https://github.com/NOAA-OWP/gval/blob/main/CONTRIBUTING.MD).
# Citation
Please cite our work if using this package. See 'cite this repository'
in the about section on [GitHub](https://github.com/NOAA-OWP/gval/) or
refer to
[CITATION.cff](https://github.com/NOAA-OWP/gval/blob/main/CITATION.cff)
Raw data
{
"_id": null,
"home_page": null,
"name": "gval",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "geospatial, evaluations",
"author": null,
"author_email": "Fernando Aristizabal <fernando.aristizabal@noaa.gov>, Gregory Petrochenkov <gregory.petrochenkov@noaa.gov>",
"download_url": "https://files.pythonhosted.org/packages/af/c4/96cbc09db0ed36051752a535491a28f6585186226e9bb4e007f9ce7ecafc/gval-0.2.9.tar.gz",
"platform": null,
"description": " \n\n[](https://badge.fury.io/py/gval)\n\nGVAL (pronounced \"g-val\") is a high-level Python framework to evaluate\nthe skill of geospatial datasets by comparing candidates to benchmark\nmaps producing agreement maps and metrics.\n\nGVAL is intended to work on raster and vector files as xarray and\ngeopandas objects, respectively. Abilities to prepare or homogenize maps\nfor comparison are included. The comparisons are based on scoring\nphilosophies for three statistical data types including categorical,\ncontinuous, and probabilistic.\n\nSee the full [documentation](https://noaa-owp.github.io/gval/).\n\nWARNING:\n\n- Our current public API and output formats are likely to change in the\n future.\n- Software is provided \"AS-IS\" without any guarantees. Please QA/QC your\n metrics carefully until this project matures.\n\n# Installation\n\n## General Use\n\nTo use this package:\n\n`pip install gval`\n\nOr for bleeding edge updates install from the repository:\n\n`pip install 'git+https://github.com/NOAA-OWP/gval'`\n\n# Using GVAL\n\n### Categorical Example\n\nAn example of running the entire process for two-class categorical\nrasters with one function using minimal arguments is demonstrated below:\n\n``` python\nimport gval\nimport rioxarray as rxr\n\ncandidate = rxr.open_rasterio('candidate_map_two_class_categorical.tif', mask_and_scale=True)\nbenchmark = rxr.open_rasterio('benchmark_map_two_class_categorical.tif', mask_and_scale=True)\n\n(agreement_map,\n crosstab_table,\n metric_table) = candidate.gval.categorical_compare(benchmark,\n positive_categories=[2],\n negative_categories=[0, 1])\n```\n\n#### Categorical Outputs\n\n`agreement_map`\n\n\n\n`crosstab_table`\n\n\n\n`metric_table`\n\n\n\n### Continuous Example\n\nThe same can be done for rasters with continuous valued statistical data\ntypes as shown below (in this case only a subset of the default\nstatistics will be run):\n\n``` python\nimport gval\nimport rioxarray as rxr\n\ncandidate = rxr.open_rasterio('livneh_2011_precip.tif', mask_and_scale=True) # VIC\nbenchmark = rxr.open_rasterio('prism_2011_precip.tif', mask_and_scale=True) # PRISM\n\nagreement, metric_table = candidate.gval.continuous_compare(\n benchmark,\n metrics=[\n \"coefficient_of_determination\",\n \"mean_percentage_error\",\n \"mean_absolute_percentage_error\",\n \"mean_normalized_mean_absolute_error\"\n ]\n)\n```\n\n#### Continuous Outputs\n\n`agreement_map`\n\n\n\n`metric_table`\n\n\n\n### Catalog Example\n\nEntire catalogs can be compared in GVAL, which are represented by\ndataframes of maps. The following is a candidate and benchmark catalog\nfor continuous datasets:\n\n`candidate_catalog`\n\n\n\n`benchmark_catalog`\n\n\n\nWith the following code a comparison of each pair of maps can be run\nwith the following code. Since the parameter `agreement_map_field` is\nprovided the column `agreement_maps` found in the candidate catalog will\nbe used to export the agreement map to that location. (Note the first\npair of candidate and benchmark maps are single band rasters while the\nsecond pair are multiband rasters):\n\n``` python\nimport pandas as pd\n\nfrom gval.catalogs.catalogs import catalog_compare\n\ncandidate_continuous_catalog = pd.read_csv('candidate_catalog_0.csv')\nbenchmark_continuous_catalog = pd.read_csv('benchmark_catalog_0.csv')\n\narguments = {\n \"candidate_catalog\": candidate_continuous_catalog,\n \"benchmark_catalog\": benchmark_continuous_catalog,\n \"on\": \"compare_id\",\n \"agreement_map_field\": \"agreement_maps\",\n \"map_ids\": \"map_id\",\n \"how\": \"inner\",\n \"compare_type\": \"continuous\",\n \"compare_kwargs\": {\n \"metrics\": (\n \"coefficient_of_determination\",\n \"mean_absolute_error\",\n \"mean_absolute_percentage_error\",\n ),\n \"encode_nodata\": True,\n \"nodata\": -9999,\n },\n \"open_kwargs\": {\n \"mask_and_scale\": True,\n \"masked\": True\n }\n}\n\nagreement_continuous_catalog = catalog_compare(**arguments)\n```\n\n#### Catalog Outputs\n\n`agreement_map`\n\n \n\n`catalog_metrics`\n\n\n\n(Note that both catalog level attributes in the candidate and benchmark\ncatalogs are present in the catalog metrics table.)\n\nFor more detailed examples of how to use this software, check out these\n[notebook\ntutorials](https://github.com/NOAA-OWP/gval/blob/main/notebooks).\n\n# Contributing\n\nGuidelines for contributing to this repository can be found at\n[CONTRIBUTING](https://github.com/NOAA-OWP/gval/blob/main/CONTRIBUTING.MD).\n\n# Citation\n\nPlease cite our work if using this package. See 'cite this repository'\nin the about section on [GitHub](https://github.com/NOAA-OWP/gval/) or\nrefer to\n[CITATION.cff](https://github.com/NOAA-OWP/gval/blob/main/CITATION.cff)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flexible, portable, and efficient geospatial evaluations for a variety of data.",
"version": "0.2.9",
"project_urls": {
"Homepage": "https://noaa-owp.github.io/gval/",
"Repository": "https://github.com/NOAA-OWP/gval"
},
"split_keywords": [
"geospatial",
" evaluations"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a4fea6ea4cb2e4dc2440e121f321ca470074b6b4080110448d289954924b366",
"md5": "24c5083cb1333bf5c9a5d852fcc8c58f",
"sha256": "dd3eba3546dddfd537445f3a7053a24fa3a553ba25566d604c3bf523c12bd4c3"
},
"downloads": -1,
"filename": "gval-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24c5083cb1333bf5c9a5d852fcc8c58f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 70537,
"upload_time": "2024-10-10T04:30:24",
"upload_time_iso_8601": "2024-10-10T04:30:24.856600Z",
"url": "https://files.pythonhosted.org/packages/9a/4f/ea6ea4cb2e4dc2440e121f321ca470074b6b4080110448d289954924b366/gval-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "afc496cbc09db0ed36051752a535491a28f6585186226e9bb4e007f9ce7ecafc",
"md5": "8c94503a319fe27599146e4785d6f437",
"sha256": "7d7996bf4e05c5ce577bcd328819313abd57acb4b11eac3d82d34fbf0cdf9c0b"
},
"downloads": -1,
"filename": "gval-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "8c94503a319fe27599146e4785d6f437",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 73813,
"upload_time": "2024-10-10T04:30:26",
"upload_time_iso_8601": "2024-10-10T04:30:26.598789Z",
"url": "https://files.pythonhosted.org/packages/af/c4/96cbc09db0ed36051752a535491a28f6585186226e9bb4e007f9ce7ecafc/gval-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 04:30:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NOAA-OWP",
"github_project": "gval",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "rioxarray",
"specs": [
[
">=",
"0.13.4"
]
]
},
{
"name": "dask",
"specs": [
[
">=",
"2023.5.0"
],
[
"<",
"2025"
]
]
},
{
"name": "pandera",
"specs": [
[
"==",
"0.15.1"
]
]
},
{
"name": "shapely",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "geocube",
"specs": [
[
">=",
"0.3.3"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.0.2"
]
]
},
{
"name": "odc-geo",
"specs": [
[
"==",
"0.4.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"1.10.13"
]
]
},
{
"name": "rio-cogeo",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.7.1"
]
]
},
{
"name": "contextily",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "flox",
"specs": [
[
"==",
"0.7.2"
]
]
},
{
"name": "xskillscore",
"specs": [
[
"==",
"0.0.24"
]
]
},
{
"name": "pyogrio",
"specs": [
[
">=",
"0.7.2"
],
[
"<=",
"0.8.0"
]
]
},
{
"name": "pystac-client",
"specs": [
[
"==",
"0.7.5"
]
]
},
{
"name": "s3fs",
"specs": [
[
"<=",
"2023.12.1"
]
]
}
],
"lcname": "gval"
}
JSON
