Skip to contents

Annotate a GBIF download with annotation terms from rules

Source: R/annotate_download.R
annotate_download.Rd

Adds an "annotations" column to the download containing annotation terms (SUSPICIOUS, NATIVE, INTRODUCED, etc.) from matching rules. Multiple annotations for the same record are semicolon-delimited. Records without any matching annotations will have NA in the annotations column. If project_id is provided, only rules belonging to those project(s) will be used. When use_higher_taxonomy is TRUE, rules can match records at any taxonomic level present in the download.

Usage

annotate_download(
  d,
  project_id = NULL,
  use_higher_taxonomy = FALSE,
  include_vote_counts = FALSE,
  min_support = NULL,
  exclude_contested = FALSE
)

Arguments

d

a GBIF download in DWCA format

project_id

optional project ID(s) to filter rules by specific project(s). Can be a single ID or vector of IDs.

use_higher_taxonomy

logical; if TRUE, rules will match records based on higher taxonomic ranks. The function checks for matches against kingdomKey, phylumKey, classKey, orderKey, familyKey, genusKey, speciesKey, and taxonKey columns in the download data. For example, a rule created for taxonKey 212 (Aves/Birds) will match all bird species records that have classKey = 212. Default is FALSE for conservative, explicit annotations only.

include_vote_counts

logical; if TRUE, add support_count and contest_count columns to the output showing the number of supports and contests for each annotation. For records with multiple annotations, shows the counts for the most-supported rule. Default is FALSE.

min_support

integer; minimum number of supports required for a rule to be applied. NULL (default) means no minimum. Only rules with at least this many supports will be used.

exclude_contested

logical; if TRUE, exclude any rules that have been contested (downvoted). Default is FALSE.

Value

The original download `data.frame()` with an added `annotations` column

Examples

if (FALSE) { # \dontrun{
library(rgbif)
# Download and annotate
d <- occ_download_get('0004693-260120142942310') %>%
  occ_download_import()

# Annotate with all available rules
annotated <- annotate_download(d)

# Annotate using only rules from a specific project
annotated <- annotate_download(d, project_id = 1)

# Annotate using rules from multiple projects
annotated <- annotate_download(d, project_id = c(1, 2, 3))

# Enable higher taxonomy matching
annotated <- annotate_download(d, use_higher_taxonomy = TRUE)

# Include vote counts for transparency
annotated <- annotate_download(d, include_vote_counts = TRUE)

# Only use well-supported, uncontested rules
annotated <- annotate_download(d, min_support = 3, exclude_contested = TRUE)
} # }