diff --git a/DESCRIPTION b/DESCRIPTION index e21b3b5c..66eff02d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -34,7 +34,7 @@ Config/testthat/edition: 3 Encoding: UTF-8 Language: en-GB Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 Collate: 'register.R' 'calc_biome.R' @@ -55,6 +55,7 @@ Collate: 'get_resources.R' 'calc_indicators.R' 'calc_ipbes_biomes.R' + 'calc_key_biodiversity_areas.R' 'calc_landcover.R' 'calc_mangroves_area.R' 'calc_population_count.R' @@ -83,6 +84,7 @@ Collate: 'get_gsw.R' 'get_hfp.R' 'get_ipbes_biomes.R' + 'get_key_biodiversity_areas.R' 'get_mcd64A1.R' 'get_nasa_grace.R' 'get_nasa_srtm.R' diff --git a/NAMESPACE b/NAMESPACE index ec524b58..785ef7d4 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -19,6 +19,7 @@ export(calc_humanfootprint) export(calc_indicators) export(calc_ipbes_biomes) export(calc_irr_carbon) +export(calc_key_biodiversity_area) export(calc_landcover) export(calc_man_carbon) export(calc_mangroves_area) @@ -55,6 +56,7 @@ export(get_gmw) export(get_humanfootprint) export(get_ipbes_biomes) export(get_irr_carbon) +export(get_key_biodiversity_areas) export(get_man_carbon) export(get_mcd64a1) export(get_nasa_grace) diff --git a/NEWS.md b/NEWS.md index c072347b..fef75c58 100644 --- a/NEWS.md +++ b/NEWS.md @@ -21,12 +21,14 @@ - `get_chelsa()` - `get_ipbes_biomes()` - `get_humanfootprint()` + - `get_key_biodiversity_areas()` - `get_vul_carbon()`, `get_man_carbon()`, and `get_irr_carbon()` - new indicators: - - `calc_precipitation_chelsa()` - `calc_exposed_population()` - `calc_humanfootprint()` - `calc_ipbes_biomes()` + - `calc_key_biodiversity_area()` + - `calc_precipitation_chelsa()` - `calc_vul_carbon()`, `calc_man_carbon()`, and `calc_irr_carbon()` ## Bug fixes diff --git a/R/calc_key_biodiversity_areas.R b/R/calc_key_biodiversity_areas.R new file mode 100644 index 00000000..b888cf26 --- /dev/null +++ b/R/calc_key_biodiversity_areas.R @@ -0,0 +1,80 @@ +#' Calculate Key Biodiversity Areas +#' +#' This function calculates the total area of key biodiversity areas for a given +#' input polygon. +#' +#' The required resources for this indicator are: +#' - [key_biodiversity_areas] +#' +#' @name key_biodiversity_areas +#' @docType data +#' @keywords indicator +#' @format A function returning an indicator tibble with `key_biodiversity_area` +#' as variable and the total overlap area (in ha) as value. +#' @include register.R +#' @export +#' @examples +#' \dontshow{ +#' mapme.biodiversity:::.copy_resource_dir(file.path(tempdir(), "mapme-data")) +#' } +#' \dontrun{ +#' library(sf) +#' library(mapme.biodiversity) +#' +#' outdir <- file.path(tempdir(), "mapme-data") +#' dir.create(outdir, showWarnings = FALSE) +#' +#' mapme_options( +#' outdir = outdir, +#' verbose = FALSE +#' ) +#' +#' kbas <- system.file("resources", "key_biodiversity_areas", "kbas.gpkg", +#' package = "mapme.biodiversity") +#' +#' aoi <- system.file("extdata", "shell_beach_protected_area_41057_B.gpkg", +#' package = "mapme.biodiversity" +#' ) %>% +#' read_sf() %>% +#' get_resources(get_key_biodiversity_area(kbas)) %>% +#' calc_indicators(calc_key_biodiversity_area()) %>% +#' portfolio_long() +#' +#' aoi +#' } +calc_key_biodiversity_area <- function() { + function(x = NULL, + key_biodiversity_areas, + name = "key_biodiversity_areas", + mode = "asset", + aggregation = "mean", + verbose = mapme_options()[["verbose"]]) { + + key_biodiversity_areas <- key_biodiversity_areas[[1]] + if (is.null(key_biodiversity_areas)) { + return(NULL) + } + if (length(key_biodiversity_areas) == 0) { + return(NULL) + } + + int_area <- suppressWarnings(st_intersection(x, key_biodiversity_areas)) + if (nrow(int_area) == 0) return(NULL) + int_area_ha <- as.numeric(sum(st_area(int_area), na.rm = TRUE) / 10000) + + results <- tibble::tibble( + datetime = as.POSIXct("2024-01-01T00:00:00Z"), + variable = "key_biodiversity_area", + unit = "ha", + value = int_area_ha + ) + + return(results) + } +} + +register_indicator( + name = "key_biodiversity_areas", + description = "Area estimation of intersection with key biodiversity areas.", + resources = "key_biodiversity_areas" +) diff --git a/R/get_key_biodiversity_areas.R b/R/get_key_biodiversity_areas.R new file mode 100644 index 00000000..62e76ef3 --- /dev/null +++ b/R/get_key_biodiversity_areas.R @@ -0,0 +1,52 @@ +#' Key Biodiversity Areas +#' +#' This resource contains outlines of key biodiversity areas, which are areas +#' representing sites with specific importance for nature conservation. +#' +#' To use this data in mapme workflows, you will have to manually download the +#' global data set and point towards its file path on your local machine. +#' Please find the available data under the source link given below. +#' +#' @name key_biodiversity_areas +#' @keywords resource +#' @param path A character vector to the key biodiversity areas GPKG file. +#' Note, that the file has to be downloaded manually. +#' @returns A function that returns an `sf` footprints object. +#' @references BirdLife International (2024). The World Database of +#' Key Biodiversity Areas. Developed by the KBA Partnership: BirdLife +#' International, International Union for the Conservation of Nature, +#' Amphibian Survival Alliance, Conservation International, Critical Ecosystem +#' Partnership Fund, Global Environment Facility, Re:wild, NatureServe, +#' Rainforest Trust, Royal Society for the Protection of Birds, Wildlife +#' Conservation Society and World Wildlife Fund. Available at +#' www.keybiodiversityareas.org. +#' @source \url{https://www.keybiodiversityareas.org/kba-data} +#' @include register.R +#' @export +get_key_biodiversity_areas <- function(path = NULL) { + + if(is.null(path) || !file.exists(path)) { + stop("Expecting path to point towards an existing file.") + } + + function( + x, + name = "key_biodiversity_areas", + type = "vector", + outdir = mapme_options()[["outdir"]], + verbose = mapme_options()[["verbose"]]) { + + bbox <- c(xmin = -180.0, ymin = -90.0, xmax = 180.0, ymax = 90.0) + tile <- st_as_sf(st_as_sfc(st_bbox(bbox, crs = "EPSG:4326"))) + tile[["source"]] <- path + make_footprints(tile, what = "vector") + } +} + +register_resource( + name = "key_biodiversity_areas", + description = "Key Biodiversity Areas", + licence = "https://www.keybiodiversityareas.org/termsofservice", + source = "https://www.keybiodiversityareas.org/kba-data", + type = "vector" +) diff --git a/README.md b/README.md index bc9c6d43..31eb4c3f 100644 --- a/README.md +++ b/README.md @@ -56,74 +56,76 @@ remotes::install_github("https://github.com/mapme-initiative/mapme.biodiversity" Below is a list of the resources currently supported by `mapme.biodiversity`. -| name | description | licence | -|:---|:---|:---| -| chelsa | Climatologies at High resolution for the Earth Land Surface Areas (CHELSA) | Unknown - Must cite! | -| chirps | Climate Hazards Group InfraRed Precipitation with Station data (CHIRPS) | CC - unknown | -| esalandcover | Copernicus Land Monitoring Service (CLMS) 100 meter land cover product | CC-BY 4.0 | -| fritz_et_al | Drivers of deforestation in the tropics | CC-BY 4.0 | -| gfw_emissions | Global Forest Watch - CO2 Emssions caused by forest cover loss | CC-BY 4.0 | -| gfw_lossyear | Global Forest Watch - Year of forest cover loss occurence | CC-BY 4.0 | -| gfw_treecover | Global Forest Watch - Percentage of canopy closure in 2000 | CC-BY 4.0 | -| global_surface_water_change | Global Surface Water - Change of water occurrence intensity | | -| global_surface_water_occurrence | Global Surface Water - Percentage of water occurrence | | -| global_surface_water_recurrence | Global Surface Water - Percentage of water recurrence | | -| global_surface_water_seasonality | Global Surface Water - Seasonality of water occurrrence | | -| global_surface_water_transitions | Global Surface Water - Transition classes | | -| gmw | Global Mangrove Watch - Vector data of mangrove extent | CC BY 4.0 | -| humanfootprint | Time series on human pressures on natural ecosystems. | CC BY 4.0 | -| ipbes_biomes | Global Assessment Report on Biodiversity and Ecosystem Services division of the earth’s surface into biomes and anthromes. | CC 4.0 | -| irr_carbon | Amount of carbon irrecoverably lost by a typical land use conversion event until mid-century. | CC NC 4.0 | -| man_carbon | Amount of carbon that is manageable by humans. | CC NC 4.0 | -| mcd64a1 | MODIS Burned Area Monthly Product (Aqua and Terra) | | -| nasa_grace | NASA Gravity Recovery And Climate Experiment (GRACE) - Measurments of Earth’s mass and water changes | | -| nasa_srtm | NASA Shuttle Radar Topography Mission (SRTM) Digital Elevation Model (DEM) | | -| nelson_et_al | Global maps of traveltime to cities | CC-BY 4.0 | -| soilgrids | ISRIC - Modelled global soil property layers | CC-BY 4.0 | -| teow | Terrestrial Ecosystems of the World (TEOW) from WWF-US | unknown | -| ucdp_ged | UCDP Georeferenced Event Dataset (UCDP GED) | CC-BY 4.0 | -| vul_carbon | Amount of carbon that is vulnerable to a typical land use conversion event. | CC NC 4.0 | -| worldclim_max_temperature | WorldClim - Monthly maximum temperature 1960 - 2021 | | -| worldclim_min_temperature | WorldClim - Monthly minimum temperature 1960 - 2021 | | -| worldclim_precipitation | WorldClim - Monthly precipitation 1960 - 2021 | | -| worldpop | WorldPop - Unconstrained Global Mosaics 2000 - 2020 | CC-BY 4.0 | +| name | description | licence | +|:---------------------------------|:---------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------| +| chelsa | Climatologies at High resolution for the Earth Land Surface Areas (CHELSA) | Unknown - Must cite! | +| chirps | Climate Hazards Group InfraRed Precipitation with Station data (CHIRPS) | CC - unknown | +| esalandcover | Copernicus Land Monitoring Service (CLMS) 100 meter land cover product | CC-BY 4.0 | +| fritz_et_al | Drivers of deforestation in the tropics | CC-BY 4.0 | +| gfw_emissions | Global Forest Watch - CO2 Emssions caused by forest cover loss | CC-BY 4.0 | +| gfw_lossyear | Global Forest Watch - Year of forest cover loss occurence | CC-BY 4.0 | +| gfw_treecover | Global Forest Watch - Percentage of canopy closure in 2000 | CC-BY 4.0 | +| global_surface_water_change | Global Surface Water - Change of water occurrence intensity | | +| global_surface_water_occurrence | Global Surface Water - Percentage of water occurrence | | +| global_surface_water_recurrence | Global Surface Water - Percentage of water recurrence | | +| global_surface_water_seasonality | Global Surface Water - Seasonality of water occurrrence | | +| global_surface_water_transitions | Global Surface Water - Transition classes | | +| gmw | Global Mangrove Watch - Vector data of mangrove extent | CC BY 4.0 | +| humanfootprint | Time series on human pressures on natural ecosystems. | CC BY 4.0 | +| ipbes_biomes | Global Assessment Report on Biodiversity and Ecosystem Services division of the earth’s surface into biomes and anthromes. | CC 4.0 | +| irr_carbon | Amount of carbon irrecoverably lost by a typical land use conversion event until mid-century. | CC NC 4.0 | +| key_biodiversity_areas | Key Biodiversity Areas | | +| man_carbon | Amount of carbon that is manageable by humans. | CC NC 4.0 | +| mcd64a1 | MODIS Burned Area Monthly Product (Aqua and Terra) | | +| nasa_grace | NASA Gravity Recovery And Climate Experiment (GRACE) - Measurments of Earth’s mass and water changes | | +| nasa_srtm | NASA Shuttle Radar Topography Mission (SRTM) Digital Elevation Model (DEM) | | +| nelson_et_al | Global maps of traveltime to cities | CC-BY 4.0 | +| soilgrids | ISRIC - Modelled global soil property layers | CC-BY 4.0 | +| teow | Terrestrial Ecosystems of the World (TEOW) from WWF-US | unknown | +| ucdp_ged | UCDP Georeferenced Event Dataset (UCDP GED) | CC-BY 4.0 | +| vul_carbon | Amount of carbon that is vulnerable to a typical land use conversion event. | CC NC 4.0 | +| worldclim_max_temperature | WorldClim - Monthly maximum temperature 1960 - 2021 | | +| worldclim_min_temperature | WorldClim - Monthly minimum temperature 1960 - 2021 | | +| worldclim_precipitation | WorldClim - Monthly precipitation 1960 - 2021 | | +| worldpop | WorldPop - Unconstrained Global Mosaics 2000 - 2020 | CC-BY 4.0 | Next, is a list of supported indicators. -| name | description | -|:---|:---| -| biome | Areal statistics of biomes from TEOW | -| burned_area | Monthly burned area detected by MODIS satellites | -| deforestation_drivers | Areal statistics of deforestation drivers | -| drought_indicator | Relative wetness statistics based on NASA GRACE | -| ecoregion | Areal statstics of ecoregions based on TEOW | -| elevation | Statistics of elevation based on NASA SRTM | -| exposed_population | Number of people exposed to conflicts based on UCDP GED | -| fatalities | Number of fatalities by group of conflict based on UCDP GED | -| gsw_change | Statistics of the surface water change layer by JRC | -| gsw_occurrence | Areal statistic of surface water based on occurrence threshold | -| gsw_recurrence | Areal statistic of surface water based on reccurence threshold | -| gsw_seasonality | Areal statistic of surface water by seasonality | -| gsw_transitions | Areal statistics of surface water grouped by transition class | -| humanfootprint | Statistics of the human footprint data set per polygon. | -| ipbes_biomes | Area distibution of IBPES biomes within a polygon. | -| irr_carbon | Statistics of irrecoverable carbon per polygon. | -| landcover | Areal statistics grouped by landcover class | -| man_carbon | Statistics of manageable carbon per polygon. | -| mangroves_area | Area covered by mangroves | -| population_count | Statistic of population counts | -| precipitation_chelsa | Statistics of CHELSA precipitation layer | -| precipitation_chirps | Statistics of CHIRPS precipitation layer | -| precipitation_wc | Statistics of WorldClim precipitation layer | -| soilproperties | Statistics of SoilGrids layers | -| temperature_max_wc | Statistics of WorldClim maximum temperature layer | -| temperature_min_wc | Statistics of WorldClim minimum temperature layer | -| traveltime | Statistics of traveltime to the clostes city grouped by city category | -| treecover_area | Area of forest cover by year | +| name | description | +|:-----------------------------|:-------------------------------------------------------------------------------| +| biome | Areal statistics of biomes from TEOW | +| burned_area | Monthly burned area detected by MODIS satellites | +| deforestation_drivers | Areal statistics of deforestation drivers | +| drought_indicator | Relative wetness statistics based on NASA GRACE | +| ecoregion | Areal statstics of ecoregions based on TEOW | +| elevation | Statistics of elevation based on NASA SRTM | +| exposed_population | Number of people exposed to conflicts based on UCDP GED | +| fatalities | Number of fatalities by group of conflict based on UCDP GED | +| gsw_change | Statistics of the surface water change layer by JRC | +| gsw_occurrence | Areal statistic of surface water based on occurrence threshold | +| gsw_recurrence | Areal statistic of surface water based on reccurence threshold | +| gsw_seasonality | Areal statistic of surface water by seasonality | +| gsw_transitions | Areal statistics of surface water grouped by transition class | +| humanfootprint | Statistics of the human footprint data set per polygon. | +| ipbes_biomes | Area distibution of IBPES biomes within a polygon. | +| irr_carbon | Statistics of irrecoverable carbon per polygon. | +| key_biodiversity_areas | Area estimation of intersection with key biodiversity areas. | +| landcover | Areal statistics grouped by landcover class | +| man_carbon | Statistics of manageable carbon per polygon. | +| mangroves_area | Area covered by mangroves | +| population_count | Statistic of population counts | +| precipitation_chelsa | Statistics of CHELSA precipitation layer | +| precipitation_chirps | Statistics of CHIRPS precipitation layer | +| precipitation_wc | Statistics of WorldClim precipitation layer | +| soilproperties | Statistics of SoilGrids layers | +| temperature_max_wc | Statistics of WorldClim maximum temperature layer | +| temperature_min_wc | Statistics of WorldClim minimum temperature layer | +| traveltime | Statistics of traveltime to the clostes city grouped by city category | +| treecover_area | Area of forest cover by year | | treecover_area_and_emissions | Area of forest cover and greenhouse gas emssions caused by forest loss by year | -| treecoverloss_emissions | Greenouse gas emissions cause by forest loss by year | -| tri | Statistics of terrain rudgedness index based on NASA SRTM DEM | -| vul_carbon | Statistics of vulnerable carbon per polygon. | +| treecoverloss_emissions | Greenouse gas emissions cause by forest loss by year | +| tri | Statistics of terrain rudgedness index based on NASA SRTM DEM | +| vul_carbon | Statistics of vulnerable carbon per polygon. | ## Usage example diff --git a/man/key_biodiversity_areas.Rd b/man/key_biodiversity_areas.Rd new file mode 100644 index 00000000..fd5f0096 --- /dev/null +++ b/man/key_biodiversity_areas.Rd @@ -0,0 +1,87 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/calc_key_biodiversity_areas.R, +% R/get_key_biodiversity_areas.R +\docType{data} +\name{key_biodiversity_areas} +\alias{key_biodiversity_areas} +\alias{calc_key_biodiversity_area} +\alias{get_key_biodiversity_areas} +\title{Calculate Key Biodiversity Areas} +\format{ +A function returning an indicator tibble with \code{key_biodiversity_area} +as variable and the total overlap area (in ha) as value. +} +\source{ +\url{https://www.keybiodiversityareas.org/kba-data} +} +\usage{ +calc_key_biodiversity_area() + +get_key_biodiversity_areas(path = NULL) +} +\arguments{ +\item{path}{A character vector to the key biodiversity areas GPKG file. +Note, that the file has to be downloaded manually.} +} +\value{ +A function that returns an \code{sf} footprints object. +} +\description{ +This function calculates the total area of key biodiversity areas for a given +input polygon. + +This resource contains outlines of key biodiversity areas, which are areas +representing sites with specific importance for nature conservation. +} +\details{ +The required resources for this indicator are: +\itemize{ +\item \link{key_biodiversity_areas} +} + +To use this data in mapme workflows, you will have to manually download the +global data set and point towards its file path on your local machine. +Please find the available data under the source link given below. +} +\examples{ +\dontshow{ +mapme.biodiversity:::.copy_resource_dir(file.path(tempdir(), "mapme-data")) +} +\dontrun{ +library(sf) +library(mapme.biodiversity) + +outdir <- file.path(tempdir(), "mapme-data") +dir.create(outdir, showWarnings = FALSE) + +mapme_options( + outdir = outdir, + verbose = FALSE +) + +kbas <- system.file("resources", "key_biodiversity_areas", "kbas.gpkg", + package = "mapme.biodiversity") + +aoi <- system.file("extdata", "shell_beach_protected_area_41057_B.gpkg", + package = "mapme.biodiversity" +) \%>\% + read_sf() \%>\% + get_resources(get_key_biodiversity_area(kbas)) \%>\% + calc_indicators(calc_key_biodiversity_area()) \%>\% + portfolio_long() + +aoi +} +} +\references{ +BirdLife International (2024). The World Database of +Key Biodiversity Areas. Developed by the KBA Partnership: BirdLife +International, International Union for the Conservation of Nature, +Amphibian Survival Alliance, Conservation International, Critical Ecosystem +Partnership Fund, Global Environment Facility, Re:wild, NatureServe, +Rainforest Trust, Royal Society for the Protection of Birds, Wildlife +Conservation Society and World Wildlife Fund. Available at +www.keybiodiversityareas.org. +} +\keyword{indicator} +\keyword{resource} diff --git a/tests/testthat/test-calc_key_biodiversity_area.R b/tests/testthat/test-calc_key_biodiversity_area.R new file mode 100644 index 00000000..372c0017 --- /dev/null +++ b/tests/testthat/test-calc_key_biodiversity_area.R @@ -0,0 +1,27 @@ +test_that("calc_key_biodiversity_areas works", { + sample_path <- system.file("extdata", "shell_beach_protected_area_41057_B.gpkg", + package = "mapme.biodiversity") + x <- read_sf(sample_path) + x_area <- as.numeric(st_area(x)) + x_area <- x_area / 10000 + + .clear_resources() + outdir <- tempfile() + dir.create(outdir) + mapme_options(outdir = outdir, verbose = FALSE) + get_resources(x, get_key_biodiversity_areas(path = sample_path)) + kbas <- prep_resources(x)[["key_biodiversity_areas"]] + + kb <- calc_key_biodiversity_area() + + expect_null(kb(x, key_biodiversity_areas = NULL)) + expect_null(kb(x, key_biodiversity_areas = head(x, 0))) + + result <- kb(x, kbas) + expect_silent(.check_single_asset(result)) + expect_equal(result$value, x_area, tolerance = 0.01) + + st_geometry(x) <- st_geometry(x) + 5 + st_crs(x) <- st_crs(4326) + expect_equal(kb(x, kbas), NULL) +}) diff --git a/tests/testthat/test-get_key_biodiversity_areas.R b/tests/testthat/test-get_key_biodiversity_areas.R new file mode 100644 index 00000000..55afc5e7 --- /dev/null +++ b/tests/testthat/test-get_key_biodiversity_areas.R @@ -0,0 +1,26 @@ +test_that("get_key_biodiversity_areas works", { + sample_path <- system.file("extdata", "sierra_de_neiba_478140.gpkg", + package = "mapme.biodiversity" + ) + aoi <- read_sf(sample_path) + aoi <- suppressWarnings(st_cast(aoi, to = "POLYGON")[1, ]) + + expect_error( + get_resources(aoi, get_key_biodiversity_areas()), + "Expecting path to point towards an existing file." + ) + expect_error( + get_resources(aoi, get_key_biodiversity_areas("")), + "Expecting path to point towards an existing file." + ) + expect_error( + get_resources(aoi, get_key_biodiversity_areas(NULL)), + "Expecting path to point towards an existing file." + ) + + res <- get_resources(aoi, get_key_biodiversity_areas(sample_path)) + expect_equal( + names(prep_resources(res)), + "key_biodiversity_areas" + ) +})