| Title: | General Biodiversity Indicators for Biodiversity Data Cubes |
|---|---|
| Description: | Calculate general biodiversity indicators from GBIF data cubes. Includes many common indicators such as species richness, evenness, and completeness, which can be calculated over time (trends) or space (maps). Now also supports retaining original cell IDs. |
| Authors: | Shawn Dove [aut, cre] (ORCID: <https://orcid.org/0000-0001-9465-5638>), University of Giessen [cph], European Union [fnd] |
| Maintainer: | Shawn Dove <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.8.19 |
| Built: | 2026-05-29 09:22:05 UTC |
| Source: | https://github.com/b-cubed-eu/b3gbi |
This function calculates area-based or abundance-based rarity over a gridded map or as a time series (see 'Details' for more information).
area_rarity_map(data, ...) area_rarity_ts(data, ...) ab_rarity_map(data, ...) ab_rarity_ts(data, ...)area_rarity_map(data, ...) area_rarity_ts(data, ...) ab_rarity_map(data, ...) ab_rarity_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Rarity is the scarcity or infrequency of a particular species in an area. A rare species might have a small population size, a limited distribution, or a unique ecological niche (Maciel, 2021; Rabinowitz, 1981). Rarity can also be a biodiversity indicator when summed over multiple species in an area, and may provide important insight for determining conservation priorities. When measured over time, rarity may indicate potential threats or changes in the environment.
Abundance-based rarity is the inverse of the proportion of total occurrences represented by a particular species. The total summed rarity for each grid cell or year is calculated (sum the rarity values of each species present there). It is calculated as:
where S is the number of species and pi is the proportion of occurrences represented by species i.
Area-based rarity is the inverse of occupancy frequency (proportion of grid cells occupied) for a particular species. The total summed rarity for each grid cell or year is calculated (sum the rarity values of each species present there). It is calculated as:
where S is the number of species, N is the total number of occupied grid cells, and ni is the number of grid cells occupied by species i.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'area_rarity' or 'ab_rarity' containing the calculated indicator values and metadata.
area_rarity_map():
area_rarity_ts():
ab_rarity_map():
ab_rarity_ts():
Maciel, E. A. (2021). An index for assessing the rare species of a community. Ecological Indicators, 124, 107424.
Rabinowitz, D. (1981). Seven forms of rarity. *Biological aspects of rare * plant conservation.
compute_indicator_workflow
## Not run: arr_map <- area_rarity_map(example_cube_1, level = "country", region = "Denmark" ) plot(arr_map) ## End(Not run) ## Not run: arr_ts <- area_rarity_ts(example_cube_1, first_year = 1985) plot(arr_ts) ## End(Not run) ## Not run: abr_map <- ab_rarity_map(example_cube_1, level = "country", region = "Denmark" ) plot(abr_map) ## End(Not run) ## Not run: abr_ts <- ab_rarity_ts(example_cube_1, first_year = 1985) plot(abr_ts) ## End(Not run)## Not run: arr_map <- area_rarity_map(example_cube_1, level = "country", region = "Denmark" ) plot(arr_map) ## End(Not run) ## Not run: arr_ts <- area_rarity_ts(example_cube_1, first_year = 1985) plot(arr_ts) ## End(Not run) ## Not run: abr_map <- ab_rarity_map(example_cube_1, level = "country", region = "Denmark" ) plot(abr_map) ## End(Not run) ## Not run: abr_ts <- ab_rarity_ts(example_cube_1, first_year = 1985) plot(abr_ts) ## End(Not run)
A list of all biodiversity indicators available within the package, along with the dimensions they can be calculated across, the functions to access them, and any special arguments
available_indicatorsavailable_indicators
A special object of class 'available_indicators' containing a list of indicators and six fields with information about them
class of the indicator
name of the indicator
title to be used when plotting with automated title generation
title to be used when plotting with automated legend title generation
any transformation to perform on the legend when plotting, to improve visualization of maps
wrapper function to use when calculating indicator as a map
wrapper function to use when calculating indicator as a time series
any special arguments to consider when using the function to calculate an indicator map
any special arguments to consider when using the function to calculate an indicator time series
N/A
This function calculates bootstrap confidence intervals for a biodiversity indicator. It is called automatically when calculating a biodiversity indicator over time unless you choose 'none' for ci_type.
calc_ci(x, indicator, ...) ## Default S3 method: calc_ci(x, indicator, ...) ## S3 method for class 'total_occ' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'occ_density' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_richness_density' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'newness' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'williams_evenness' calc_ci(x, ...) ## S3 method for class 'pielou_evenness' calc_ci(x, ...) ## S3 method for class 'ab_rarity' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'area_rarity' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_occ' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_range' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...)calc_ci(x, indicator, ...) ## Default S3 method: calc_ci(x, indicator, ...) ## S3 method for class 'total_occ' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'occ_density' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_richness_density' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'newness' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'williams_evenness' calc_ci(x, ...) ## S3 method for class 'pielou_evenness' calc_ci(x, ...) ## S3 method for class 'ab_rarity' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'area_rarity' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_occ' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...) ## S3 method for class 'spec_range' calc_ci(x, indicator, num_bootstrap = 1000, ci_type = ci_type, ...)
x |
A data cube object |
indicator |
An indicator calculated over time, in the form of a data frame. *Note: this should NOT be an 'indicator_ts' object as it is meant to be called by the 'compute_indicator_workflow' function. |
... |
Additional arguments passed to specific calc_ci functions. |
num_bootstrap |
(Optional) Set the number of bootstraps to calculate for generating confidence intervals. (Default: 1000) |
ci_type |
(Optional) Type of bootstrap confidence intervals to calculate. (Default: "norm". Select "none" to avoid calculating bootstrap CIs.) |
calc_ci(total_occ): Calculate confidence intervals for total occurrences
calc_ci(occ_density): Calculate confidence intervals for occurrence density
calc_ci(spec_richness_density): Calculate confidence intervals for species richness density
calc_ci(newness): Calculate confidence intervals for newness
calc_ci(williams_evenness): Calculate confidence intervals for Williams' evenness
calc_ci(pielou_evenness): Calculate confidence intervals for Pielou's evenness
calc_ci(ab_rarity): Calculate confidence intervals for abundance-based rarity
calc_ci(area_rarity): Calculate confidence intervals for area-based rarity
calc_ci(spec_occ): Calculate confidence intervals for species occurrences
calc_ci(spec_range): Calculate confidence intervals for species range
This function provides a flexible framework for calculating various biodiversity indicators on a spatial grid or as a time series. It prepares the data, creates a grid, calculates indicators, and formats the output into an appropriate S3 object ('indicator_map'). Specific implementations for different indicator types are provided using the appropriate wrappers.
## S3 method for class 'completeness' calc_map(x, ...) ## S3 method for class 'hill0' calc_map(x, ...) ## S3 method for class 'hill1' calc_map(x, ...) ## S3 method for class 'hill2' calc_map(x, ...) ## S3 method for class 'relative_occupancy' calc_map(x, occ_type = 0, ...) ## S3 method for class 'obs_richness' calc_map(x, ...) ## S3 method for class 'total_occ' calc_map(x, ...) ## S3 method for class 'newness' calc_map(x, newness_min_year = NULL, ...) ## S3 method for class 'spec_richness_density' calc_map(x, ...) ## S3 method for class 'occ_density' calc_map(x, ...) ## S3 method for class 'williams_evenness' calc_map(x, ...) ## S3 method for class 'pielou_evenness' calc_map(x, ...) ## S3 method for class 'ab_rarity' calc_map(x, ...) ## S3 method for class 'area_rarity' calc_map(x, ...) ## S3 method for class 'spec_occ' calc_map(x, ...) ## S3 method for class 'spec_range' calc_map(x, ...) ## S3 method for class 'tax_distinct' calc_map(x, ...) calc_map(x, ...)## S3 method for class 'completeness' calc_map(x, ...) ## S3 method for class 'hill0' calc_map(x, ...) ## S3 method for class 'hill1' calc_map(x, ...) ## S3 method for class 'hill2' calc_map(x, ...) ## S3 method for class 'relative_occupancy' calc_map(x, occ_type = 0, ...) ## S3 method for class 'obs_richness' calc_map(x, ...) ## S3 method for class 'total_occ' calc_map(x, ...) ## S3 method for class 'newness' calc_map(x, newness_min_year = NULL, ...) ## S3 method for class 'spec_richness_density' calc_map(x, ...) ## S3 method for class 'occ_density' calc_map(x, ...) ## S3 method for class 'williams_evenness' calc_map(x, ...) ## S3 method for class 'pielou_evenness' calc_map(x, ...) ## S3 method for class 'ab_rarity' calc_map(x, ...) ## S3 method for class 'area_rarity' calc_map(x, ...) ## S3 method for class 'spec_occ' calc_map(x, ...) ## S3 method for class 'spec_range' calc_map(x, ...) ## S3 method for class 'tax_distinct' calc_map(x, ...) calc_map(x, ...)
x |
A data cube object ('processed_cube'). |
... |
Additional arguments passed to specific indicator calculation functions. |
occ_type |
Integer controlling the occupancy denominator (default
Note on presence-only data: All three types rely on presence-only records. A cell with no records cannot be assumed to be truly unoccupied. Types 1 and 2 condition on cells with documented occurrences, but those still reflect sampling effort rather than true species absence. Note on cell aggregation: When a coarser |
newness_min_year |
(Optional) If set, only shows values above this (e.g. 1970). Values below the minimum will be replaced with NA. This can be useful e.g. if you have outlier cells where the data is very old causing the legend gradient to stretch in a way that makes other cell values difficult to discern. |
An S3 object of the class 'indicator_map' containing the calculated indicator values and metadata.
observed_richness_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark") plot(observed_richness_map)observed_richness_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark") plot(observed_richness_map)
This function provides a flexible framework for calculating various biodiversity indicators over time. It prepares the data, creates a grid, calculates indicators, and formats the output into an appropriate S3 object ('indicator_ts'). Specific implementations for different indicator types are provided using the appropriate wrappers.
## Default S3 method: calc_ts(x, ...) ## S3 method for class 'completeness' calc_ts(x, ...) ## S3 method for class 'hill0' calc_ts(x, ...) ## S3 method for class 'hill1' calc_ts(x, ...) ## S3 method for class 'hill2' calc_ts(x, ...) ## S3 method for class 'obs_richness' calc_ts(x, ...) ## S3 method for class 'cum_richness' calc_ts(x, ...) ## S3 method for class 'total_occ' calc_ts(x, ...) ## S3 method for class 'spec_richness_density' calc_ts(x, ...) ## S3 method for class 'occ_density' calc_ts(x, ...) ## S3 method for class 'newness' calc_ts(x, ...) ## S3 method for class 'williams_evenness' calc_ts(x, ...) ## S3 method for class 'pielou_evenness' calc_ts(x, ...) ## S3 method for class 'ab_rarity' calc_ts(x, ...) ## S3 method for class 'area_rarity' calc_ts(x, ...) ## S3 method for class 'spec_occ' calc_ts(x, ...) ## S3 method for class 'spec_range' calc_ts(x, ...) ## S3 method for class 'relative_occupancy' calc_ts(x, occ_type = 0, ...) ## S3 method for class 'tax_distinct' calc_ts(x, set_rows = 1, ...) ## S3 method for class 'occ_turnover' calc_ts(x, ...) calc_ts(x, ...)## Default S3 method: calc_ts(x, ...) ## S3 method for class 'completeness' calc_ts(x, ...) ## S3 method for class 'hill0' calc_ts(x, ...) ## S3 method for class 'hill1' calc_ts(x, ...) ## S3 method for class 'hill2' calc_ts(x, ...) ## S3 method for class 'obs_richness' calc_ts(x, ...) ## S3 method for class 'cum_richness' calc_ts(x, ...) ## S3 method for class 'total_occ' calc_ts(x, ...) ## S3 method for class 'spec_richness_density' calc_ts(x, ...) ## S3 method for class 'occ_density' calc_ts(x, ...) ## S3 method for class 'newness' calc_ts(x, ...) ## S3 method for class 'williams_evenness' calc_ts(x, ...) ## S3 method for class 'pielou_evenness' calc_ts(x, ...) ## S3 method for class 'ab_rarity' calc_ts(x, ...) ## S3 method for class 'area_rarity' calc_ts(x, ...) ## S3 method for class 'spec_occ' calc_ts(x, ...) ## S3 method for class 'spec_range' calc_ts(x, ...) ## S3 method for class 'relative_occupancy' calc_ts(x, occ_type = 0, ...) ## S3 method for class 'tax_distinct' calc_ts(x, set_rows = 1, ...) ## S3 method for class 'occ_turnover' calc_ts(x, ...) calc_ts(x, ...)
x |
A data cube object ('processed_cube'). |
... |
Additional arguments passed to specific indicator calculation functions. |
occ_type |
Integer controlling the occupancy denominator (default
Note on presence-only data: All three types are computed from presence-only occurrence data. A cell with no records cannot be assumed to be truly unoccupied; it may be unsampled or under-surveyed. Types 1 and 2 partially address this by restricting the denominator to cells with documented occurrences, but they still reflect recording effort rather than true absence. Interpret all types with care. Note on cell aggregation: When a coarser |
set_rows |
Automatically select which taxonomic information to keep when there are multiple options. Default value of 1 keeps the first option, which is usually the best. |
An S3 object of the class 'indicator_ts' containing the calculated indicator values and metadata.
total_occurrences_trend <- total_occ_ts(example_cube_1) plot(total_occurrences_trend, min_year=1980)total_occurrences_trend <- total_occ_ts(example_cube_1) plot(total_occurrences_trend, min_year=1980)
Check if a given CRS is in meters or degrees.
check_crs_units(crs_input)check_crs_units(crs_input)
crs_input |
The CRS, which can be an EPSG code, WKT string, or PROJ.4 string. |
"km" if it's in meters, "degrees" if it's in degrees. Otherwise, throws an informative error.
tryCatch({ print(check_crs_units(4326)) # EPSG:4326 (degrees) print(check_crs_units(25832)) # EPSG:25832 (meters) print(check_crs_units("+proj=longlat +datum=WGS84 +no_defs")) print(check_crs_units("+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs")) print(check_crs_units("+proj=somerc +lat_0=0 +lon_0=0 +k=1 +x_0=0 +y_0=0 +ellps=WGS84 +units=km +no_defs")) # Invalid CRS print(check_crs_units("not a crs")) # Invalid CRS print(check_crs_units("+proj=lcc +lat_1=33 +lat_2=45 +lat_0=39 +lon_0=-96 +x_0=0 +y_0=0 +datum=NAD83 +units=us-ft +no_defs")) # Invalid units }, error = function(e) { print(e$message) })tryCatch({ print(check_crs_units(4326)) # EPSG:4326 (degrees) print(check_crs_units(25832)) # EPSG:25832 (meters) print(check_crs_units("+proj=longlat +datum=WGS84 +no_defs")) print(check_crs_units("+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs")) print(check_crs_units("+proj=somerc +lat_0=0 +lon_0=0 +k=1 +x_0=0 +y_0=0 +ellps=WGS84 +units=km +no_defs")) # Invalid CRS print(check_crs_units("not a crs")) # Invalid CRS print(check_crs_units("+proj=lcc +lat_1=33 +lat_2=45 +lat_0=39 +lon_0=-96 +x_0=0 +y_0=0 +datum=NAD83 +units=us-ft +no_defs")) # Invalid units }, error = function(e) { print(e$message) })
This function calculates the completeness of biodiversity data over a gridded map or as a time series using the Sample Coverage metric from the iNEXT package.
completeness_map( data, cutoff_length = 5, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) completeness_ts(data, cutoff_length = 5, gridded_average = FALSE, ...)completeness_map( data, cutoff_length = 5, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) completeness_ts(data, cutoff_length = 5, gridded_average = FALSE, ...)
data |
A data cube object (class 'processed_cube'). |
cutoff_length |
(Optional) The minimum number of species or observations required for a grid cell or time point to be included. Default is 5. |
data_type |
The type of data: "incidence" or "abundance". Default is "incidence". |
assume_freq |
(Optional) Whether to assume frequency data if using incidence. Default is FALSE. |
... |
Arguments passed on to
|
gridded_average |
(Optional) For time series, calculate completeness for each grid cell and average the results, rather than calculating for the entire area at once. Default is FALSE. |
Completeness is measured as Sample Coverage, a concept developed by Turing and Good (1953) and further popularized in ecology by Chao and Jost (2012). Sample coverage estimates the proportion of the total individuals in an ecological community that belong to the species detected in a sample.
A coverage value of 1.0 indicates that no new species are expected to be uncovered through further sampling, meaning the sample is perfectly complete. A value of 0.8, for example, suggests that 20% of the individuals in the community belong to species that have not yet been detected in the sample.
Calculating sample coverage is a prerequisite for reliable comparisons of biodiversity across different areas or time periods, as it provides a standardized measure of sample completeness that is independent of sample size alone (Chao et al., 2014).
In this package, completeness is calculated using the iNEXT package based on the observed data in each grid cell or time point.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'completeness' containing the calculated indicator values and metadata.
completeness_map():
completeness_ts():
## Not run: comp_map <- completeness_map(example_cube_1) plot(comp_map) ## End(Not run) ## Not run: comp_ts <- completeness_ts(example_cube_1, first_year = 1985) plot(comp_ts) ## End(Not run)## Not run: comp_map <- completeness_map(example_cube_1) plot(comp_map) ## End(Not run) ## Not run: comp_ts <- completeness_ts(example_cube_1, first_year = 1985) plot(comp_ts) ## End(Not run)
This function provides a flexible framework for calculating various biodiversity indicators on a spatial grid or as a time series. It prepares the data, creates a grid, calculates indicators, and formats the output into an appropriate S3 object ('indicator_map' or 'indicator_ts').
compute_indicator_workflow( data, type, dim_type = c("map", "ts"), ci_type = c("norm", "basic", "perc", "bca", "none"), cell_size = "grid", level = c("cube", "continent", "country", "world", "sovereignty", "geounit"), region = "Europe", ne_type = c("countries", "map_units", "sovereignty", "tiny_countries"), ne_scale = c("medium", "small", "large"), output_crs = NULL, first_year = NULL, last_year = NULL, spherical_geometry = TRUE, make_valid = FALSE, num_bootstrap = 100, shapefile_path = NULL, shapefile_crs = NULL, invert = FALSE, include_land = TRUE, include_ocean = TRUE, buffer_dist_km = 50, force_grid = FALSE, ... )compute_indicator_workflow( data, type, dim_type = c("map", "ts"), ci_type = c("norm", "basic", "perc", "bca", "none"), cell_size = "grid", level = c("cube", "continent", "country", "world", "sovereignty", "geounit"), region = "Europe", ne_type = c("countries", "map_units", "sovereignty", "tiny_countries"), ne_scale = c("medium", "small", "large"), output_crs = NULL, first_year = NULL, last_year = NULL, spherical_geometry = TRUE, make_valid = FALSE, num_bootstrap = 100, shapefile_path = NULL, shapefile_crs = NULL, invert = FALSE, include_land = TRUE, include_ocean = TRUE, buffer_dist_km = 50, force_grid = FALSE, ... )
data |
A data cube object (class 'processed_cube'). |
type |
The indicator to calculate. Supported options include:
|
dim_type |
(Optional) Dimension to calculate indicator over time: 'ts', or space: 'map'. (Default: 'map') |
ci_type |
(Optional) Type of bootstrap confidence intervals to calculate. (Default: "norm"). Select "none" to avoid calculating bootstrap CIs. |
cell_size |
(Optional) Length of grid cell sides, in km or degrees. If set to "grid" (default), this will use the existing grid size of your cube. If set to "auto", this will be automatically determined according to the geographical level selected. This is 100 km or 1 degree for 'continent' or 'world', 10 km or (for a degree-based CRS) the native resolution of the cube for 'country', 'sovereignty' or 'geounit'. If level is set to 'cube', cell size will be the native resolution of the cube for a degree-based CRS, or for a km-based CRS, the cell size will be determined by the area of the cube: 100 km for cubes larger than 1 million sq km, 10 km for cubes between 10 thousand and 1 million sq km, 1 km for cubes between 100 and 10 thousand sq km, and 0.1 km for cubes smaller than 100 sq km. Alternatively, the user can manually select the grid cell size (in km or degrees). Note that the cell size must be a whole number multiple of the cube's resolution. |
level |
(Optional) Spatial level: 'cube', 'continent', 'country', 'world', 'sovereignty', or 'geounit'. (Default: 'cube') |
region |
(Optional) The region of interest (e.g., "Europe"). This parameter is ignored if level is set to 'cube' or 'world'. (Default: NULL) |
ne_type |
(Optional) The type of Natural Earth data to download: 'countries', 'map_units', 'sovereignty', or 'tiny_countries'. This parameter is ignored if level is set to 'cube' or 'world'. (Default: "countries") |
ne_scale |
(Optional) The scale of Natural Earth data to download: 'small' - 110m, 'medium' - 50m, or 'large' - 10m. (Default: "medium") |
output_crs |
(Optional) The CRS you want for your calculated indicator. (Leave blank to let the function choose a default based on grid reference system.) |
first_year |
(Optional) Exclude data before this year. (Uses all data in the cube by default.) |
last_year |
(Optional) Exclude data after this year. (Uses all data in the cube by default.) |
spherical_geometry |
(Optional) If set to FALSE, will temporarily disable spherical geometry while the function runs. Should only be used to solve specific issues. (Default is TRUE). |
make_valid |
(Optional) Calls st_make_valid() from the sf package after creating the grid. Increases processing time but may help if you are getting polygon errors. (Default is FALSE). |
num_bootstrap |
(Optional) Set the number of bootstraps to calculate for generating confidence intervals. (Default: 100) |
shapefile_path |
(optional) Path of an external shapefile to merge into the workflow. For example, if you want to calculate your indicator particular features such as protected areas or wetlands. |
shapefile_crs |
(Optional) CRS of a .wkt shapefile. If your shapefile is .wkt and you do NOT use this parameter, the CRS will be assumed to be EPSG:4326 and the coordinates will be read in as lat/long. If your shape is NOT a .wkt the CRS will be determined automatically. |
invert |
(optional) Calculate an indicator over the inverse of the shapefile (e.g. if you have a protected areas shapefile this would calculate an indicator over all non protected areas within your cube). Default is FALSE. |
include_land |
(Optional) Include occurrences which fall within the land area. Default is TRUE. *Note that this purely a geographic filter, and does not filter based on whether the occurrence is actually terrestrial. Grid cells which fall partially on land and partially on ocean will be included even if include_land is FALSE. To exclude terrestrial and/or freshwater taxa, you must manually filter your data cube before calculating your indicator. |
include_ocean |
(Optional) Include occurrences which fall outside the land area. Default is TRUE. Set as "buffered_coast" to include a set buffer size around the land area rather than the entire ocean area. *Note that this is purely a geographic filter, and does not filter based on whether the occurrence is actually marine. Grid cells which fall partially on land and partially on ocean will be included even if include_ocean is FALSE. To exclude marine taxa, you must manually filter your data cube before calculating your indicator. |
buffer_dist_km |
(Optional) The distance to buffer around the land if include_ocean is set to "buffered_coast". Default is 50 km. |
force_grid |
(Optional) Forces the calculation of a grid even if this would not normally be part of the pipeline, e.g. for time series. This setting is required for the calculation of rarity or Hill diversity, and is forced on by indicators that require it. (Default: FALSE) |
... |
Additional arguments passed to specific indicator calculation functions. |
An S3 object containing the calculated indicator values and metadata.
diversity_map <- compute_indicator_workflow(example_cube_1, type = "obs_richness", dim_type = "map", level = "country", region = "Denmark" ) diversity_mapdiversity_map <- compute_indicator_workflow(example_cube_1, type = "obs_richness", dim_type = "map", level = "country", region = "Denmark" ) diversity_map
This is a helper function that takes a vector of EQDGC (Equal-Area Quarter-Degree Grid Cell) codes and converts them to their central latitude and longitude coordinates. The function parses the base coordinates and the nested sub-grid codes to precisely locate the center of each grid cell.
convert_eqdgc_latlong(cellCode)convert_eqdgc_latlong(cellCode)
cellCode |
A character vector of EQDGC cell codes, which must follow the "direction-base_coord" format (e.g., "W10N34" or "E15S20"). The code can also contain additional letter characters for sub-grids (e.g., "W10N34A"). |
The function works by first extracting the base longitude and
latitude coordinates from the cell code, accounting for direction
(East/West and North/South). It then iteratively processes any sub-grid
codes (e.g., A, B, C, D) to refine the coordinates. The final
coordinates are the center point of the most specific grid cell.
A matrix with two columns, lat and long, representing the central
coordinates of each input grid cell.
# A simple quarter-degree cell convert_eqdgc_latlong("E10N10") # A sub-grid cell convert_eqdgc_latlong("W-10S34ABCD") # Multiple cell codes convert_eqdgc_latlong(c("E10N10", "W-10S34DDBA"))# A simple quarter-degree cell convert_eqdgc_latlong("E10N10") # A sub-grid cell convert_eqdgc_latlong("W-10S34ABCD") # Multiple cell codes convert_eqdgc_latlong(c("E10N10", "W-10S34DDBA"))
This function takes a data frame with UTM coordinates (xcoord, ycoord) and a utmzone column, and creates an sf object with the correct CRS for each zone.
create_sf_from_utm(df, output_crs = NULL)create_sf_from_utm(df, output_crs = NULL)
df |
A data frame with columns: xcoord, ycoord, and utmzone. |
output_crs |
(Optional) The EPSG code or CRS string for the desired output CRS. If NULL, the CRS of the first UTM zone will be used. |
An sf object with the geometry correctly defined for each UTM zone.
This function calculates cumulative species richness as a time series (see 'Details' for more information).
cum_richness_ts(data, ...)cum_richness_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Species richness is the total number of species present in a sample (Magurran, 1988). It is a fundamental and commonly used measure of biodiversity, providing a simple and intuitive overview of the status of biodiversity. However, richness is not well suited to measuring biodiversity change over time, as it only decreases when local extinctions occur and thus lags behind abundance for negative trends. While it may act as a leading indicator of alien species invasions, it will not indicate establishment because it ignores abundance. Nor will it necessarily indicate changes in local species composition, which can occur without any change in richness. Although richness is conceptually simple, it can be measured in different ways.
Cumulative richness is calculated by adding the newly observed unique species each year to a cumulative sum. This indicator provides an estimation of whether and how many new species are still being discovered in a region. While an influx of alien species could cause an increase in cumulative richness, a fast-rising trend as shown in Fig. 2 is likely an indication that the dataset is not comprehensive and therefore observed richness will provide an underestimate of species richness.
An S3 object with the classes 'indicator_ts' and 'cum_richness' containing the calculated indicator values and metadata.
compute_indicator_workflow
## Not run: cr_ts <- cum_richness_ts(example_cube_1, first_year = 1985) plot(cr_ts) ## End(Not run)## Not run: cr_ts <- cum_richness_ts(example_cube_1, first_year = 1985) plot(cr_ts) ## End(Not run)
Small example cube containing the mammal occurrences in Denmark available on GBIF as of 16.03.2024.
example_cube_1example_cube_1
A 'processed_cube' object containing a tibble with 31,632 rows and 15 variables, as well as metadata
year occurrence was recorded
code containing the cell resolution and coordinates on the Extended Quarter Degree (eqdgc) grid
kingdom key associated with the species on GBIF
kingdom name
family key associated with the species on GBIF
family name
taxonomic key associated with the species on GBIF
scientific species name
number of individuals observed
minimum coordinate uncertainty in meters
minimum temporal uncertainty in seconds
East-West coordinate on the eqdgc grid
North-South coordinate on the eqdgc grid
grid cell size
https://doi.org/10.15468/dl.5mb887
{ ## Not run: # Basic example of how to use the dataset denmark_mammals_or_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark") plot(denmark_mammals_or_map, title = "Mammals in Denmark (1862-2024): Observed Species Richness") ## End(Not run) }{ ## Not run: # Basic example of how to use the dataset denmark_mammals_or_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark") plot(denmark_mammals_or_map, title = "Mammals in Denmark (1862-2024): Observed Species Richness") ## End(Not run) }
Example indicator containing a map of observed species richness for mammal occurrences in Denmark (occurrences from GBIF: 16.03.2024).
example_indicator_map1example_indicator_map1
An 'indicator_map' object containing a tibble with 800 rows and 5 variables, as well as metadata
id of a map cell the indicator was calculated for
area of the map cell in square kilometers
code containing the cell coordinates in Extended Quarter Degree (eqdgc) grid format
calculated richness value for the cell
geometry of the map cell
https://doi.org/10.15468/dl.5mb887
Example indicator containing a time series of observed species richness for mammal occurrences in Denmark, 1970-2024 (occurrences from GBIF: 16.03.2024).
example_indicator_ts1example_indicator_ts1
An 'indicator_ts' object containing a tibble with 55 rows and 2 variables, as well as metadata
a year the indicator was calculated for
calculated richness value for the year
ed
https://doi.org/10.15468/dl.5mb887
Example indicator containing a time series of cumulative species richness for bryophyte occurrences in South Africa, 1875-2024 (occurrences from GBIF: 16.03.2024).
example_indicator_ts2example_indicator_ts2
An 'indicator_ts' object containing a tibble with 110 rows and 2 variables, as well as metadata
a year the indicator was calculated for
calculated richness value for the year
https://doi.org/10.15468/dl.yfzgja
boot objectsThis function calculates confidence intervals for a list of objects of class
"boot" per year into a dataframe containing all required summaries.
get_bootstrap_ci(bootstrap_list, temporal_list_name = "year", ...)get_bootstrap_ci(bootstrap_list, temporal_list_name = "year", ...)
bootstrap_list |
A list of objects of class |
temporal_list_name |
(Optional) The temporal list names of
|
... |
Additional argument to be passed to the |
The returned value is a dataframe containing the time point,
the type of interval (int_type), the lower limit of the confidence
interval (ll), the upper limit of the confidence interval (ul), and the
confidence level of the intervals (conf_level).
Takes an "indicator_map", "indicator_ts", or "processed_cube" object and determines the years for which observation data exists.
get_observed_years(x)get_observed_years(x)
x |
An "indicator_map" object containing calculated indicator values associated with grid cells. |
A data frame with two columns:
years: A sequence of years covering the range of observations.
occurrences: A logical vector indicating if observations exist
for each year (TRUE if present, FALSE if absent).
total_occ_mammals_denmark <- total_occ_map(example_cube_1, level = "country", region = "Denmark") get_observed_years(total_occ_mammals_denmark)total_occ_mammals_denmark <- total_occ_map(example_cube_1, level = "country", region = "Denmark") get_observed_years(total_occ_mammals_denmark)
Use coverage-based methods to estimate Hill diversity measures over a gridded map or as a time series. Three Hill diversity measures are covered:
Species richness - hill0_map() and
hill0_ts()
Hill-Shannon diversity - hill1_map() and
hill1_ts()
Hill-Simpson diversity - hill2_map() and
hill2_ts()
(see 'Details' for more information).
hill0_map( data, coverage = 0.95, cutoff_length = 5, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill0_ts(data, coverage = 0.95, cutoff_length = 5, conf_level = 0.95, ...) hill1_map( data, cutoff_length = 5, coverage = 0.95, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill1_ts(data, cutoff_length = 5, coverage = 0.95, conf_level = 0.95, ...) hill2_map( data, cutoff_length = 5, coverage = 0.95, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill2_ts(data, cutoff_length = 5, coverage = 0.95, conf_level = 0.95, ...)hill0_map( data, coverage = 0.95, cutoff_length = 5, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill0_ts(data, coverage = 0.95, cutoff_length = 5, conf_level = 0.95, ...) hill1_map( data, cutoff_length = 5, coverage = 0.95, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill1_ts(data, cutoff_length = 5, coverage = 0.95, conf_level = 0.95, ...) hill2_map( data, cutoff_length = 5, coverage = 0.95, data_type = c("incidence", "abundance"), assume_freq = FALSE, ... ) hill2_ts(data, cutoff_length = 5, coverage = 0.95, conf_level = 0.95, ...)
data |
A data cube object (class 'processed_cube'). |
coverage |
(Optional) The sample coverage value for the estimator. Default is 0.95. |
cutoff_length |
(Optional) The minimum number of data points for each grid cell. Grid cells with fewer data points will be removed before calculations to avoid errors. Default is 5. |
data_type |
(Optional) If set to "incidence", occurrences are converted to incidence data. Observations are treated as presence/absence and years are used as sampling units. The number of years in which a species was observed within a grid cell are then summarized. If set to "abundance", occurrences are summed across years for each species as a proxy for abundance. Default is "incidence". |
assume_freq |
(Optional) If TRUE, the sum of observations for a species within a grid cell is assumed to be a sum of sampling sites in which that species was observed. The maximum number of observations for any species within a grid cell is then taken as a proxy for the total number of sampling sites for that cell. This parameter is ignored if data_type is set to "abundance". It is advisable to leave this on FALSE unless you are certain of how your data is structured. Default is FALSE. |
... |
Arguments passed on to
|
conf_level |
(Optional) Confidence level for bootstrap confidence intervals. Only applies to temporal indicators. Default is 0.95. |
Hill (1973) introduced the concept of Hill diversity, which assumes that the number and relative abundance of species are inseparable components of diversity. Hill diversity uses a single equation to calculate multiple measures of diversity by varying a single parameter ℓ, which changes the emphasis on rare vs common species (Roswell et al., 2019). It represents the mean rarity of sampled species, and is calculated as:
where D is diversity, S is the number of species, pi is the proportion of individuals belonging to species i, ri is the rarity of species i, and ℓ determines the rarity scale for the mean. While ℓ can theoretically take almost any value, three common measures of diversity are special cases: species richness, and modified versions of the Shannon and Simpson diversity indices (Roswell et al., 2019). These three measures occur when ℓ takes the value of 1, 0 (or near-zero, as ℓ cannot actually take the value of 0), or -1, respectively.
Species Richness (ℓ = 1):
Hill-Shannon Diversity (ℓ ≈ 0):
Hill-Simpson Diversity (ℓ = -1):
Richness uses an arithmetic scale (the arithmetic mean), thus giving rare species a lot of leverage. By contrast, Hill-Shannon diversity uses a logarithmic scale (the geometric mean), treating common and rare species equally, and Hill-Simpson diversity uses a reciprocal scale (the harmonic mean), giving common species higher leverage.
Hill diversity values can be estimated through different standardisation procedures as a way to mitigate the effects of sample size and sampling biases. One way to do this is by equalising sample size by calculating a species accumulation curve (a plot of cumulative species richness as a function of sample size) for each year or grid cell. The smallest sample size from among all the grid cells or years in the dataset is used as a reference to select richness values from each curve. This is called rarefaction. It is also possible to use a larger sample size as a reference, but this requires extrapolation of smaller samples, which is more prone to error than rarefaction.
However, results from sample-size based estimation can be problematic as they depend on both richness and evenness. A sample from a community with a more even distribution of individuals across species is likely to show higher richness than a sample of the same size from a community where many species are rare, as the rare species are less likely to appear in the sample. Similarly, a community containing a lot of species will appear less rich than it actually is if the sample size used for comparison is too small. Detectability also plays an important part; hard to detect species are less likely to appear in the sample, so communities in which rare species are more easily detectable are likely to yield richer samples.
Another way to estimate species richness is to standardise by coverage. The iNEXT package (Chao et al., 2014; Hsieh et al., 2016) for R is used to estimate species richness at an equal level of coverage (e.g. 0.95) for each cell or year in a biodiversity data cube. Coverage is the proportion of individuals in the community belonging to species in the sample. So, at a coverage of 0.95, 95% of individuals in the community belong to species detected in the sample while 5% belong to species that are not detected in the sample. Coverage is estimated based on the frequencies of species already in the sample. It can be illustrated using a species accumulation curve, the slope of which represents the probability of detecting a new species with the next individual you sample from a community. At a sample size of zero, the slope would be one, meaning the next individual sampled has a 100% probability of being a species not already in the sample. Therefore, a coverage value of one corresponds to the asymptote of a species accumulation curve (slope of zero), meaning no new species would be uncovered through further sampling.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'hill0' or 'hill1' or 'hill2' containing the calculated indicator values and metadata.
hill0_map():
hill0_ts():
hill1_map():
hill1_ts():
hill2_map():
hill2_ts():
Hill, M. O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54(2), 427-432.
Roswell, M., Shipley, J., & Ewers, R. M. (2019). A conceptual guide to measuring and interpreting functional diversity. Journal of Applied Ecology, 56(12), 2533-2543.
Chao, A., Gotelli, N. J., Hsieh, T. C., Sander, E. L., Ma, K. H., Colwell, R. K., & Ellison, A. M. (2014). Rarefaction and extrapolation with Hill numbers: a framework for sampling and estimation in species diversity studies. Ecological monographs, 84(1), 45-67.
Hsieh, T. C., Ma, K. H., & Chao, A. (2016). iNEXT: an R package for rarefaction and extrapolation of species diversity (Hill numbers). Methods in Ecology and Evolution, 7(12), 1451-1456.
compute_indicator_workflow
## Not run: h0_map <- hill0_map(example_cube_1, level = "country", region = "Denmark") plot(h0_map) ## End(Not run) ## Not run: h0_ts <- hill0_ts(example_cube_1, first_year = 1985) plot(h0_ts) ## End(Not run) ## Not run: h1_map <- hill1_map(example_cube_1, level = "country", region = "Denmark") plot(h1_map) ## End(Not run) ## Not run: h1_ts <- hill1_ts(example_cube_1, first_year = 1985) plot(h1_ts) ## End(Not run) ## Not run: h2_map <- hill2_map(example_cube_1, level = "country", region = "Denmark") plot(h2_map) ## End(Not run) ## Not run: h2_ts <- hill2_ts(example_cube_1, first_year = 1985) plot(h2_ts) ## End(Not run)## Not run: h0_map <- hill0_map(example_cube_1, level = "country", region = "Denmark") plot(h0_map) ## End(Not run) ## Not run: h0_ts <- hill0_ts(example_cube_1, first_year = 1985) plot(h0_ts) ## End(Not run) ## Not run: h1_map <- hill1_map(example_cube_1, level = "country", region = "Denmark") plot(h1_map) ## End(Not run) ## Not run: h1_ts <- hill1_ts(example_cube_1, first_year = 1985) plot(h1_ts) ## End(Not run) ## Not run: h2_map <- hill2_map(example_cube_1, level = "country", region = "Denmark") plot(h2_map) ## End(Not run) ## Not run: h2_ts <- hill2_ts(example_cube_1, first_year = 1985) plot(h2_ts) ## End(Not run)
Retrieves a standardized list of species names from a biodiversity data object ('processed_cube', 'indicator_map' or 'indicator_ts').
list_species(object)list_species(object)
object |
A biodiversity data object containing species names (either in
a |
A tibble with a single column:
scientificName: The unique scientific names found in the object.
list_species(example_cube_1)list_species(example_cube_1)
Converts MGRS coordinates to a single sf bounding box in a suitable projected CRS, handling data that spans multiple UTM zones.
mgrs_to_latlong_bbox(df)mgrs_to_latlong_bbox(df)
df |
A data frame with at least three columns: |
An sf bounding box (sf::st_bbox) in a single projected CRS (e.g.,
Albers).
This function estimates the relative newness of records in a data cube by calculating the mean year of occurrence over a gridded map or as a time series (see 'Details' for more information).
newness_map(data, ...) newness_ts(data, ...)newness_map(data, ...) newness_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
The mean year of occurrence is calculated per cell, giving an indication of how recent the data is for each cell. A recent mean year is not necessarily an indication of quality, as some countries or regions have been conducting comprehensive biodiversity monitoring for many years and will therefore reflect an older mean year of occurrence, while others may show a recent mean year due to e.g., the sudden availability of large amounts of citizen science data.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'newness' containing the calculated indicator values and metadata.
newness_map():
newness_ts():
compute_indicator_workflow
## Not run: n_map <- newness_map(example_cube_1, level = "country", region = "Denmark") plot(n_map) ## End(Not run) ## Not run: n_ts <- newness_ts(example_cube_1, first_year = 1985) plot(n_ts) ## End(Not run)## Not run: n_map <- newness_map(example_cube_1, level = "country", region = "Denmark") plot(n_map) ## End(Not run) ## Not run: n_ts <- newness_ts(example_cube_1, first_year = 1985) plot(n_ts) ## End(Not run)
This function calculates observed species richness over a gridded map or as a time series (see 'Details' for more information).
obs_richness_map(data, ...) obs_richness_ts(data, ...)obs_richness_map(data, ...) obs_richness_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Species richness is the total number of species present in a sample (Magurran, 1988). It is a fundamental and commonly used measure of biodiversity, providing a simple and intuitive overview of the status of biodiversity. However, richness is not well suited to measuring biodiversity change over time, as it only decreases when local extinctions occur and thus lags behind abundance for negative trends. While it may act as a leading indicator of alien species invasions, it will not indicate establishment because it ignores abundance. Nor will it necessarily indicate changes in local species composition, which can occur without any change in richness. Although richness is conceptually simple, it can be measured in different ways.
Observed richness is calculated by summing the number of unique species observed for each year or each cell. Observed richness is highly dependent on the comprehensiveness of the dataset it is being applied to. If some regions are more intensively, carefully or systematically sampled than others, this will likely reflect as higher observed richness. Observed richness also depends on the relative abundance and spatial aggregation of each species, with less abundant and less aggregated species less likely to be discovered during surveys (Hillebrand et al., 2018), as well as the detectability of each species.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'obs_richness' containing the calculated indicator values and metadata.
obs_richness_map():
obs_richness_ts():
Hillebrand, H., Blasius, B., Borer, E. T., Chase, J. M., Downing, J. A., Eriksson, B. K., Filstrup, C. T., Harpole, W. S., Hodapp, D., Larsen, S., Lewandowska, A. M., Seabloom, E. W., Van de Waal, D. B., & Ryabov, A. B. (2018). Biodiversity change is uncoupled from species richness trends: Consequences for conservation and monitoring. Journal of Applied Ecology, 55(1), 169-184.
compute_indicator_workflow
## Not run: or_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark" ) plot(or_map) ## End(Not run) ## Not run: or_ts <- obs_richness_ts(example_cube_1, first_year = 1985) plot(or_ts) ## End(Not run)## Not run: or_map <- obs_richness_map(example_cube_1, level = "country", region = "Denmark" ) plot(or_map) ## End(Not run) ## Not run: or_ts <- obs_richness_ts(example_cube_1, first_year = 1985) plot(or_ts) ## End(Not run)
This function calculates the density of records over a gridded map or as a time series (see 'Details' for more information).
occ_density_map(data, ...) occ_density_ts(data, ...)occ_density_map(data, ...) occ_density_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Density is calculated by summing the total number of occurrences per square kilometre for each cell or year. This provides similar information to total occurrences, but is adjusted for cell area.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'occ_density' containing the calculated indicator values and metadata.
occ_density_map():
occ_density_ts():
compute_indicator_workflow
## Not run: od_map <- occ_density_map(example_cube_1, level = "country", region = "Denmark" ) plot(od_map) ## End(Not run) ## Not run: od_ts <- occ_density_ts(example_cube_1, first_year = 1985) plot(od_ts) ## End(Not run)## Not run: od_map <- occ_density_map(example_cube_1, level = "country", region = "Denmark" ) plot(od_map) ## End(Not run) ## Not run: od_ts <- occ_density_ts(example_cube_1, first_year = 1985) plot(od_ts) ## End(Not run)
This function calculates occupancy turnover as a time series (see 'Details' for more information).
occ_turnover_ts(data, ...)occ_turnover_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Occupancy turnover measures the change in species composition over time, reflecting the rate at which species appear or disappear from a given area. It provides insights into the dynamic nature of ecological communities, highlighting shifts in species distributions and potential environmental changes. High turnover rates may indicate rapid community restructuring, potentially driven by factors such as habitat alteration, climate change, or invasive species. Analyzing occupancy turnover can be crucial for understanding ecosystem stability, identifying areas of conservation concern, and assessing the effectiveness of management strategies.
Occupancy turnover can be calculated in different ways, but here we use the Jaccard dissimilarity index (Jaccard, 1901) to measure the similarity between two sets of species occurrences. The Jaccard index is calculated as:
where a is the number of species present in both time periods, b is the number of species present only in the first time period, and c is the number of species present only in the second time period. The index ranges from 0 (no turnover) to 1 (complete turnover).
An S3 object with the classes 'indicator_ts' and 'occ_turnover' containing the calculated indicator values and metadata.
Jaccard, P. (1901). Étude de la distribution florale dans une portion des Alpes et du Jura. Bulletin de la Société Vaudoise des Science Naturelles, 37(142), 547-579.
compute_indicator_workflow
ot_ts <- occ_turnover_ts(example_cube_1, first_year = 1985) plot(ot_ts)ot_ts <- occ_turnover_ts(example_cube_1, first_year = 1985) plot(ot_ts)
Calculate evenness over a gridded map or as a time series (see 'Details' for more information).
pielou_evenness_map(data, ...) pielou_evenness_ts(data, ...) williams_evenness_map(data, ...) williams_evenness_ts(data, ...)pielou_evenness_map(data, ...) pielou_evenness_ts(data, ...) williams_evenness_map(data, ...) williams_evenness_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Species evenness is a commonly used indicator that measures how uniformly individuals are distributed across species in a region or over time. It provides a complement to richness by taking relative abundance into account. Although GBIF provides information about abundances as individual counts, the majority of entries lack this information. Hence, evenness can only be calculated using the proportions of observations rather than proportions of individuals. Strictly speaking, the evenness measures therefore indicate how uniformly species are represented in the respective data set rather than the true evenness of the ecological community.
Pielou's evenness (1966) is a well-known and commonly used evenness measure. It is calculated as:
where S is the number of species and pi is the proportion of occurrences represented by species i.
An analysis of evenness properties by Kvålseth (2015) showed that an evenness index introduced by Williams in 1977 in an unpublished manuscript has two important properties which Pielou's does not. The properties in question are complex mathematical properties known as the Schur-Concavity and value validity, but we attempt to describe them here more simply. If a measure of evenness is Schur-concave, it means that when the distribution of individuals becomes more evenly spread across species, the measure of evenness will stay the same or increase, but never decrease. Value validity means that an evenness index should provide sensible and meaningful values across its range for any given distribution of species abundances. Kvålseth referred to this evenness measure as E9 but we refer to it as Williams' evenness.
Williams' evenness is calculated as:
where S is the number of species and pi is the proportion of occurrences represented by species i.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'pielou_evenness' or 'williams_evenness' containing the calculated indicator values and metadata.
pielou_evenness_map():
pielou_evenness_ts():
williams_evenness_map():
williams_evenness_ts():
Pielou, E. C. (1966). The measurement of diversity in different types of biological collections. Journal of theoretical biology, 13, 131-144.
Kvålseth, T. O. (2015). Evenness indices once again: critical analysis of properties. SpringerPlus, 4, 1-12.
compute_indicator_workflow
## Not run: pe_map <- pielou_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot(pe_map) ## End(Not run) ## Not run: pe_ts <- pielou_evenness_ts(example_cube_1, first_year = 1985) plot(pe_ts) ## End(Not run) ## Not run: we_map <- williams_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot(we_map) ## End(Not run) ## Not run: we_ts <- williams_evenness_ts(example_cube_1, first_year = 1985) plot(we_ts) ## End(Not run)## Not run: pe_map <- pielou_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot(pe_map) ## End(Not run) ## Not run: pe_ts <- pielou_evenness_ts(example_cube_1, first_year = 1985) plot(pe_ts) ## End(Not run) ## Not run: we_map <- williams_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot(we_map) ## End(Not run) ## Not run: we_ts <- williams_evenness_ts(example_cube_1, first_year = 1985) plot(we_ts) ## End(Not run)
Creates a map visualization of a calculated multi-species
biodiversity indicator. Requires an indicator_map object as input. To plot
single-species indicators, use the plot_species_map() function
instead.
plot_map( x, title = "auto", auto_title = NULL, leg_label_default = NULL, xlims = NULL, ylims = NULL, trans = NULL, bcpower = NULL, breaks = NULL, labels = NULL, output_crs = NULL, crop_to_grid = NULL, crop_by_region = FALSE, ocean_fill_colour = NULL, land_fill_colour = NULL, grid_fill_colour = NULL, grid_line_colour = NULL, grid_line_width = NULL, grid_fill_transparency = NULL, grid_line_transparency = NULL, legend_title = NULL, legend_limits = NULL, legend_title_wrap_length = 10, title_wrap_length = 60, visible_gridlines = TRUE, visible_panel_gridlines = FALSE, map_expansion_factor = 0.1, layers = NULL, layer_colours = NULL, layer_fill_colours = NULL, scale = c("medium", "small", "large"), filter_outliers = FALSE )plot_map( x, title = "auto", auto_title = NULL, leg_label_default = NULL, xlims = NULL, ylims = NULL, trans = NULL, bcpower = NULL, breaks = NULL, labels = NULL, output_crs = NULL, crop_to_grid = NULL, crop_by_region = FALSE, ocean_fill_colour = NULL, land_fill_colour = NULL, grid_fill_colour = NULL, grid_line_colour = NULL, grid_line_width = NULL, grid_fill_transparency = NULL, grid_line_transparency = NULL, legend_title = NULL, legend_limits = NULL, legend_title_wrap_length = 10, title_wrap_length = 60, visible_gridlines = TRUE, visible_panel_gridlines = FALSE, map_expansion_factor = 0.1, layers = NULL, layer_colours = NULL, layer_fill_colours = NULL, scale = c("medium", "small", "large"), filter_outliers = FALSE )
x |
An 'indicator_map' object containing multi-species indicator values associated with map grid cells. This is a required parameter with no default. |
title |
(Optional) Plot title. Replace "auto" with your own title if you want a custom title or if calling the function manually. |
auto_title |
(Optional) Text for automatic title generation, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
leg_label_default |
(Optional) Default label for the legend, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
xlims |
(Optional) Custom x-axis limits. |
ylims |
(Optional) Custom y-axis limits. |
trans |
(Optional) Scale transformation for the fill gradient (e.g., 'log'). |
bcpower |
(Optional) Power parameter for the Box-Cox, modulus, or Yeo-Johnson transformations. |
breaks |
(Optional) Break points for the legend scale. |
labels |
(Optional) Labels for legend scale break points. |
output_crs |
(Optional) Coordinate Reference System (CRS) for the output map. Can be specified as an EPSG code (e.g., 4326) or a proj4string. If NULL (default), the original CRS of the indicator_map object will be used. |
crop_to_grid |
(Optional) If TRUE, the grid will determine the edges of the map. If FALSE, a buffer will be added around the grid. If NULL (default), will be set to TRUE if map_level is "cube", otherwise FALSE. |
crop_by_region |
(Optional) If TRUE, the map will be cropped to the specified region when calculating the indicator_map. Default is FALSE. Note: this requires that a region was specified when calculating the indicator_map. |
ocean_fill_colour |
(Optional) Colour for the ocean area outside of the grid. Default is "lightblue". |
land_fill_colour |
(Optional) Colour for the land area outside of the grid. Default is "grey85". |
grid_fill_colour |
(Optional) Colour for empty grid cells (non-empty grid cells will be coloured according to their indicator value). Default is "transparent". |
grid_line_colour |
(Optional) Colour for the grid lines. Default is "black". If visible_gridlines is set to FALSE, this setting will have no effect. |
grid_line_width |
(Optional) Width of the grid lines. Default is 0.1. |
grid_fill_transparency |
(Optional) Transparency of the grid fill colour for empty grid cells (0 = fully transparent, 1 = fully opaque). If visible_gridlines is set to TRUE, default is 0.2. Otherwise, default is 0. *Note that this setting does NOT apply to grid cells with indicator values! |
grid_line_transparency |
(Optional) Transparency of the grid line colour (0 = fully transparent, 1 = fully opaque). Default is 0.5. If visible_gridlines is set to FALSE, this setting will have no effect. *Note that this setting does NOT apply to the grid outline! |
legend_title |
(Optional) Title for the plot legend. |
legend_limits |
(Optional) Limits for the legend scale. |
legend_title_wrap_length |
(Optional) Maximum legend title length before wrapping to a new line. |
title_wrap_length |
(Optional) Maximum title length before wrapping to a new line. |
visible_gridlines |
(Optional) Show gridlines between cells. Default is TRUE. |
visible_panel_gridlines |
(Optional) Show ggplot panel gridlines. Default is FALSE. |
map_expansion_factor |
(Optional) Factor to expand the map limits beyond the grid limits. This does NOT expand the boundaries of the plot, it only affects where the crop is applied. If this value is too small, some land may be visibly cut off due to map distortion caused by projections. A larger value will extend the bounding box for cropping to prevent this. Must be a positive number. (Default is 0.5). This should be enough for most projections, but you can increase this value if you are using an extreme projection and find that some land is visibly cut off. |
layers |
(Optional) Additional rnaturalearth layers to plot, e.g. c("reefs", "playas"). |
layer_colours |
(Optional) Colours for the outlines of additional layers. Must be the same length as 'layers'. |
layer_fill_colours |
(Optional) Fill colours for the additional layers. Must be the same length as 'layers'. |
scale |
(Optional) Scale of Natural Earth data ("small", "medium", or "large"). Default is 'medium'. |
filter_outliers |
(Optional) If TRUE, removes geographical outliers from the plot extent using an Interquartile Range (IQR) method based on the centroid coordinates of the indicator_map cells. This is particularly useful for discrete global grids like ISEA3H where stray data points from coordinate errors can force the map bounds to expand globally. Default is FALSE. |
A ggplot object representing the biodiversity indicator map. Can be customized using ggplot2 functions.
evenness_map <- pielou_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot_map( x = evenness_map, title = "Map of Species Evenness in Denmark", legend_title = "Evenness" )evenness_map <- pielou_evenness_map(example_cube_1, level = "country", region = "Denmark" ) plot_map( x = evenness_map, title = "Map of Species Evenness in Denmark", legend_title = "Evenness" )
Creates an interactive map of a calculated multi-species biodiversity indicator. Requires an indicator_map object as input.
plot_mv( x, legend_title = NULL, transparency = 0.8, filter_NA = TRUE, basemap_list = c("OpenStreetMap", "OpenTopoMap", "CartoDB.Positron", "Esri.WorldImagery"), ... )plot_mv( x, legend_title = NULL, transparency = 0.8, filter_NA = TRUE, basemap_list = c("OpenStreetMap", "OpenTopoMap", "CartoDB.Positron", "Esri.WorldImagery"), ... )
x |
An 'indicator_map' object containing multi-species indicator values associated with map grid cells. This is a required parameter with no default. |
legend_title |
(Optional) Legend title. Add your own custom legend title if you don't like the automatically generated one. If set to the default of NULL, the function will provide a legend title based on the indicator being plotted. |
transparency |
(Optional) Change the transparency of the grid fill. Default is 0.8. A value of 0 is full transparency, 1 is solid fill. |
filter_NA |
(Optional) Filter out NA values so NA grid cells do not appear. Default is TRUE. |
basemap_list |
(Optional) A list of basemaps you want mapview to display as options to select from. The first one in the list will be shown when the map loads. Default is c("OpenStreetMap", "OpenTopoMap", "CartoDB.Positron", "Esri.WorldImagery"). |
... |
(Optional) Pass additional parameters to the mapview package. |
An interactive mapview plot.
Creates map visualizations of species ranges or species
occurrences. Requires an indicator_map object created using the
spec_occ_map() or spec_range_map() functions as input. To plot
multi-species indicators (e.g., species richness or evenness), use the
plot_map() function instead.
plot_species_map( x, species, single_plot = TRUE, title = "auto", auto_title = NULL, leg_label_default = NULL, suppress_legend = FALSE, xlims = NULL, ylims = NULL, trans = NULL, bcpower = NULL, breaks = NULL, labels = NULL, output_crs = NULL, crop_to_grid = NULL, crop_by_region = FALSE, ocean_fill_colour = NULL, land_fill_colour = NULL, grid_fill_colour = NULL, grid_line_colour = NULL, grid_line_width = NULL, grid_fill_transparency = NULL, grid_line_transparency = NULL, legend_title = NULL, legend_limits = NULL, legend_title_wrap_length = 10, title_wrap_length = 60, spec_name_wrap_length = 40, visible_gridlines = TRUE, visible_panel_gridlines = FALSE, map_expansion_factor = 0.5, layers = NULL, layer_colours = NULL, layer_fill_colours = NULL, scale = c("medium", "small", "large"), filter_outliers = FALSE )plot_species_map( x, species, single_plot = TRUE, title = "auto", auto_title = NULL, leg_label_default = NULL, suppress_legend = FALSE, xlims = NULL, ylims = NULL, trans = NULL, bcpower = NULL, breaks = NULL, labels = NULL, output_crs = NULL, crop_to_grid = NULL, crop_by_region = FALSE, ocean_fill_colour = NULL, land_fill_colour = NULL, grid_fill_colour = NULL, grid_line_colour = NULL, grid_line_width = NULL, grid_fill_transparency = NULL, grid_line_transparency = NULL, legend_title = NULL, legend_limits = NULL, legend_title_wrap_length = 10, title_wrap_length = 60, spec_name_wrap_length = 40, visible_gridlines = TRUE, visible_panel_gridlines = FALSE, map_expansion_factor = 0.5, layers = NULL, layer_colours = NULL, layer_fill_colours = NULL, scale = c("medium", "small", "large"), filter_outliers = FALSE )
x |
An 'indicator_map' object containing indicator values for individual
species associated with map grid cells. This object is typically created
using the |
species |
Species you want to map occurrences for. Can be either numerical taxonKeys or species names. Partial species names can be used (the function will try to match them). This is a required parameter with no default. |
single_plot |
(Optional) If TRUE, all species occurrence time series will be combined into a single multi-panel plot. Set this to FALSE to plot each species separately. Default is TRUE. |
title |
(Optional) Plot title. Replace "auto" with your own title if you want a custom title or if calling the function manually. |
auto_title |
(Optional) Text for automatic title generation, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
leg_label_default |
(Optional) Default label for the legend, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
suppress_legend |
(Optional) Do not show legend. This defaults to FALSE but will be forcibly set to TRUE when plotting species ranges, as all cell values are 1. |
xlims |
(Optional) Custom x-axis limits. |
ylims |
(Optional) Custom y-axis limits. |
trans |
(Optional) Scale transformation for the fill gradient (e.g., 'log'). |
bcpower |
(Optional) Power parameter for the Box-Cox, modulus, or Yeo-Johnson transformations. |
breaks |
(Optional) Break points for the legend scale. |
labels |
(Optional) Labels for legend scale break points. |
output_crs |
(Optional) Coordinate Reference System (CRS) for the output map. Can be specified as an EPSG code (e.g., 4326) or a proj4string. If NULL (default), the original CRS of the indicator_map object will be used. |
crop_to_grid |
(Optional) If TRUE, the grid will determine the edges of the map. If FALSE, a buffer will be added around the grid. If NULL (default), will be set to TRUE if map_level is "cube", otherwise FALSE. |
crop_by_region |
(Optional) If TRUE, the map will be cropped to the specified region when calculating the indicator_map. Default is FALSE. Note: this requires that a region was specified when calculating the indicator_map. |
ocean_fill_colour |
(Optional) Colour for the ocean area outside of the grid. Default is "lightblue". |
land_fill_colour |
(Optional) Colour for the land area outside of the grid. Default is "grey85". |
grid_fill_colour |
(Optional) Colour for empty grid cells (non-empty grid cells will be coloured according to their indicator value). Default is "transparent". |
grid_line_colour |
(Optional) Colour for the grid lines. Default is "black". If visible_gridlines is set to FALSE, this setting will have no effect. |
grid_line_width |
(Optional) Width of the grid lines. Default is 0.1. |
grid_fill_transparency |
(Optional) Transparency of the grid fill colour for empty grid cells (0 = fully transparent, 1 = fully opaque). If visible_gridlines is set to TRUE, default is 0.2. Otherwise, default is 0. *Note that this setting does NOT apply to grid cells with indicator values! |
grid_line_transparency |
(Optional) Transparency of the grid line colour (0 = fully transparent, 1 = fully opaque). Default is 0.5. If visible_gridlines is set to FALSE, this setting will have no effect. *Note that this setting does NOT apply to the grid outline! |
legend_title |
(Optional) Title for the plot legend. |
legend_limits |
(Optional) Limits for the legend scale. |
legend_title_wrap_length |
(Optional) Maximum legend title length before wrapping to a new line. |
title_wrap_length |
(Optional) Maximum title length before wrapping to a new line. |
spec_name_wrap_length |
(Optional) Maximum species name length before wrapping to a new line. Default: 40 characters. |
visible_gridlines |
(Optional) Show gridlines between cells. Default is TRUE. |
visible_panel_gridlines |
(Optional) Show ggplot panel gridlines. Default is FALSE. |
map_expansion_factor |
(Optional) Factor to expand the map limits beyond the grid limits. This does NOT expand the boundaries of the plot, it only affects where the crop is applied. If this value is too small, some land may be visibly cut off due to map distortion caused by projections. A larger value will extend the bounding box for cropping to prevent this. Must be a positive number. (Default is 0.5). This should be enough for most projections, but you can increase this value if you are using an extreme projection and find that some land is visibly cut off. |
layers |
(Optional) Additional rnaturalearth layers to plot, e.g. c("reefs", "playas"). |
layer_colours |
(Optional) Colours for the outlines of additional layers. Must be the same length as 'layers'. |
layer_fill_colours |
(Optional) Fill colours for the additional layers. Must be the same length as 'layers'. |
scale |
(Optional) Scale of Natural Earth data ("small", "medium", or "large"). Default is 'medium'. |
filter_outliers |
(Optional) If TRUE, removes geographical outliers from the plot extent using an Interquartile Range (IQR) method based on the centroid coordinates of the indicator_map cells. This is particularly useful for discrete global grids like ISEA3H where stray data points from coordinate errors can force the map bounds to expand globally. Default is FALSE. |
A ggplot object representing the map of species range or occurrences. Can be customized using ggplot2 functions.
spec_occ_mammals_denmark <- spec_occ_map(example_cube_1, level = "country", region = "Denmark" ) plot_species_map(x = spec_occ_mammals_denmark, c(2440728, 4265185))spec_occ_mammals_denmark <- spec_occ_map(example_cube_1, level = "country", region = "Denmark" ) plot_species_map(x = spec_occ_mammals_denmark, c(2440728, 4265185))
Creates time series plots of species occurrences or species
range sizes, with an optional smoothed trendline, and visualizes
uncertainty. Requires an indicator_ts object created using the
spec_occ_ts() or spec_range_ts() functions as input. To plot
multi-species indicators (e.g., species richness or evenness), use the
plot_ts() function instead.
plot_species_ts( x, species, single_plot = TRUE, min_year = NULL, max_year = NULL, title = "auto", auto_title = NULL, y_label_default = NULL, suppress_y = FALSE, smoothed_trend = TRUE, linecolour = NULL, linealpha = 0.8, ribboncolour = NULL, ribbonalpha = 0.2, error_alpha = 1, trendlinecolour = NULL, trendlinealpha = 0.5, envelopecolour = NULL, envelopealpha = 0.2, smooth_cialpha = 1, point_line = c("point", "line"), pointsize = 2, linewidth = 1, ci_type = c("error_bars", "ribbon"), error_width = 1, error_thickness = 1, smooth_linetype = c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"), smooth_linewidth = 1, smooth_cilinewidth = 1, gridoff = FALSE, x_label = NULL, y_label = NULL, x_expand = 0.1, y_expand = 0.1, x_breaks = 10, y_breaks = 6, title_wrap_length = 60, spec_name_wrap_length = 40 )plot_species_ts( x, species, single_plot = TRUE, min_year = NULL, max_year = NULL, title = "auto", auto_title = NULL, y_label_default = NULL, suppress_y = FALSE, smoothed_trend = TRUE, linecolour = NULL, linealpha = 0.8, ribboncolour = NULL, ribbonalpha = 0.2, error_alpha = 1, trendlinecolour = NULL, trendlinealpha = 0.5, envelopecolour = NULL, envelopealpha = 0.2, smooth_cialpha = 1, point_line = c("point", "line"), pointsize = 2, linewidth = 1, ci_type = c("error_bars", "ribbon"), error_width = 1, error_thickness = 1, smooth_linetype = c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"), smooth_linewidth = 1, smooth_cilinewidth = 1, gridoff = FALSE, x_label = NULL, y_label = NULL, x_expand = 0.1, y_expand = 0.1, x_breaks = 10, y_breaks = 6, title_wrap_length = 60, spec_name_wrap_length = 40 )
x |
An 'indicator_ts' object containing time series of indicator values
matched to species names and/or taxon keys, created using the
|
species |
Species you want to map occurrences for. Can be either numerical taxonKeys or species names. Partial species names can be used (the function will try to match them). This is a required parameter with no default. |
single_plot |
(Optional) By default all species occurrence time series will be combined into a single multi-panel plot. Set this to FALSE to plot each species separately. |
min_year |
(Optional) Earliest year to include in the plot. |
max_year |
(Optional) Latest year to include in the plot. |
title |
(Optional) Plot title. Replace "auto" with your own title if you want a custom title or if calling the function manually. |
auto_title |
(Optional) Text for automatic title generation, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
y_label_default |
(Optional) Default label for the y-axis, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
suppress_y |
(Optional) If TRUE, suppresses y-axis labels. |
smoothed_trend |
(Optional) If TRUE, plot a smoothed trendline over time
( |
linecolour |
(Optional) Colour for the indicator line or points. Default is darkorange. |
linealpha |
(Optional) Transparency for indicator line or points. Default is 0.8. |
ribboncolour |
(Optional) Colour for the bootstrapped confidence intervals. Default is goldenrod1. Set to "NA" if you don't want to plot the CIs. |
ribbonalpha |
(Optional) Transparency for indicator confidence interval ribbon (if ci_type = "ribbon"). Default is 0.2. |
error_alpha |
(Optional) Transparency for indicator error bars (if ci_type = "error_bar"). Default is 1. |
trendlinecolour |
(Optional) Colour for the smoothed trendline. Default is blue. |
trendlinealpha |
(Optional) Transparency for the smoothed trendline. Default is 0.5. |
envelopecolour |
(Optional) Colour for the uncertainty envelope. Default is lightsteelblue. |
envelopealpha |
(Optional) Transparency for the smoothed trendline envelope. Default is 0.2. |
smooth_cialpha |
(Optional) Transparency for the smoothed lines forming the edges of the trendline envelope. Default is 1. |
point_line |
(Optional) Whether to plot the indicator as a line or a series of points. Options are "line" or "point". Default is "point". |
pointsize |
(Optional) Size of the points if point_line = "point". Default is 2. |
linewidth |
(Optional) Width of the line if point_line = "line". Default is 1. |
ci_type |
(Optional) Whether to plot bootstrapped confidence intervals as a "ribbon" or "error_bars". Default is "error_bars". |
error_width |
(Optional) Width of error bars if ci_type = "error_bars". Default is 1. Note that unlike the default 'width' parameter in geom_errorbar, 'error_width' is NOT dependent on the number of data points in the plot. It is automatically scaled to account for this. Therefore the width you select will be consistent relative to the plot width even if you change 'min_year' and 'max_year'. |
error_thickness |
(Optional) Thickness of error bars if ci_type = "error_bars". Default is 1. |
smooth_linetype |
(Optional) Type of line to plot for smoothed trendline. Default is "solid". |
smooth_linewidth |
(Optional) Line width for smoothed trendline. Default is 1. |
smooth_cilinewidth |
(Optional) Line width for smoothed trendline confidence intervals. Default is 1. |
gridoff |
(Optional) If TRUE, hides gridlines. |
x_label |
(Optional) Label for the x-axis. |
y_label |
(Optional) Label for the y-axis. |
x_expand |
(Optional) Expansion factor to expand the x-axis beyond the data. Left and right values are required in the form of c(0.1, 0.2) or simply 0.1 to apply the same value to each side. Default is 0.05. |
y_expand |
(Optional) Expansion factor to expand the y-axis beyond the data. Lower and upper values are required in the form of c(0.1, 0.2) or simply 0.1 to apply the same value to the top and bottom. Default is 0.05. |
x_breaks |
(Optional) Integer giving desired number of breaks for x axis. (May not return exactly the number requested.) |
y_breaks |
(Optional) Integer giving desired number of breaks for y axis. (May not return exactly the number requested.) |
title_wrap_length |
(Optional) Maximum title length before wrapping to a new line. |
spec_name_wrap_length |
(Optional) Maximum species name length before wrapping to a new line. |
A ggplot object representing species range or occurrence time series plot(s). Can be customized using ggplot2 functions.
spec_occ_ts_mammals_denmark <- spec_occ_ts(example_cube_1, level = "country", region = "Denmark") # default colours: plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185)) # custom colours: plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185), linecolour = "thistle", trendlinecolour = "forestgreen", envelopecolour = "lightgreen")spec_occ_ts_mammals_denmark <- spec_occ_ts(example_cube_1, level = "country", region = "Denmark") # default colours: plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185)) # custom colours: plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185), linecolour = "thistle", trendlinecolour = "forestgreen", envelopecolour = "lightgreen")
Creates a time series plot of a calculated multi-species
biodiversity indicator (e.g. species richness or evenness), with an optional
smoothed trendline, and visualizes uncertainty. Requires an 'indicator_ts'
object as input. To plot a single-species indicator time series, use the
plot_species_ts() function instead.
plot_ts( x, min_year = NULL, max_year = NULL, title = "auto", auto_title = NULL, y_label_default = NULL, suppress_y = FALSE, smoothed_trend = TRUE, linecolour = NULL, linealpha = 0.8, ribboncolour = NULL, ribbonalpha = 0.2, error_alpha = 1, trendlinecolour = NULL, trendlinealpha = 0.5, envelopecolour = NULL, envelopealpha = 0.2, smooth_cialpha = 1, point_line = c("point", "line"), pointsize = 2, linewidth = 1, ci_type = c("error_bars", "ribbon"), error_width = 1, error_thickness = 1, smooth_linetype = c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"), smooth_linewidth = 1, smooth_cilinewidth = 1, gridoff = FALSE, x_label = NULL, y_label = NULL, x_expand = 0.1, y_expand = 0.1, x_breaks = 10, y_breaks = 6, title_wrap_length = 60 )plot_ts( x, min_year = NULL, max_year = NULL, title = "auto", auto_title = NULL, y_label_default = NULL, suppress_y = FALSE, smoothed_trend = TRUE, linecolour = NULL, linealpha = 0.8, ribboncolour = NULL, ribbonalpha = 0.2, error_alpha = 1, trendlinecolour = NULL, trendlinealpha = 0.5, envelopecolour = NULL, envelopealpha = 0.2, smooth_cialpha = 1, point_line = c("point", "line"), pointsize = 2, linewidth = 1, ci_type = c("error_bars", "ribbon"), error_width = 1, error_thickness = 1, smooth_linetype = c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"), smooth_linewidth = 1, smooth_cilinewidth = 1, gridoff = FALSE, x_label = NULL, y_label = NULL, x_expand = 0.1, y_expand = 0.1, x_breaks = 10, y_breaks = 6, title_wrap_length = 60 )
x |
An 'indicator_ts' object containing a time series of multi-species indicator values. This is a required parameter with no default. |
min_year |
(Optional) Earliest year to include in the plot. |
max_year |
(Optional) Latest year to include in the plot. |
title |
(Optional) Plot title. Replace "auto" with your own title if you want a custom title or if calling the function manually. |
auto_title |
(Optional) Text for automatic title generation, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
y_label_default |
(Optional) Default label for the y-axis, provided by an appropriate S3 method (if calling the function manually, leave as NULL). |
suppress_y |
(Optional) If TRUE, suppresses y-axis labels. |
smoothed_trend |
(Optional) If TRUE, plot a smoothed trendline over time
( |
linecolour |
(Optional) Colour for the indicator line or points. Default is darkorange. |
linealpha |
(Optional) Transparency for indicator line or points. Default is 0.8. |
ribboncolour |
(Optional) Colour for the bootstrapped confidence intervals. Default is goldenrod1. Set to "NA" if you don't want to plot the CIs. |
ribbonalpha |
(Optional) Transparency for indicator confidence interval ribbon (if ci_type = "ribbon"). Default is 0.2. |
error_alpha |
(Optional) Transparency for indicator error bars (if ci_type = "error_bar"). Default is 1. |
trendlinecolour |
(Optional) Colour for the smoothed trendline. Default is blue. |
trendlinealpha |
(Optional) Transparency for the smoothed trendline. Default is 0.5. |
envelopecolour |
(Optional) Colour for the uncertainty envelope. Default is lightsteelblue. |
envelopealpha |
(Optional) Transparency for the smoothed trendline envelope. Default is 0.2. |
smooth_cialpha |
(Optional) Transparency for the smoothed lines forming the edges of the trendline envelope. Default is 1. |
point_line |
(Optional) Whether to plot the indicator as a line or a series of points. Options are "line" or "point". Default is "point". |
pointsize |
(Optional) Size of the points if point_line = "point". Default is 2. |
linewidth |
(Optional) Width of the line if point_line = "line". Default is 1. |
ci_type |
(Optional) Whether to plot bootstrapped confidence intervals as a "ribbon" or "error_bars". Default is "error_bars". |
error_width |
(Optional) Width of error bars if ci_type = "error_bars". Default is 1. Note that unlike the default 'width' parameter in geom_errorbar, 'error_width' is NOT dependent on the number of data points in the plot. It is automatically scaled to account for this. Therefore the width you select will be consistent relative to the plot width even if you change 'min_year' and 'max_year'. |
error_thickness |
(Optional) Thickness of error bars if ci_type = "error_bars". Default is 1. |
smooth_linetype |
(Optional) Type of line to plot for smoothed trendline. Default is "solid". |
smooth_linewidth |
(Optional) Line width for smoothed trendline. Default is 1. |
smooth_cilinewidth |
(Optional) Line width for smoothed trendline confidence intervals. Default is 1. |
gridoff |
(Optional) If TRUE, hides gridlines. |
x_label |
(Optional) Label for the x-axis. |
y_label |
(Optional) Label for the y-axis. |
x_expand |
(Optional) Expansion factor to expand the x-axis beyond the data. Left and right values are required in the form of c(0.1, 0.2) or simply 0.1 to apply the same value to each side. Default is 0.05. |
y_expand |
(Optional) Expansion factor to expand the y-axis beyond the data. Lower and upper values are required in the form of c(0.1, 0.2) or simply 0.1 to apply the same value to the top and bottom. Default is 0.05. |
x_breaks |
(Optional) Integer giving desired number of breaks for x axis. (May not return exactly the number requested.) |
y_breaks |
(Optional) Integer giving desired number of breaks for y axis. (May not return exactly the number requested.) |
title_wrap_length |
(Optional) Maximum title length before wrapping to a new line. |
A ggplot object representing the biodiversity indicator time series plot. Can be customized using ggplot2 functions.
# default colours: plot_ts(example_indicator_ts1, y_label = "Species Richness", title = "Observed Species Richness: Mammals in Denmark") # custom colours: plot_ts(example_indicator_ts1, y_label = "Species Richness", title = "Observed Species Richness: Mammals in Denmark", linecolour = "thistle", trendlinecolour = "forestgreen", envelopecolour = "lightgreen")# default colours: plot_ts(example_indicator_ts1, y_label = "Species Richness", title = "Observed Species Richness: Mammals in Denmark") # custom colours: plot_ts(example_indicator_ts1, y_label = "Species Richness", title = "Observed Species Richness: Mammals in Denmark", linecolour = "thistle", trendlinecolour = "forestgreen", envelopecolour = "lightgreen")
Provide a summary of indicators registered in the package.
## S3 method for class 'available_indicators' print(x, n = 30, ...)## S3 method for class 'available_indicators' print(x, n = 30, ...)
x |
Object of class available_indicators |
n |
(Optional) Integer specifying the number of rows of data to display. |
... |
Additional arguments. |
Provides a summary representation of an indicator_map object, designed for user-friendly display in the console.
## S3 method for class 'indicator_map' print(x, n = 10, include_na = FALSE, ...)## S3 method for class 'indicator_map' print(x, n = 10, include_na = FALSE, ...)
x |
An indicator_map object. |
n |
Integer specifying the number of rows of data to display. |
include_na |
Logical. If TRUE, includes rows with NA diversity values in the printed output. Default is FALSE. |
... |
Additional arguments. |
Provides a summary representation of an indicator_ts object, designed for user-friendly display in the console.
## S3 method for class 'indicator_ts' print(x, n = 10, ...)## S3 method for class 'indicator_ts' print(x, n = 10, ...)
x |
An indicator_ts object. |
n |
(Optional) Integer specifying the number of rows of data to display. |
... |
Additional arguments. |
print(example_indicator_ts1)print(example_indicator_ts1)
Provides a summary representation of a processed_cube object, designed for user-friendly display in the console.
## S3 method for class 'processed_cube' print(x, n = 10, ...)## S3 method for class 'processed_cube' print(x, n = 10, ...)
x |
A processed_cube object. |
n |
(Optional) Integer specifying the number of rows of cube data to display. |
... |
Additional arguments. |
print(example_cube_1)print(example_cube_1)
Provides a summary representation of a processed_cube_dsinfo object, designed for user-friendly display in the console.
## S3 method for class 'processed_cube_dsinfo' print(x, n = 10, ...)## S3 method for class 'processed_cube_dsinfo' print(x, n = 10, ...)
x |
A processed_cube_dsinfo object. |
n |
(Optional) Integer specifying the number of rows of data to display. |
... |
Additional arguments. |
Provides a summary representation of a sim_cube object, designed for user-friendly display in the console.
## S3 method for class 'sim_cube' print(x, n = 10, ...)## S3 method for class 'sim_cube' print(x, n = 10, ...)
x |
A sim_cube object. |
n |
(Optional) Integer specifying the number of rows of cube data to display. |
... |
Additional arguments. |
Processes a GBIF data cube and (if applicable) an associated taxonomic information file. If your cube includes a taxonomic info file it is likely a previous generation cube and should be processed using 'process_cube_old'. The taxonomic info file must reside in the same directory as your cube and share a base file name (e.g., 'cubes/my_mammals_cube.csv', 'cubes/my_mammals_info.csv'). If your cube does NOT include a taxonomic info file then it is likely a current generation cube and should be processed using the standard process_cube function. The API used to generate the current generation cubes is very flexible and allows user-specified column names. Therefore, please check that the column names of your cube match the Darwin Core standard expected by the process_cube function. If they do not, you may need to enter them manually. The function will return an error if it cannot find all required columns.
process_cube( cube_name, grid_type = c("automatic", "eea", "mgrs", "eqdgc", "isea3h", "custom", "none"), first_year = NULL, last_year = NULL, force_gridcode = FALSE, cols_year = NULL, cols_yearMonth = NULL, cols_yearMonthDay = NULL, cols_cellCode = NULL, cols_occurrences = NULL, cols_scientificName = NULL, cols_minCoordinateUncertaintyInMeters = NULL, cols_minTemporalUncertainty = NULL, cols_kingdom = NULL, cols_family = NULL, cols_species = NULL, cols_kingdomKey = NULL, cols_familyKey = NULL, cols_speciesKey = NULL, cols_familyCount = NULL, cols_sex = NULL, cols_lifeStage = NULL, separator = NULL )process_cube( cube_name, grid_type = c("automatic", "eea", "mgrs", "eqdgc", "isea3h", "custom", "none"), first_year = NULL, last_year = NULL, force_gridcode = FALSE, cols_year = NULL, cols_yearMonth = NULL, cols_yearMonthDay = NULL, cols_cellCode = NULL, cols_occurrences = NULL, cols_scientificName = NULL, cols_minCoordinateUncertaintyInMeters = NULL, cols_minTemporalUncertainty = NULL, cols_kingdom = NULL, cols_family = NULL, cols_species = NULL, cols_kingdomKey = NULL, cols_familyKey = NULL, cols_speciesKey = NULL, cols_familyCount = NULL, cols_sex = NULL, cols_lifeStage = NULL, separator = NULL )
cube_name |
The location and name of a data cube file (e.g., 'inst/extdata/europe_species_cube.csv'). |
grid_type |
(Optional) Specify which grid reference system your cube uses. By default the function will attempt to determine this automatically and return an error if it fails. If you want to perform analysis on a cube with custom grid codes (e.g. output from the gcube package) or a cube without grid codes, select 'custom' or 'none', respectively. |
first_year |
(Optional) The first year of occurrences to include. If not specified, uses a default of 1600 to prevent false records (e.g. with year = 0). |
last_year |
(Optional) The final year of occurrences to include. If not specified, uses the latest year present in the cube. |
force_gridcode |
(Optional) Force the function to assume a specific grid reference system. This may cause unexpected downstream issues, so it is not recommended. If you are getting errors related to grid cell codes, check to make sure they are valid. |
cols_year |
(Optional) The name of the column containing the year of occurrence (if something other than 'year'). This column is required unless you have a yearMonth column. |
cols_yearMonth |
(Optional) The name of the column containing the year and month of occurrence (if present and if other than 'yearMonth'). Use this only if you do not have a year column. The b3gbi package does not use month data, so the function will convert your yearMonth column to a year column. |
cols_yearMonthDay |
(Optional) The name of the column containing the year, month and day of occurrence (if present and if other than 'yearMonthDay'). Use this only if you do not have year or yearMonth columns. The b3gbi package does not use day or month data, so the function will convert your yearMonthDay column to a year column. |
cols_cellCode |
(Optional) The name of the column containing the grid reference codes (if other than 'cellCode'). This column is required. |
cols_occurrences |
(Optional) The name of the column containing the number of occurrence (if other than 'occurrences'). This column is required. |
cols_scientificName |
(Optional) The name of the column containing the scientific name of the species (if other than 'scientificName'). Note that it is not necessary to have both a species column and a scientificName column. One or the other is sufficient. |
cols_minCoordinateUncertaintyInMeters |
(Optional) The name of the column containing the minimum coordinate uncertainty of the occurrences (if other than 'minCoordinateUncertaintyinMeters'). |
cols_minTemporalUncertainty |
(Optional) The name of the column containing the minimum temporal uncertainty of the occurrences (if other than 'minTemporalUncertainty'). |
cols_kingdom |
(Optional) The name of the column containing the kingdom the occurring species belongs to (if other than 'kingdom'). |
cols_family |
(Optional) The name of the column containing the family the occurring species belongs to (if other than 'family'). |
cols_species |
(Optional) The name of the column containing the name of the occurring species (if other than 'species'). Note that it is not necessary to have both a species column and a scientificName column. One or the other is sufficient. |
cols_kingdomKey |
(Optional) The name of the column containing the kingdom key of the occurring species (if other than 'kingdomKey'). |
cols_familyKey |
(Optional) The name of the column containing the family key of the occurring species (if other than 'familykey'). |
cols_speciesKey |
(Optional) The name of the column containing the species key of the occurring species (if other than 'speciesKey'). The column is required, but note that if you have a 'taxonKey' column you can provide it as the speciesKey. |
cols_familyCount |
(Optional) The name of the column containing the occurrence count by family. |
cols_sex |
(Optional) The name of the column containing the sex of the observed individuals. |
cols_lifeStage |
(Optional) The name of the column containing the life stage of the observed individuals. |
separator |
(Optional) The column-separating character in your csv file. This should be automatically recognized, so only specify this if you are having trouble. |
A tibble containing the processed GBIF occurrence data.
## Not run: cube_name <- system.file("extdata", "denmark_mammals_cube_eqdgc.csv", package = "b3gbi") denmark_example_cube <- process_cube(cube_name) denmark_example_cube ## End(Not run)## Not run: cube_name <- system.file("extdata", "denmark_mammals_cube_eqdgc.csv", package = "b3gbi") denmark_example_cube <- process_cube(cube_name) denmark_example_cube ## End(Not run)
Calculate the relative occupancy of each species — the
proportion of grid cells in which it has been recorded — either as a
gridded map or as a time series. Three denominator definitions are
available via the occ_type parameter (see 'Details').
relative_occupancy_map(data, occ_type = 0, ...) relative_occupancy_ts(data, occ_type = 0, ...)relative_occupancy_map(data, occ_type = 0, ...) relative_occupancy_ts(data, occ_type = 0, ...)
data |
A data cube object (class 'processed_cube'). |
occ_type |
Integer controlling the occupancy denominator. One of:
|
... |
Arguments passed on to
|
Relative occupancy quantifies how widely distributed a species is within
a study region, expressed as a proportion (0–1). The numerator is always
the number of post-aggregation grid cells (cellid) in which the species
has at least one recorded occurrence. The denominator depends on
occ_type:
occ_type |
Name | Denominator |
0 |
Total-area | All grid cells in region (constant) |
1 |
Ever-occupied | Cells with ≥ 1 occurrence, any species, full window |
2 |
Annual (TS) / Temporal mean (map) | Cells with ≥ 1 occ in that year |
Type 0 is the most conservative and comparable across different data cubes because the denominator is fixed by the grid definition. A low value means the species occupies few cells relative to the entire region; however, empty cells cannot be assumed truly unoccupied — they may be under-sampled or simply not yet visited.
Type 1 restricts the denominator to cells where any occurrence was
recorded across the full time window, conditioning on cells with
documented sampling effort. Values will always be the
corresponding Type 0 value (since the denominator is smaller). Useful
when you wish to compare species occupancy within the subset of cells
that have been at least partially surveyed.
Type 2 further restricts the denominator within each year (for time series) to cells active in that year. For maps, the annual proportion is computed first and then averaged across years (temporal mean). This is the most dynamic measure, as both numerator and denominator can vary per year, reflecting inter-annual changes in sampling footprint.
These cubes contain presence-only data. An empty cell does not imply that a species was absent — it may simply reflect lack of sampling in that cell. Types 1 and 2 partially address this by conditioning on cells where at least one occurrence was recorded, but those cells still only document where observers were active, not where species were definitively absent. All three types should be interpreted as recorded occupancy, not true occupancy.
When cell_size is coarser than the native cube resolution, the data are
first aggregated to the coarser grid (internally via
aggregate_data_to_coarser_grid()).
All denominators are computed on the post-aggregation cellid (not the
original cellCode). This ensures the indicator is consistent with the
resolution at which it is displayed.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'relative_occupancy' containing:
cellid (map) or year (ts): spatial or temporal identifier.
cellCode: grid cell codes (map only; if available).
taxonKey: GBIF taxon keys.
scientificName: Species scientific names.
diversity_val: Relative occupancy value in .
relative_occupancy_map(): Calculate relative occupancy as a
gridded map.
relative_occupancy_ts(): Calculate relative occupancy as a time
series.
Sax, D. F., & Gaines, S. D. (2003). Species diversity: from global decreases to local increases. Trends in Ecology & Evolution, 18(11), 561–566.
compute_indicator_workflow
## Not run: # Type 0: proportion of all grid cells ro_map <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 0 ) plot(ro_map, c(2440728, 4265185)) # Type 1: proportion of ever-occupied cells ro_map_1 <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 1 ) # Type 2: temporal mean annual occupancy ro_map_2 <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 2 ) ## End(Not run) ## Not run: # Type 0: proportion of all grid cells (default) ro_ts <- relative_occupancy_ts(example_cube_1, occ_type = 0) plot(ro_ts, c(2440728, 4265185)) # Type 1: proportion of ever-occupied cells (constant denominator) ro_ts_1 <- relative_occupancy_ts(example_cube_1, occ_type = 1) # Type 2: proportion of cells active that year (varying denominator) ro_ts_2 <- relative_occupancy_ts(example_cube_1, occ_type = 2) ## End(Not run)## Not run: # Type 0: proportion of all grid cells ro_map <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 0 ) plot(ro_map, c(2440728, 4265185)) # Type 1: proportion of ever-occupied cells ro_map_1 <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 1 ) # Type 2: temporal mean annual occupancy ro_map_2 <- relative_occupancy_map(example_cube_1, level = "country", region = "Denmark", occ_type = 2 ) ## End(Not run) ## Not run: # Type 0: proportion of all grid cells (default) ro_ts <- relative_occupancy_ts(example_cube_1, occ_type = 0) plot(ro_ts, c(2440728, 4265185)) # Type 1: proportion of ever-occupied cells (constant denominator) ro_ts_1 <- relative_occupancy_ts(example_cube_1, occ_type = 1) # Type 2: proportion of cells active that year (varying denominator) ro_ts_2 <- relative_occupancy_ts(example_cube_1, occ_type = 2) ## End(Not run)
This function takes an indicator_map or indicator_ts object and
replaces all NA values in the diversity_val column with zeros. This is
useful when NA values represent areas or years with no data that should be
treated as zero for mapping or analysis purposes.
replace_na(x)replace_na(x)
x |
An |
The input indicator object with NA values in diversity_val
replaced by zero.
## Not run: # Assuming 'result' is an indicator_map or indicator_ts object result_filled <- replace_na(result) ## End(Not run)## Not run: # Assuming 'result' is an indicator_map or indicator_ts object result_filled <- replace_na(result) ## End(Not run)
This function calculates the number of occurrences for individual species over a gridded map or as a time series (see 'Details' for more information).
spec_occ_map(data, ...) spec_occ_ts(data, ...)spec_occ_map(data, ...) spec_occ_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Species occurrences are considered an essential biodiversity variable (EBV). They are mapped by calculating the total number of occurrences of a given species for each cell. This represents the occurrence frequency distribution, and also indicates the observed species distribution. The number of occurrences can act as a proxy for relative abundance of species with a similar detectability, which is an important aspect of biodiversity although not an indicator when calculated in isolation.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'spec_occ' containing the calculated indicator values and metadata.
spec_occ_map():
spec_occ_ts():
compute_indicator_workflow
## Not run: so_map <- spec_occ_map(example_cube_1, level = "country", region = "Denmark", include_ocean = FALSE ) plot(so_map, c(2440728, 4265185)) ## End(Not run) so_ts <- spec_occ_ts(example_cube_1, first_year = 1985) plot(so_ts, c(2435767, 2434793))## Not run: so_map <- spec_occ_map(example_cube_1, level = "country", region = "Denmark", include_ocean = FALSE ) plot(so_map, c(2440728, 4265185)) ## End(Not run) so_ts <- spec_occ_ts(example_cube_1, first_year = 1985) plot(so_ts, c(2435767, 2434793))
Plot the cells occupied for individual species over a gridded map or calculate the change in the number of cells occupied as a time series.
spec_range_map(data, ...) spec_range_ts(data, ...)spec_range_map(data, ...) spec_range_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'spec_range' containing the calculated indicator values and metadata.
spec_range_map():
spec_range_ts():
compute_indicator_workflow
sr_map <- spec_range_map(example_cube_1, level = "country", region = "Denmark", include_ocean = FALSE ) plot(sr_map, c(2440728, 4265185)) ## Not run: sr_ts <- spec_range_ts(example_cube_1, first_year = 1985) plot(sr_ts, c(2440728, 4265185)) ## End(Not run)sr_map <- spec_range_map(example_cube_1, level = "country", region = "Denmark", include_ocean = FALSE ) plot(sr_map, c(2440728, 4265185)) ## Not run: sr_ts <- spec_range_ts(example_cube_1, first_year = 1985) plot(sr_ts, c(2440728, 4265185)) ## End(Not run)
This function calculates the density of unique species over a gridded map or as a time series (see 'Details' for more information).
spec_richness_density_map(data, ...) spec_richness_density_ts(data, ...)spec_richness_density_map(data, ...) spec_richness_density_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
Density is calculated by dividing the total number of unique species per square kilometre for each cell or year. This provides similar information to observed species richness, but is adjusted for cell area. Like observed richness, bootstrapped confidence intervals are not calculated for this indicator because they are statistically inappropriate at the indicator level.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'spec_richness_density' containing the calculated indicator values and metadata.
spec_richness_density_map():
spec_richness_density_ts():
compute_indicator_workflow
## Not run: srd_map <- spec_richness_density_map(example_cube_1, level = "country", region = "Denmark" ) plot(srd_map) ## End(Not run) ## Not run: srd_ts <- spec_richness_density_ts(example_cube_1, first_year = 1985) plot(srd_ts) ## End(Not run)## Not run: srd_map <- spec_richness_density_map(example_cube_1, level = "country", region = "Denmark" ) plot(srd_map) ## End(Not run) ## Not run: srd_ts <- spec_richness_density_ts(example_cube_1, first_year = 1985) plot(srd_ts) ## End(Not run)
This function takes a processed_cube object and aggregates the
observation counts by a specified taxonomic rank.
sum_by_taxon(object, rank)sum_by_taxon(object, rank)
object |
A |
rank |
A character string specifying the taxonomic rank to group by
(e.g., "family", "kingdom"). This column must exist in |
A tibble with columns total_observations and the specified rank.
## Not run: # Assuming 'cube' is a processed_cube object family_sums <- sum_by_taxon(cube, "family") ## End(Not run)## Not run: # Assuming 'cube' is a processed_cube object family_sums <- sum_by_taxon(cube, "family") ## End(Not run)
This function calculates the taxonomic distinctness index (TDI) over a gridded map or as a time series (see 'Details' for more information).
tax_distinct_map(data, rows = 1, ...) tax_distinct_ts(data, rows = 1, ...)tax_distinct_map(data, rows = 1, ...) tax_distinct_ts(data, rows = 1, ...)
data |
A data cube object (class 'processed_cube'). |
rows |
(Optional) Choose which row to select if there are multiple matches when retrieving taxonomic information from GBIF. (Default is 1. Use NA for interactive mode.) |
... |
Arguments passed on to
|
Taxonomic distinctness is an essential biodiversity variable (EBV) that measures the taxonomic relatedness between species, providing a measure of biodiversity that accounts for evolutionary relationships. A distance matrix based on pairwise taxonomic relationships is calculated for each cell using the taxize package (Chamberlain & Szöcs, 2013; Chamberlain et al., 2020), then taxonomic distinctness is calculated as the Taxonomic Distinctness Index (TDI; Clarke & Warwick, 1999):
where S is the number of species, Ri and Rj are the taxonomic ranks of species i and j (from the GBIF Taxonomic Backbone), and L is the maximum number of taxonomic ranks. The TDI ranges from 0 to 1, with higher values indicating greater taxonomic distinctness.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'tax_distinct' containing the calculated indicator values and metadata.
tax_distinct_map():
tax_distinct_ts():
Chamberlain, S. A., & Szöcs, E. (2013). taxize: taxonomic search and retrieval in R. F1000Research, 2.
Chamberlain, S., Szoecs, E., Foster, Z., Boettiger, C., Ram, K., Bartomeus, I., Baumgartner, J., O'Donnell, J., Oksanen, J., Tzovaras, B. G., Marchand, P., Tran, V., Salmon, M., Li, G., & Grenié, M. (2020). taxize: Taxonomic Information from Around the Web. R package version 0.9.98. https://github.com/ropensci/taxize.
Clarke, K. R., & Warwick, R. M. (1999). The taxonomic distinctness measure of biodiversity: weighting of step lengths between hierarchical levels. Marine Ecology Progress Series, 184, 21-29.
compute_indicator_workflow
## Not run: td_map <- tax_distinct_map(example_cube_1, level = "country", region = "Denmark" ) plot(td_map) ## End(Not run) ## Not run: td_ts <- tax_distinct_ts(example_cube_1, level = "country", region = "Denmark" ) plot(td_ts) ## End(Not run)## Not run: td_map <- tax_distinct_map(example_cube_1, level = "country", region = "Denmark" ) plot(td_map) ## End(Not run) ## Not run: td_ts <- tax_distinct_ts(example_cube_1, level = "country", region = "Denmark" ) plot(td_ts) ## End(Not run)
This function calculates the total number of species occurrence records over a gridded map or as a time series (see 'Details' for more ' information).
total_occ_map(data, ...) total_occ_ts(data, ...)total_occ_map(data, ...) total_occ_ts(data, ...)
data |
A data cube object (class 'processed_cube'). |
... |
Arguments passed on to
|
The total number of occurrences is calculated by summing the occurrences of all species observed for each cell or year. While not itself an indicator, this variable provides an overview of the comprehensiveness and distribution of data in the cube being analysed, and may be helpful, or even vital, for interpreting the results of calculated indicators.
An S3 object with the classes 'indicator_map' or 'indicator_ts' and 'total_occ' containing the calculated indicator values and metadata.
total_occ_map():
total_occ_ts():
compute_indicator_workflow
## Not run: to_map <- total_occ_map(example_cube_1, level = "country", region = "Denmark" ) plot(to_map) ## End(Not run) ## Not run: to_ts <- total_occ_ts(example_cube_1, first_year = 1985) plot(to_ts) ## End(Not run)## Not run: to_map <- total_occ_map(example_cube_1, level = "country", region = "Denmark" ) plot(to_map) ## End(Not run) ## Not run: to_ts <- total_occ_ts(example_cube_1, first_year = 1985) plot(to_ts) ## End(Not run)