Package {biomes}

Internal package setup for biomes

Description

Reproducibly classifies occurrence records into biome classes using 31 published global terrestrial biome schemes compiled by Fischer and colleagues (2022) doi:10.1111/geb.13574, provided as harmonised raster layers at 10x10 km resolution globally. Includes functions to choose the most suitable biome scheme for a dataset by a data-driven ranking, to classify occurrence records, and to tabulate and visualise the result. Works with user-provided occurrences or a taxon name, in which case occurrences are downloaded from GBIF (https://www.gbif.org) and cleaned automatically.

Author(s)

Maintainer: Hans Christian Groß hc.gross@gmx.de

Authors:

• Hans Christian Groß hc.gross@gmx.de

• Alexander Zizka alexander.zizka@biologie.uni-marburg.de [funder]

• Anna Walentowitz

• Jan-Christopher Fischer

See Also

Useful links:

• https://azizka.github.io/biomes/

• https://github.com/azizka/biomes

• Report bugs at https://github.com/azizka/biomes/issues

Classify occurrences into biomes

Description

For each occurrence record, assigns a biome label based on its spatial position and one or more biome raster layers. One row of the returned data frame corresponds to one row (one occurrence record) of x.

Usage

biomes_classify(
  x,
  scheme = NULL,
  biome = NULL,
  lon = "decimalLongitude",
  lat = "decimalLatitude",
  value = "name",
  append = TRUE,
  na = "no_biome",
  raster_file = NULL
)

Arguments

Value

A data frame with one row per record in x. By default (append = TRUE) the original columns of x are kept and the classification columns are added on the right. With append = FALSE only the classification columns are returned. Classification columns are named after the input layers, with the suffix ⁠_value⁠ for the raster value and ⁠_name⁠ for the biome name. Raster values without a name in the legend (typically azonal classes encoded with high values) fall back to "azonal (raster value: X)".

Examples

# Load example occurrence data
data("biomes_example")


# The biome raster (~36 MB) is downloaded and cached on first use.

# Default: classify against all 31 layers and append the result to x
biomes_classify(biomes_example)

# Single scheme, both raster value and biome name
biomes_classify(biomes_example, scheme = 1, value = "both")

# Multiple schemes
biomes_classify(biomes_example, scheme = c(1, 25))

# Return only the classification columns (old default behaviour)
biomes_classify(biomes_example, scheme = 1, append = FALSE)

Download the packaged biome raster stack

Description

The 31-layer biome raster stack (Biomes_Inventory_RasterStack.tif, ~36 MB) is too large to ship inside the package on CRAN. It is hosted as a release asset on GitHub instead. biomes_download() fetches it once and reuses the local copy on every later call, including every internal use by biomes_get() or biomes_classify().

Usage

biomes_download(path = NULL, overwrite = FALSE, quiet = FALSE)

Arguments

Details

The storage location is chosen as follows:

• If path is supplied, the raster is written to that directory and no other location is touched.

• If path is NULL and a copy already exists in the persistent per-user cache directory (see tools::R_user_dir()), that copy is reused.

• Otherwise, in interactive sessions, the function asks once for permission to store the raster in the persistent per-user cache directory, so that the download happens only once across R sessions.

• If permission is declined, or in non-interactive sessions, the raster is stored under tempdir() and is removed automatically when the R session ends.

The package therefore never writes outside tempdir() without the user's explicit consent (an interactive confirmation or an explicit path).

Value

The local file path to the raster, invisibly.

See Also

biomes_get() to load the raster as a terra::SpatRaster.

Examples

# Downloads ~36 MB into the session's temporary directory.
raster_path <- biomes_download(path = tempdir())
raster_path

Example species occurrence dataset

Description

A cleaned subset of species occurrence records downloaded from GBIF, used in examples and vignettes to demonstrate biome classification.

Usage

biomes_example

Format

A data frame with 29,104 rows and 5 columns:

genus

Genus name.

species

Scientific species name.

countryCode

ISO 3166-1 alpha-2 country code of the record.

decimalLongitude

Decimal longitude in WGS84.

decimalLatitude

Decimal latitude in WGS84.

Source

Records downloaded and cleaned from the Global Biodiversity Information Facility (GBIF). See inst/extdata/GBIF_example_citation.txt for the full citation.

One-call workflow: from taxon (or dataset) to table (and optional figure)

Description

Convenience wrapper that runs the full biomes workflow in a single call. There are two entry paths:

Usage

biomes_full(
  x = NULL,
  taxon = NULL,
  scheme = "best",
  lon = "decimalLongitude",
  lat = "decimalLatitude",
  value = "name",
  plot = "none",
  show = FALSE,
  ...
)

Arguments

Details

1. From a taxon name. Pass a scientific name as taxon (x = NULL). biomes_full() calls biomes_occ() to download cleaned GBIF occurrences for the taxon and then proceeds as below.

2. From an occurrence dataset. Pass a data frame, sf object or terra::SpatVector as x (taxon = NULL).

Once occurrences are available the function:

• picks the biome scheme (either ⁠scheme = <integer>⁠ or, with the default scheme = "best", by running biomes_rank() and selecting the top-1 scheme);

• classifies the records with biomes_classify();

• tabulates them with biomes_tab();

• optionally builds a figure with biomes_visualise() (controlled by plot; skipped by default for speed).

Value

Invisibly, a biomes_full list with elements:

occ

The occurrence data frame (downloaded or provided).

scheme

The chosen biome scheme number.

ranking

The ranking data frame (only when scheme = "best"), otherwise NULL.

classified

The output of biomes_classify().

table

The biome occurrence table from biomes_tab().

plot

The combined, lettered figure (only when plot = "all"), otherwise NULL.

rank, map, barplot

The individual panels (no letters), each present only when requested via plot = c(...), otherwise NULL.

Examples

## Not run: 
# Path 1: from a taxon name. Queries the GBIF web service and may
# prompt for the download workflow (GBIF credentials), so it is not
# run here.
res <- biomes_full(taxon = "Fagus sylvatica", limit = 2000)
res$table

## End(Not run)


# Path 2: from an existing data frame, pick the best scheme.
# Uses the biome raster (~36 MB), downloaded on first use.
data("biomes_example")
res <- biomes_full(x = biomes_example, scheme = "best")

# Path 2 with a fixed scheme
res <- biomes_full(x = biomes_example, scheme = 1)

# Path 2, best-fitting scheme within the vegetation group,
# and build the full figure
res <- biomes_full(x = biomes_example, scheme = "vegetation", plot = "all")
res$plot

# individual panels (no a-c letters) in $rank / $map / $barplot
res <- biomes_full(x = biomes_example, plot = c("map", "barplot"))
res$map
res$barplot

Load the packaged biome raster stack

Description

Loads the 31 biome layers shipped with the package as a terra::SpatRaster stack.

Usage

biomes_get(...)

Arguments

Value

A terra::SpatRaster with 31 layers, one per biome classification (in the same order as the rows of biomes_information).

Examples

# Load the default biome raster stack (downloads ~36 MB on first use)
biomes_raster <- biomes_get()
biomes_raster

Print metadata for selected biome definitions

Description

Prints a human-readable summary of the biome classifications shipped with the package. For each requested classification the function prints the publication, the criteria and methodology used to define the classes, a short description, the number of biome classes, the biome scheme number, and a list of biome-class names with their raster values.

Usage

biomes_info(x = NULL)

Arguments

Details

This is the interactive sibling of the biomes_information data set: use biomes_information when you want the raw metadata table (e.g. to subset, filter, or join programmatically), and biomes_info() when you want a quick read of the most relevant fields for a specific biome scheme.

Value

Invisibly returns the integer vector of biome scheme numbers that was printed. The function is called for its side effect of printing to the console.

See Also

biomes_information for the underlying metadata table and biomes_legend for the mapping from raster values to biome names.

Examples

# Print information for all biome definitions
biomes_info()

# Print information for the first three biomes
biomes_info(1:3)

Metadata for the 31 biome classifications

Description

A data frame containing descriptive metadata for each of the 31 biome classifications shipped with the package. Each row corresponds to one biome layer in the raster stack returned by biomes_get(), in the same order. The metadata is derived from the inventory compiled by Fischer et al. (2022).

Usage

biomes_information

Format

A data frame with 31 rows and 12 columns:

publication

Original publication of the biome classification.

name_of_classification

Full name of the classification scheme.

criteria_for_class_assignment

Criteria used to assign biome classes.

methodology

Methodology used to derive the biome classification.

scheme_number

Biome scheme number (1-31); index of the corresponding layer in the raster stack returned by biomes_get().

background_and_specifications

Free-text background information about the classification scheme.

number_of_classes_zonal_azonal

Total number of biome classes in the classification, with the split between zonal and azonal classes in parentheses.

cover_deviation_percent

Deviation of the total area covered by this classification from the mean area of all 31 classifications, in percent.

original_file_format

File format of the original data source (e.g. raster, shapefile).

source

URL or citation of the original data source.

access_date

Date on which the original data source was accessed.

scheme_type

Methodological group the classification belongs to, one of "climate", "vegetation", "land_cover", "ecoregion", "integrative" (combined climate-vegetation schemes), or "anthropogenic". Used by biomes_rank() to rank layers within a conceptually comparable group.

Details

This is the raw metadata table. For an interactive, human-readable summary of one or more classifications, see biomes_info().

Source

Fischer J-C, Walentowitz A, Beierkuhnlein C (2022) The biome inventory - Standardizing global biogeographical units. Global Ecology and Biogeography 31(11): 2172-2183. doi:10.1111/geb.13574

Legend (biome class names) for the 31 biome classifications

Description

A data frame mapping the raster values used in each of the 31 biome layers to human-readable biome class names. Each row corresponds to one layer in the raster stack returned by biomes_get(), in the same order. Columns id_1, id_2, ... give the biome class names for raster values 1, 2, ..., respectively. Cells are NA for classifications with fewer classes than the maximum across all classifications.

Usage

biomes_legend

Format

A data frame with 31 rows and 41 columns:

layer

Index of the layer in the raster stack returned by biomes_get().

source

Short reference to the publication that defines the classification.

id_1, id_2, id_3, id_4, id_5, id_6, id_7, id_8, id_9, id_10, id_11, id_12, id_13, id_14, id_15, id_16, id_17, id_18, id_19, id_20, id_21, id_22, id_23, id_24, id_25, id_26, id_27, id_28, id_29, id_30, id_31, id_32, id_33, id_34, id_35, id_36, id_37, id_38, id_39

Biome class names for raster values 1 through 39. NA if the classification has fewer classes.

Source

Fischer J-C, Walentowitz A, Beierkuhnlein C (2022) The biome inventory - Standardizing global biogeographical units. Global Ecology and Biogeography 31(11): 2172-2183. doi:10.1111/geb.13574

Download and clean GBIF occurrences for a taxon

Description

Retrieves occurrence records for a given taxon (species, genus, family, ...) from GBIF and, optionally, runs standard coordinate cleaning with CoordinateCleaner::clean_coordinates().

Usage

biomes_occ(
  taxon,
  use_download = FALSE,
  username = NULL,
  pwd = NULL,
  email = NULL,
  save_dir = NULL,
  filter_clean = TRUE,
  filter_sea = FALSE,
  year_min = NULL,
  year_max = NULL,
  country = NULL,
  limit = NULL,
  slim = TRUE
)

Arguments

Details

By default, biomes_occ() first asks GBIF how many records exist for the taxon and then prompts the user (in interactive sessions):

1. Use rgbif::occ_search()? (no login required, capped at 100,000 records.) If yes, the user is then asked for the number of records. If no, the function switches to rgbif::occ_download(), which needs a save directory and GBIF credentials and downloads everything (you get a DOI for citation).

The only GBIF predicate applied is hasCoordinate = TRUE. The result is slim by default: family, genus, species, year, countryCode, decimalLongitude, decimalLatitude. Set slim = FALSE to keep every GBIF column. With occ_download() the downloaded data and the GBIF citation are written to save_dir.

Value

A data frame of GBIF occurrence records, optionally cleaned. Always contains decimalLongitude and decimalLatitude columns (when records are returned), so the result can be passed directly to biomes_classify(), biomes_rank() or biomes_full().

Examples

## Not run: 
# interactive: prompted for occ_search vs occ_download
occ <- biomes_occ(taxon = "Solemyida")

# force the GBIF download workflow up front (requires credentials)
occ <- biomes_occ(
  taxon        = "Fagus sylvatica",
  use_download = TRUE,
  username     = "xxx",
  pwd          = "xxx",
  email        = "you@example.org",
  save_dir     = file.path(tempdir(), "GBIF")
)

## End(Not run)

Rank biome schemes for a given occurrence dataset

Description

Compares the biome classification layers for a user-supplied set of occurrences and proposes a single "best" layer for that dataset. Each layer is scored on several data-driven criteria that are combined into one composite_score, which drives the ranking.

Usage

biomes_rank(
  x,
  scheme = NULL,
  biome = NULL,
  lon = "decimalLongitude",
  lat = "decimalLatitude",
  scheme_type = "all",
  criteria = c("coverage", "effective_classes", "granularity"),
  tiebreaker = c("year", "classes", "none"),
  verbose = TRUE
)

Arguments

Details

By default, three equally weighted criteria are used:

1. coverage: fraction of records that the layer places in a biome at all (the rest fall on unclassified, NA cells).

2. effective_classes: \exp(H') (Hill number of order 1), i.e. the effective number of biomes the records spread across, weighted by evenness.

3. granularity: biome classes actually used, divided by the classes available in the layer.

Two further criteria can be requested via criteria:

• informativeness: Pielou's evenness J' = H' / \log(k_{used}).

• agreement: mean pairwise Cohen's \kappa against the other layers (Monserud & Leemans 1992).

All raw scores are min-max scaled to [0, 1] across the compared layers and averaged into the composite_score. Layers are then ordered by this score and ties resolved according to tiebreaker.

Value

A data frame of classes biomes_rank and data.frame, with one row per compared biome scheme. Columns: scheme (the biome scheme number, 1-31), scheme_name, year (publication year of the scheme), n_total, n_hit and n_na (number of records in total, classified, and unclassified), pct_na (percentage of unclassified records), then one ⁠*_raw⁠ and one ⁠*_scaled⁠ column per requested criterion (the raw score and its min-max scaled version), composite_score (mean of the scaled criteria, drives the ranking), rank (1 = best), and is_best (TRUE for the top-ranked scheme). The result carries the attributes criteria, tiebreaker, scheme_type, and best_scheme (the biome scheme number of the top-ranked scheme, ready to be used as the scheme argument of biomes_classify() or biomes_full()).

Note

biomes_rank() gives a data-driven ranking, not an authoritative "best" classification. The criteria favour layers that cover your records and split them into many, evenly-used classes, but the top-ranked layer is not necessarily the most suitable one for your question. For best results, narrow the comparison to a meaningful group via scheme_type, and treat the ranking as a shortlist rather than a verdict: inspect the per-criterion columns in the result and use biomes_info() to choose the layer whose definition and resolution actually match your data.

Examples

data("biomes_example")


# Ranks layers of the biome raster (~36 MB), downloaded on first use.

# Default call: coverage + effective_classes + granularity, equally weighted
r <- biomes_rank(biomes_example, verbose = FALSE)
head(r)
attr(r, "best_scheme")

# Restrict to a subset of criteria
r2 <- biomes_rank(
  biomes_example,
  criteria = c("coverage", "effective_classes"),
  verbose  = FALSE
)

Tabulate the number of occurrences per biome

Description

Summarizes the number of occurrence records (one row of x = one occurrence) in each biome, for one or more biome layers. The output is a long-format table with one row per (layer, biome) pair.

Usage

biomes_tab(x, value = "names")

Arguments

Details

This function counts occurrences, not species. To count unique species per biome, deduplicate by species before tabulating (e.g. dplyr::distinct(species, biome) after combining classifications with the original data).

Value

A data frame with columns scheme, biome, and n (the number of occurrence records in that biome class on that scheme).

Examples

# Load example occurrence data
data("biomes_example")


# biomes_classify() downloads and caches the biome raster (~36 MB).

# Tabulate by biome name
classified_names <- biomes_classify(
  x     = biomes_example,
  value = "name"
)
biomes_tab(classified_names, value = "names")

# Tabulate by raster value
classified_ids <- biomes_classify(
  x     = biomes_example,
  value = "ID"
)
biomes_tab(classified_ids, value = "ID")

Visualise the biomes workflow (ranking, map and biome-class composition)

Description

Produces the publication figure of the biomes workflow for a set of occurrence records. Up to three panels are drawn and combined:

Usage

biomes_visualise(
  x,
  scheme = NULL,
  scheme_type = "all",
  biome = NULL,
  lon = "decimalLongitude",
  lat = "decimalLatitude",
  panels = c("rank", "map", "barplot"),
  legend_counts = TRUE,
  legend = TRUE,
  point_color = "#B20000",
  point_size = 0.25,
  combine = TRUE,
  verbose = FALSE
)

Arguments

Details

• rank: the data-driven ranking of the biome schemes (biomes_rank()): the composite score per scheme (best highlighted) next to the raw criterion values it averages (coverage, effective number of classes, granularity, ...).

• map: the occurrence records (points) mapped over the chosen biome scheme, with the number of records per biome class optionally appended to the legend labels.

• barplot: the number of occurrence records (left) and species (right) per biome class, with the biome-class names in the centre.

Which panels are drawn is controlled by panels; the panel letters (a, b, c) are assigned in drawing order, so selecting only rank and barplot labels them (a) and (b).

Value

For a single panel, a ggplot object. For several panels: a combined cowplot object when combine = TRUE (default), or a named list of ggplot objects (rank, map, barplot) when combine = FALSE. Print to display or save with ggplot2::ggsave().

Examples

data("biomes_example")
# full figure (rank + map + barplot), best scheme chosen automatically
biomes_visualise(biomes_example)

# only the map, for a fixed scheme
biomes_visualise(biomes_example, scheme = 1, panels = "map")

# map + barplot for the best vegetation scheme
biomes_visualise(biomes_example, scheme_type = "vegetation",
                 panels = c("map", "barplot"))