gval

A high-level Python framework to evaluate the skill of geospatial datasets by comparing candidates to benchmark maps producing agreement maps and metrics.

https://github.com/noaa-owp/gval

Keywords

climate earth-science environment evaluation-framework flood-inundation forecast-skill gdal geography geopandas geospatial hydrology land-surface landcover python research science spatial-analysis spatial-temporal statistics xarray

Last synced: 6 months ago · JSON representation ·

Repository

A high-level Python framework to evaluate the skill of geospatial datasets by comparing candidates to benchmark maps producing agreement maps and metrics.

Basic Info

Host: GitHub
Owner: NOAA-OWP
License: other
Language: Jupyter Notebook
Default Branch: main
Homepage: https://noaa-owp.github.io/gval/
Size: 29.8 MB

Statistics

Stars: 25
Watchers: 3
Forks: 2
Open Issues: 18
Releases: 5

Topics

climate earth-science environment evaluation-framework flood-inundation forecast-skill gdal geography geopandas geospatial hydrology land-surface landcover python research science spatial-analysis spatial-temporal statistics xarray

Created about 3 years ago · Last pushed 7 months ago

Metadata Files

Readme Changelog Contributing License Citation

README.MD

alt text alt
text

Coverage

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.

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.openrasterio('candidatemaptwoclasscategorical.tif', maskandscale=True) benchmark = rxr.openrasterio('benchmarkmaptwoclasscategorical.tif', maskandscale=True)

(agreementmap, crosstabtable, metrictable) = candidate.gval.categoricalcompare(benchmark, positivecategories=[2], negativecategories=[0, 1]) ```

Categorical Outputs

agreement_map

alt text

crosstab_table

alt text

metric_table

alt text

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.openrasterio('livneh2011precip.tif', maskandscale=True) # VIC benchmark = rxr.openrasterio('prism2011precip.tif', maskandscale=True) # PRISM

agreement, metrictable = candidate.gval.continuouscompare( benchmark, metrics=[ "coefficientofdetermination", "meanpercentageerror", "meanabsolutepercentageerror", "meannormalizedmeanabsolute_error" ] ) ```

Continuous Outputs

agreement_map

alt text

metric_table

alt text

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

benchmark_catalog

alt text

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

candidatecontinuouscatalog = pd.readcsv('candidatecatalog0.csv') benchmarkcontinuouscatalog = pd.readcsv('benchmarkcatalog0.csv')

arguments = { "candidatecatalog": candidatecontinuouscatalog, "benchmarkcatalog": benchmarkcontinuouscatalog, "on": "compareid", "agreementmapfield": "agreementmaps", "mapids": "mapid", "how": "inner", "comparetype": "continuous", "comparekwargs": { "metrics": ( "coefficientofdetermination", "meanabsoluteerror", "meanabsolutepercentageerror", ), "encodenodata": True, "nodata": -9999, }, "openkwargs": { "maskand_scale": True, "masked": True } }

agreementcontinuouscatalog = catalog_compare(**arguments) ```

Catalog Outputs

agreement_map

alt text alt
text

catalog_metrics

alt text

(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.

Contributing

Guidelines for contributing to this repository can be found at CONTRIBUTING.

Citation

Please cite our work if using this package. See 'cite this repository' in the about section on GitHub or refer to CITATION.cff

Owner

Name: NOAA-OWP
Login: NOAA-OWP
Kind: organization

Repositories: 28
Profile: https://github.com/NOAA-OWP

Citation (CITATION.cff)

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!

cff-version: 1.2.0
title: 'gval: Geospatial Evaluation Engine'
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - given-names: Fernando
    family-names: Aristizabal
    email: fernando.aristizabal@noaa.gov
    affiliation: Lynker / NOAA
    orcid: 'https://orcid.org/0000-0003-2525-4712'
  - given-names: Gregory
    family-names: Petrochenkov
    email: greg.petrochenkov@noaa.gov
    affiliation: Lynker / NOAA
    orcid: 'https://orcid.org/0000-0001-9247-821X'
repository-code: 'https://github.com/NOAA-OWP/gval'
abstract: >-
  gval (pronounced "g-val") is a high-level Python framework
  to evaluate the geospatial skill of candidate maps
  compared to benchmarks producing agreement maps and
  metrics.
keywords:
  - science
  - research
  - statistics
  - geospatial
  - environment
  - hydrology
  - flooding
  - xarray
  - geopandas
version: 0.0.0

GitHub Events

Total

Issues event: 2
Watch event: 3
Delete event: 1
Issue comment event: 1
Push event: 12
Pull request event: 5
Fork event: 2
Create event: 2

Last Year

Issues event: 2
Watch event: 3
Delete event: 1
Issue comment event: 1
Push event: 12
Pull request event: 5
Fork event: 2
Create event: 2

Committers

Last synced: over 1 year ago

All Time

Total Commits: 319
Total Committers: 5
Avg Commits per committer: 63.8
Development Distribution Score (DDS): 0.433

Past Year

Commits: 77
Committers: 2
Avg Commits per committer: 38.5
Development Distribution Score (DDS): 0.299

Top Committers

Name	Email	Commits
Gregory Petrochenkov	g**v@n**v	181
fernando-aristizabal	f**l@n**v	82
Gregory Petrochenkov	3****A	45
fernando-aristizabal	f**a@d**g	10
NickChadwick-NOAA	n**k@n**v	1

Committer Domains (Top 20 + Academic)

noaa.gov: 3 disroot.org: 1

Issues and Pull Requests

Last synced: 7 months ago

All Time

Total issues: 69
Total pull requests: 73
Average time to close issues: about 1 month
Average time to close pull requests: 3 days
Total issue authors: 5
Total pull request authors: 3
Average comments per issue: 0.45
Average comments per pull request: 0.16
Merged pull requests: 66
Bot issues: 0
Bot pull requests: 1

Past Year

Issues: 1
Pull requests: 4
Average time to close issues: 5 days
Average time to close pull requests: 6 days
Issue authors: 1
Pull request authors: 1
Average comments per issue: 2.0
Average comments per pull request: 0.0
Merged pull requests: 4
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

fernando-aristizabal (39)
GregoryPetrochenkov-NOAA (24)
mluck (1)
Dipsi27 (1)
jarq6c (1)

Pull Request Authors

GregoryPetrochenkov-NOAA (63)
fernando-aristizabal (14)
dependabot[bot] (2)

Top Labels

Issue Labels

enhancement (24) bug (8) testing (8) documentation (6) refactor (2) help wanted (1)

Pull Request Labels

enhancement (13) bug (6) testing (2) dependencies (2) documentation (1)

Packages

Total packages: 1
Total downloads:
- pypi 139 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 18
Total maintainers: 1

pypi.org: gval

Flexible, portable, and efficient geospatial evaluations for a variety of data.

Homepage: https://noaa-owp.github.io/gval/
Documentation: https://gval.readthedocs.io/
License: MIT
Latest release: 0.2.10
published 12 months ago

Versions: 18
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 139 Last month

Rankings

Dependent packages count: 7.5%

Downloads: 14.4%

Stargazers count: 16.6%

Average: 27.7%

Forks count: 30.2%

Dependent repos count: 69.8%

Maintainers (1)

gpetroch

Last synced: 7 months ago

gval

Science Score: 54.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.MD

Installation

General Use

Using GVAL

Categorical Example

Categorical Outputs

Continuous Example

Continuous Outputs

Catalog Example

Catalog Outputs

Contributing

Citation

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: gval

Rankings

Maintainers (1)