Package 'RuHere'

Description

A data set of amphibian communities from the Atlantic Forests of South America sourced from Vancine et al. (2018).

Usage

atlantic_amphibians

Format

A data.table or data.frame with 8,254 rows and 3 columns:

species

Character. Scientific name of the virtual species.

decimalLongitude

Numeric. Georeferenced longitude in decimal degrees.

decimalLatitude

Numeric. Georeferenced latitude in decimal degrees.

References

Vancine et al. 2018. ATLANTIC AMPHIBIANS: a data set of amphibian communities from the Atlantic Forests of South America. Ecology, 99(7), 1692-1692. doi:10.1002/ecy.2392

See Also

inventory_completeness()

Examples

# First rows
head(atlantic_amphibians)

Description

This function checks which datasets contain distributional information for a given set of species, based on expert-curated sources. It searches the selected datasets and reports whether each species has available distribution data.

Usage

available_datasets(
  data_dir,
  species,
  datasets = "all",
  return_distribution = FALSE
)

Arguments

Details

The distribution datasets can be obtained using the functions florabr_here(), wcvp_here(), bien_here(), and faunabr_here(), which download and prepare the corresponding sources for use in RuHere.

Value

If return_distribution = FALSE, a data.frame containing the species names and the datasets where distributional information is available. If return_distribution = TRUE, it also returns a list containing the SpatVector objects representing the species ranges.

Examples

# Set directory where datasets were saved
# Here, we'll use the directory where the example datasets are stored
datadir <- system.file("extdata", "datasets",  package = "RuHere")
# Check available datasets
d <- available_datasets(data_dir = datadir,
                        species = c("Araucaria angustifolia",
                                    "Handroanthus serratifolius",
                                    "Cyanocorax caeruleus"))
# Check available datasets and return distribution
d2 <- available_datasets(data_dir = datadir,
                         species = c("Araucaria angustifolia",
                                     "Handroanthus serratifolius",
                                     "Cyanocorax caeruleus"),
                         return_distribution = TRUE)

Description

This function downloads distribution information from the BIEN database, required for filtering occurrence records using specialists' information via the flag_bien() function.

Usage

bien_here(
  data_dir,
  species,
  synonyms = NULL,
  overwrite = TRUE,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Details

This function uses the BIEN::BIEN_ranges_load_species() function to retrieve polygons representing the distribution ranges of species available in the BIEN database.

Because taxonomic information in BIEN may be outdated, you can optionally provide a table of synonyms to broaden the search. The synonyms data.frame should have the accepted species in the first column and their synonyms in the second. See RuHere::synonys for an example.

Value

A data frame indicating whether the polygon(s) representing the species range are available in BIEN. If the range is available, a GeoPackage file (.gpkg) is saved in data_dir/bien. The file name corresponds to the species name, with an underscore (“_”) replacing the space between the genus and the specific epithet.

Examples

# Define a directory to save the data
data_dir <- tempdir() # Here, a temporary directory

# Download species distribution information from BIEN
bien_here(data_dir = data_dir, species = "Handroanthus serratifolius")

Description

Combines multiple occurrence data frames (for example, from GBIF, SpeciesLink, BIEN, or iDigBio) into a single standardized dataset. This is particularly useful after using format_columns() to ensure column compatibility across data sources.

Usage

bind_here(..., fill = FALSE)

Arguments

Details

When fill = TRUE, columns not shared among the input data frames are added and filled with NA, ensuring that all columns align before binding. Internally, this function uses data.table::rbindlist() for efficient row binding.

Value

A data.frame containing all occurrence records combined.

Examples

# Import and standardize GBIF
data("occ_gbif", package = "RuHere") #Import data example
gbif_standardized <- format_columns(occ_gbif, metadata = "gbif")
# Import and standardize SpeciesLink
data("occ_splink", package = "RuHere") #Import data example
splink_standardized <- format_columns(occ_splink, metadata = "specieslink")
# Import and standardize BIEN
data("occ_bien", package = "RuHere") #Import data example
bien_standardized <- format_columns(occ_bien, metadata = "bien")
# Import and standardize idigbio
data("occ_idig", package = "RuHere") #Import data example
idig_standardized <- format_columns(occ_idig, metadata = "idigbio")
# Merge all
all_occ <- bind_here(gbif_standardized, splink_standardized,
                      bien_standardized, idig_standardized)

Description

Check if the records fall in the country assigned in the metadata

Usage

check_countries(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  country_column,
  distance = 5,
  try_to_fix = FALSE,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Value

The original occ data.frame with an additional column (correct_country) indicating whether each record falls within the country specified in the metadata (TRUE) or not (FALSE).

Examples

# Load example data
data("occurrences", package = "RuHere") #Import data example
# Standardize country names
occ_country <- standardize_countries(occ = occurrences,
                                     return_dictionary = FALSE)
# Check whether records fall within assigned countries
occ_country_checked <- check_countries(occ = occ_country,
                                       country_column = "country_suggested")

Description

Check if the records fall in the state assigned in the metadata

Usage

check_states(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  state_column,
  distance = 5,
  try_to_fix = FALSE,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Value

The original occ data.frame with an additional column (correct_state) indicating whether each record falls within the state specified in the metadata (TRUE) or not (FALSE).

Examples

# Load example data
data("occurrences", package = "RuHere") #Import data example
# Subset occurrences for Araucaria angustifolia
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Standardize country names
occ_country <- standardize_countries(occ = occ,
                                     return_dictionary = FALSE)
# Standardize state names
occ_state <- standardize_states(occ = occ_country,
                                country_column = "country_suggested",
                                return_dictionary = FALSE)
# Check whether records fall within assigned states
occ_state_checked <- check_states(occ = occ_state,
                                    state_column = "state_suggested")

Description

country_dictionary provides a set of lookup tables used to standardize country names and country codes in occurrence datasets.

The dictionary is built from rnaturalearthdata::map_units110 and consolidates a wide variety of country name variants (in several languages and formats), as well as multiple coding systems, into a single suggested standardized name.

This object is used internally by functions that clean or harmonize country fields, ensuring that country names in occurrence datasets (e.g., "Brasil","brasil", "BR", "BRA", "République Française") are all mapped consistently to a single standardized form ("brazil", "france", etc.).

Usage

country_dictionary

Format

A named list of two data frames:

country_name

A data frame with two columns:

country_name

Character. Lowercased and accent-stripped country name variants (from multiple rnaturalearthdata fields such as name, name_long, abbrev, formal_en, and alternative names in several languages).

country_suggested

Character. The standardized country name, derived from the name column of map_units110, also lowercased and accent-stripped.

country_code

A data frame with two columns:

country_code

Character. Country codes from several systems, including ISO-2, ISO-3, FIPS, postal codes, and others, after filtering invalid or ambiguous codes.

country_suggested

Character. The standardized country name corresponding to each code.

Details

The dictionary is generated by:

• extracting multiple name and code fields from rnaturalearthdata::map_units110,

• converting names to lowercase and removing accents,

• converting codes to uppercase,

• removing invalid or ambiguous codes (e.g., -99, "J", various country mismatches),

• and ensuring uniqueness across all entries.

Examples

data(country_dictionary)

head(country_dictionary$country_name)
head(country_dictionary$country_code)

Description

Extracts the country for each occurrence record based on coordinates.

Usage

country_from_coords(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  country_column = NULL,
  from = "all",
  output_column = "country_xy",
  append_source = FALSE
)

Arguments

Details

The countries are extracted from coordinates using a map retrieved from rnaturalearthdata::map_units110.

Value

The original occ data.frame with an additional column containing the countries extracted from coordinates.

Examples

# Import and standardize GBIF
data("occ_gbif", package = "RuHere") #Import data example
gbif_standardized <- format_columns(occ_gbif, metadata = "gbif")
gbif_countries <- country_from_coords(occ = gbif_standardized)

Description

This function creates a metadata template to be used in format_columns() for formatting and standardizing column names and classes in occurrence datasets. All column names specified as arguments must be present in the occ dataset.

If you obtained data from GBIF, SpeciesLink, BIEN or iDigBio using the functions provided in the RuHere package, you do not need to use this function, as the package already includes metadata templates for these datasets.

Usage

create_metadata(
  occ,
  scientificName,
  decimalLongitude,
  decimalLatitude,
  collectionCode = NA,
  catalogNumber = NA,
  coordinateUncertaintyInMeters = NA,
  elevation = NA,
  country = NA,
  stateProvince = NA,
  municipality = NA,
  locality = NA,
  year = NA,
  eventDate = NA,
  recordedBy = NA,
  identifiedBy = NA,
  basisOfRecord = NA,
  occurrenceRemarks = NA,
  habitat = NA,
  datasetName = NA,
  datasetKey = NA,
  key = NA
)

Arguments

Value

A data.frame containing a metadata template that can be directly used in the format_columns() function.

Examples

# Load data example
# Occurrences of Puma concolor from the atlanticr R package
data("puma_atlanticr", package = "RuHere")
# Create metadata to standardize the occurrences
puma_metadata <- create_metadata(occ = puma_atlanticr,
                                 scientificName = "actual_species_name",
                                 decimalLongitude = "longitude",
                                 decimalLatitude = "latitude",
                                 elevation = "altitude",
                                 country = "country",
                                 stateProvince = "state",
                                 municipality = "municipality",
                                 locality = "study_location",
                                 year = "year_finish",
                                 habitat = "vegetation_type",
                                 datasetName = "reference")
# Now, we can use this metadata to standardize the columns
puma_occ <- format_columns(occ = puma_atlanticr, metadata = puma_metadata,
                           binomial_from = "actual_species_name",
                           data_source = "atlanticr")

Description

cultivated is a list of character vectors containing keywords used to identify whether an occurrence record refers to cultivated or non-cultivated individuals.

This object is used internally by flag_cultivated() to scan occurrence fields (such as notes, habitat descriptions, or remarks) and classify records as cultivated or not cultivated based on textual patterns.

The list combines terms from plantR (plantR:::cultivated and plantR:::notCultivated) with additional multilingual variants commonly found in herbarium metadata.

Usage

cultivated

Format

A named list with two elements:

cultivated

Character vector. Terms that indicate an individual is cultivated. Imported from plantR:::cultivated.

not_cultivated

Character vector. Terms suggesting an individual is not cultivated (e.g., “not cultivated”, “not planted”, “no plantada”, “no cultivada”), including terms from plantR:::notCultivated.

Details

These terms are matched case-insensitively after text cleaning (e.g., lowercasing and accent removal).

References

de Lima, Renato AF, et al. plantR: An R package and workflow for managing species records from biological collections. Methods in Ecology and Evolution, 14.2 (2023): 332-339.

See Also

flag_cultivated

Examples

data(cultivated)

cultivated$cultivated
cultivated$not_cultivated

Description

fake_data is a synthetic dataset created for testing functions that validate and correct country- or state-level geographic coordinates.

Controlled coordinate errors were introduced (e.g., inverted signs, swapped values, combinations of swaps and inversions) to simulate common georeferencing mistakes.

This dataset is intended for automated testing of functions such as check_countries() and check_states().

Usage

fake_data

Format

A data frame with the same structure as all_occ, containing occurrence records with intentionally manipulated coordinates. An additional column data_source = "fake_data" identifies these records.

Details

The coordinate errors include:

• Inverted longitude: multiplying longitude by -1.

• Inverted latitude: multiplying latitude by -1.

• Both coordinates inverted.

• Swapped coordinates: (lon, lat) → (lat, lon).

• Swapped + inverted in four combinations:

  • swapped only,

  • swapped + inverted longitude,

  • swapped + inverted latitude,

  • swapped + both inverted.

Examples

data(fake_data)

Description

This function downloads the Taxonomic Catalog of the Brazilian Fauna database, which is required for filtering occurrence records using specialists' information via the flag_faunabr() function.

Usage

faunabr_here(
  data_dir,
  data_version = "latest",
  solve_discrepancy = TRUE,
  overwrite = TRUE,
  remove_files = TRUE,
  verbose = TRUE
)

Arguments

Value

A message indicating that the data were successfully saved in the directory specified by data_dir.

Examples

# Define a directory to save the data
data_dir <- tempdir() # Here, a temporary directory

# Download the latest version of the Flora e Funga do Brazil database
faunabr_here(data_dir = data_dir)

Description

This function identifies and correct inverted and transposed coordinates based on country information

Usage

fix_countries(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  country_column,
  correct_country = "correct_country",
  distance = 5,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Details

The function checks and corrects coordinate errors in occurrence records by testing whether each point falls within the expected country polygon (from RuHere’s internal world map).

The input occurrence data must contain a column (specified in the correct_country argument) with logical values indicating which records to check and fix — only those marked as FALSE will be processed. This column can be obtained by running the check_countries() function.

It runs a series of seven tests to detect common issues such as inverted signs or swapped latitude/longitude values. Inverted coordinates have their signs flipped (e.g., -45 instead of 45), placing the point in the opposite hemisphere, while swapped coordinates have latitude and longitude values exchanged (e.g., -47, -15 instead of -15, -47).

For each test, country borders are buffered by distance km to account for minor positional errors.

The type of issue (or "correct") is recorded in a new column, country_issues. Records that match their assigned country after any correction are updated accordingly, while remaining mismatches are labeled "incorrect".

This function can be used internally by check_countries() to automatically identify and fix common coordinate errors.

Value

The original occ data.frame with the coordinates in the long and lat columns corrected, and an additional column (country_issues) indicating whether the coordinates are:

• correct: the record falls within the assigned country;

• inverted: longitude and/or latitude have reversed signs;

• swapped: longitude and latitude are transposed (i.e., each appears in the other's column). incorrect: the record falls outside the assigned country and could not be corrected.

Examples

# Load example data
data("occurrences", package = "RuHere") # Import example data

# Standardize country names
occ_country <- standardize_countries(occ = occurrences,
                                     return_dictionary = FALSE)

# Check whether records fall within the assigned countries
occ_country_checked <- check_countries(occ = occ_country,
                                       country_column = "country_suggested")

# Fix records with incorrect or misassigned countries
occ_country_fixed <- fix_countries(occ = occ_country_checked,
                                   country_column = "country_suggested")

Description

This function identifies and correct inverted and transposed coordinates based on state information.

Usage

fix_states(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  state_column,
  correct_state = "correct_state",
  distance = 5,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Details

The function checks and corrects coordinate errors in occurrence records by testing whether each point falls within the expected state polygon (from RuHere’s internal world map).

The input occurrence data must contain a column (specified in the correct_state argument) with logical values indicating which records to check and fix — only those marked as FALSE will be processed. This column can be obtained by running the check_states() function.

It runs a series of seven tests to detect common issues such as inverted signs or swapped latitude/longitude values. Inverted coordinates have their signs flipped (e.g., -45 instead of 45), placing the point in the opposite hemisphere, while swapped coordinates have latitude and longitude values exchanged (e.g., -47, -15 instead of -15, -47).

For each test, state borders are buffered by distance km to account for minor positional errors.

The type of issue (or "correct") is recorded in a new column, state_issues. Records that match their assigned state after any correction are updated accordingly, while remaining mismatches are labeled "incorrect".

This function can be used internally by check_states() to automatically identify and fix common coordinate errors.

Value

The original occ data.frame with the coordinates in the long and lat columns corrected, and an additional column (state_issues) indicating whether the coordinates are:

• correct: the record falls within the assigned state;

• inverted: longitude and/or latitude have reversed signs;

• swapped: longitude and latitude are transposed (i.e., each appears in the other's column). incorrect: the record falls outside the assigned state and could not be corrected.

Examples

# Load example data
data("occurrences", package = "RuHere") # Import example data
# Subset records of Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Standardize country names
occ_country <- standardize_countries(occ = occ,
                                     return_dictionary = FALSE)

# Standardize state names
occ_state <- standardize_states(occ = occ_country,
                                country_column = "country_suggested",
                                return_dictionary = FALSE)

# Check whether records fall within the assigned states
occ_states_checked <- check_states(occ = occ_state,
                                   state_column = "state_suggested")

# Fix records with incorrect or misassigned states
occ_states_fixed <- fix_states(occ = occ_states_checked,
                               state_column = "state_suggested")

Description

Flags (validates) occurrence records based on known distribution data from the Botanical Information and Ecology Network (BIEN) data. This function checks if an occurrence point for a given species falls within its documented distribution, allowing for user-defined buffers around the region. Records are flagged as valid (TRUE) if they fall inside the documented distribution (plus optional buffer) for the species in the BIEN dataset.

Usage

flag_bien(
  data_dir,
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  buffer = 10,
  progress_bar = FALSE,
  verbose = TRUE
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named bien_flag. This column is logical (TRUE/FALSE) indicating whether the record falls within the expected distribution (plus buffer) based on the BIEN data. Records for species not found in the BIEN data will have NA in the bien_flag column.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Filter occurrences for golden trumpet tree
occ <- occurrences[occurrences$species == "Handroanthus serratifolius", ]
# Set folder where distributional datasets were saved
# Here, just a sample provided in the package
# You must run 'bien_here()' beforehand to download the necessary data files
dataset_dir <- system.file("extdata/datasets", package = "RuHere")

# Flag records using BIEN specialist information
occ_bien <- flag_bien(data_dir = dataset_dir, occ = occ)

Description

flag_colors is a named character vector defining the default colors used to plot occurrence records flagged with mapview_here().

Usage

flag_colors

Format

A named character vector where:

names

Flag labels corresponding to categories generated by the various ⁠flag_*⁠ and checking functions.

values

Hex color codes or standard R color names used for plotting.

See Also

mapview_here

Examples

data(flag_colors)

# View all flag categories and their colors
flag_colors

Description

This functions creates a new column representing the consensus across multiple flag columns. The consensus can be computed in two ways:

• "all_true": A record is considered valid (TRUE) only if all specified flag are valid (TRUE).

• "any_true": A record is considered valid (TRUE) if at least one specified flag is valid (TRUE).

Usage

flag_consensus(
  occ,
  flags,
  consensus_rule = "all_true",
  flag_name = "consensus_flag",
  remove_flag_columns = FALSE
)

Arguments

Details

The following flags are available: correct_country, correct_state, cultivated, fossil, inaturalist, faunabr, florabr, wcvp, iucn, duplicated, thin_geo, thin_env, year, .val, .equ, .zer, .cap, .cen, .sea, .urb, .otl, .gbf, .inst, and .aohi.

Value

The original occ with an additional logical column defined by flag_name, indicating the consensus result based on the selected consensus_rule.

Examples

# Load example data
data("occ_flagged", package = "RuHere")

# Get consensus using florabr, wcvp, and iucn flags
 # Valid (TRUE) only when all flags are TRUE
occ_consensus_all <- flag_consensus(occ = occ_flagged,
                                    flags = c("florabr", "wcvp", "iucn"),
                                    consensus_rule = "all_true")
# Valid (TRUE) when at least one flag is TRUE
occ_consensus_any <- flag_consensus(occ = occ_flagged,
                                    flags = c("florabr", "wcvp", "iucn"),
                                    consensus_rule = "any_true")

Description

This function identifies records of cultivated individuals based on record description.

Usage

flag_cultivated(
  occ,
  columns = c("occurrenceRemarks", "habitat", "locality"),
  cultivated_terms = NULL,
  not_cultivated_terms = NULL
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named cultivated_flag. Records identified as cultivated receive FALSE, while all other records receive TRUE.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Flag fossil records
occ_cultivated <- flag_cultivated(occ = occurrences)

Description

This function identifies duplicated records based on species name and coordinates, as well as user-defined additional columns or raster cells. Among duplicated records, the function keeps only one unflagged record, chosen according to a continuous variable (e.g., keeping the most recent), a categorical variable (e.g., prioritizing a specific data source), or randomly.

Usage

flag_duplicates(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  additional_groups = NULL,
  continuous_variable = NULL,
  decreasing = TRUE,
  categorical_variable = NULL,
  priority_categories = NULL,
  by_cell = FALSE,
  raster_variable = NULL
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named duplicated_flag. Records identified as duplicated receive FALSE, while all unique retained records receive TRUE.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Duplicate some records as example
occurrences <- rbind(occurrences[1:1000, ], occurrences[1:100,])
# Flag duplicates
occ_dup <- flag_duplicates(occ = occurrences)
sum(!occ_dup$duplicated_flag) #Number of duplicated records

Description

This function evaluates multiple environmentally thinned datasets (produced using different number of blocks) and selects the one that best balances low spatial autocorrelation and number of retained records.

For each number of bins provided in n_bins, the function computes Moran's I for the selected environmental variables and summarizes autocorrelation using a chosen statistic (mean, median, minimum, or maximum). The best thinning level is then selected according to criteria described in Details.

Usage

flag_env_moran(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  env_layers,
  n_bins,
  distance = "haversine",
  moran_summary = "mean",
  min_records = 10,
  min_imoran = 0.1,
  prioritary_column = NULL,
  decreasing = TRUE,
  do_pca = FALSE,
  mask = NULL,
  pca_buffer = 1000,
  flag_for_NA = FALSE,
  return_all = FALSE,
  verbose = TRUE
)

Arguments

Details

This function is inspired by the approach used in Velazco et al. (2020), extending the procedure by allowing:

• prioritization of records based on a user-defined variable (e.g., year)

• optional PCA transformation of environmental layers

• selection rules that prevent datasets with too few records or extremely low Moran's I from being chosen.

Procedure overview

1. For each bin number in n_bins, generate a spatially thinned dataset using thin_env() function.

2. Extract environmental values for the retained records.

3. Compute Moran's I for each environmental variable.

4. Summarize autocorrelation per dataset (mean, median, min, or max).

5. Apply the selection criteria:

   • Keep only datasets with at least min_records records.

   • Keep only datasets with Moran's I greater or equal to min_imoran.

   • Round Moran's I to two decimal places and select the dataset with the 25th lowest autocorrelation.

   • If more than on dataset is selected, choose the dataset retaining more records.

   • If still tied, choose the dataset with the largest number of bins.

Distance matrix for Moran's I Moran's I requires a weight matrix derived from pairwise distances among records. Two distance types are available:

• "haversine": geographic distance computed with fields::rdist.earth() (default; recommended for longitude/latitude coordinates)

• "euclidean": Euclidean distance computed with stats::dist()

Environmental PCA (optional) If do_pca = TRUE, the environmental layers are summarized using PCA before Moran's I is computed.

• If mask is provided, PCA is computed on masked layers.

• Otherwise, a convex hull around the records is buffered by pca_buffer kilometers to define the PCA area.

• It will select the axis that together explain more than 90% of the variation.

Value

A list with:

• occ: the selected thinned occurrence dataset with the column thin_env_flagindicating whether each record is retained (TRUE) or flagged as redundant (FALSE) in the environmental space .

• imoran: a table summarizing Moran's I for each thinning distance

• n_bins: the number of bins that produced the selected dataset

• moran_summary: the summary statistic used to select the dataset

• all_thined: (optional) list of thinned datasets for all bin numbers. Only returned if return_all was set to TRUE

Examples

# Load example data
data("occurrences", package = "RuHere")
# Subset occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Load example of raster variables
data("worldclim", package = "RuHere")
# Unwrap Packed raster
r <- terra::unwrap(worldclim)
# Select thinned occurrences
occ_env_moran <- flag_env_moran(occ = occ,
                                  n_bins = c(5, 10, 20, 30, 40, 50),
                                  env_layers = r)
# Selected number of bins
occ_env_moran$n_bins
# Number of flagged and unflagged records
sum(occ_env_moran$occ$thin_env_flag) #Retained
sum(!occ_env_moran$occ$thin_env_flag) #Flagged for thinning out
# Results os the spatial autocorrelation analysis
occ_env_moran$imoran

Description

Flags (validates) occurrence records based on known distribution data from the Catálogo Taxônomico da Fauna do Brasil (faunabr) data. This function checks if an occurrence point for a given species falls within its documented distribution, allowing for user-defined buffers around Brazilian states, or the entire country. Records are flagged as valid (TRUE) if they fall within the specified range for the distribution information available in the faunabr data.

Usage

flag_faunabr(
  data_dir,
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  origin = NULL,
  by_state = TRUE,
  buffer_state = 20,
  by_country = TRUE,
  buffer_country = 20,
  keep_columns = TRUE,
  spat_state = NULL,
  spat_country = NULL,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

Value

#' A data.frame that is the original occ data frame augmented with a new column named faunabr_flag. This column is logical (TRUE/FALSE) indicating whether the record falls within the expected distribution (plus buffer) based on the faunabr data. Records for species not found in the faunabr data will have NA in the faunabr_flag column.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Get only occurrences from Azure Jay
occ <- occurrences[occurrences$species == "Cyanocorax caeruleus", ]
# Set folder where distributional datasets were saved
# Here, just a sample provided in the package
# You must run 'faunabr_here()' beforehand to download the necessary data files for your species
dataset_dir <- system.file("extdata/datasets", package = "RuHere")
# Flag records using faunabr specialist information
occ_fauna <- flag_faunabr(data_dir = dataset_dir, occ = occ)

Description

Flags (validates) occurrence records based on known distribution data from the Flora e Funga do Brasil (florabr) data. This function checks if an occurrence point for a given species falls within its documented distribution, allowing for user-defined buffers around Brazilian states, biomes, or the entire country. Records are flagged as valid (TRUE) if they fall within the specified range for the distribution information available in the florabr data.

Usage

flag_florabr(
  data_dir,
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  origin = NULL,
  by_state = TRUE,
  buffer_state = 20,
  by_biome = TRUE,
  buffer_biome = 20,
  by_endemism = TRUE,
  buffer_brazil = 20,
  state_vect = NULL,
  state_column = NULL,
  biome_vect = NULL,
  biome_column = NULL,
  br_vect = NULL,
  keep_columns = TRUE,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named florabr_flag. This column is logical (TRUE/FALSE) indicating whether the record falls within the expected distribution (plus buffer) based on the florabr data. Records for species not found in the florabr data will have NA in the florabr_flag column.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Get only occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Set folder where distributional datasets were saved
# Here, just a sample provided in the package
# You must run 'florabr_here()' beforehand to download the necessary data files for your species
dataset_dir <- system.file("extdata/datasets", package = "RuHere")

# Flag records using specialist information from Flora do Brasil
occ_flora <- flag_florabr(data_dir = dataset_dir, occ = occ)

Description

This function identifies occurrence records that correspond to fossils, based on specific search terms found in selected columns.

Usage

flag_fossil(
  occ,
  columns = c("basisOfRecord", "occurrenceRemarks"),
  fossil_terms = NULL
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named fossil_flag. Records identified as fossils receive FALSE, while all other records receive TRUE.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Flag fossil records
occ_fossil <- flag_fossil(occ = occurrences)

Description

This function evaluates multiple geographically thinned datasets (produced using different thinning distances) and selects the one that best balances low spatial autocorrelation and number of retained records.

For each thinning distance provided in d, the function computes Moran's I for the selected environmental variables and summarizes autocorrelation using a chosen statistic (mean, median, minimum, or maximum). The best thinning level is then selected according to criteria described in Details.

Usage

flag_geo_moran(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  d,
  distance = "haversine",
  moran_summary = "mean",
  min_records = 10,
  min_imoran = 0.1,
  prioritary_column = NULL,
  decreasing = TRUE,
  env_layers,
  do_pca = FALSE,
  mask = NULL,
  pca_buffer = 1000,
  return_all = FALSE,
  verbose = TRUE
)

Arguments

Details

This function is inspired by the approach used in Velazco et al. (2021), extending the procedure by allowing:

• prioritization of records based on a user-defined variable (e.g., year)

• optional PCA transformation of environmental layers

• selection rules that prevent datasets with too few records or extremely low Moran's I from being chosen.

Procedure overview

1. For each distance in d, generate a spatially thinned dataset using thin_geo() function.

2. Extract environmental values for the retained records.

3. Compute Moran's I for each environmental variable.

4. Summarize autocorrelation per dataset (mean, median, min, or max).

5. Apply the selection criteria:

   • Keep only datasets with at least min_records records.

   • Keep only datasets with Moran's I higher than min_imoran.

   • Round Moran's I to two decimal places and select the dataset with the 25th lowest autocorrelation.

   • If more than on dataset is selected, choose the dataset retaining more records.

   • If still tied, choose the dataset with the smallest thinning distance.

Distance matrix for Moran's I Moran's I requires a weight matrix derived from pairwise distances among records. Two distance types are available:

• "haversine": geographic distance computed with fields::rdist.earth() (default; recommended for longitude/latitude coordinates)

• "euclidean": Euclidean distance computed with stats::dist()

Environmental PCA (optional) If do_pca = TRUE, the environmental layers are summarized using PCA before Moran's I is computed.

• If mask is provided, PCA is computed on masked layers.

• Otherwise, a convex hull around the records is buffered by pca_buffer kilometers to define the PCA area.

• It will select the axis that together explain more than 90% of the variation.

Value

A list with:

• occ: the selected thinned occurrence dataset with the column thin_geo_flagindicating whether each record is retained (TRUE) or flagged.

• imoran: a table summarizing Moran's I for each thinning distance

• distance: the thinning distance that produced the selected dataset

• moran_summary: the summary statistic used to select the dataset

• all_thined: (optional) list of thinned datasets for all distances. Only returned if return_all was set to TRUE

References

• Velazco, S. J. E., Svenning, J. C., Ribeiro, B. R., & Laureto, L. M. O. (2021). On opportunities and threats to conserve the phylogenetic diversity of Neotropical palms. Diversity and Distributions, 27(3), 512–523. https://doi.org/10.1111/ddi.13215

Examples

# Load example data
data("occurrences", package = "RuHere")
# Subset occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Load example of raster variables
data("worldclim", package = "RuHere")
# Unwrap Packed raster
r <- terra::unwrap(worldclim)
# Select thinned occurrences
occ_geo_moran <- flag_geo_moran(occ = occ, d = c(5, 10, 20, 30),
                                  env_layers = r)
# Selected distance
occ_geo_moran$distance
# Number of flagged and unflagged records
sum(occ_geo_moran$occ$thin_geo_flag) #Retained
sum(!occ_geo_moran$occ$thin_geo_flag) #Flagged for thinning out
# Results os the spatial autocorrelation analysis
occ_geo_moran$imoran

Description

This function identifies and flags occurrence records sourced from iNaturalist. It can flag all iNaturalist records or only those that do not have Research Grade status.

Usage

flag_inaturalist(occ, columns = "datasetName", research_grade = FALSE)

Arguments

Details

According to iNaturalist, Observations become Research Grade when:

• the iNaturalist community agrees on species-level ID or lower, i.e. when more than 2/3 of identifiers agree on a taxon;

• the community taxon and the observation taxon agree;

• or the community agrees on an ID between family and species and votes that the community taxon is as good as it can be.

Value

A data.frame that is the original occ data frame augmented with a new column named inaturalist_flag. Flagged records receive FALSE, while all other records receive TRUE.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Flag only iNaturalist records without Research Grade
occ_inat <- flag_inaturalist(occ = occurrences, research_grade = FALSE)
table(occ_inat$inaturalist_flag) # Number of records flagged (FALSE)
# Flag all iNaturalist records (including Research Grade)
occ_inat <- flag_inaturalist(occ = occurrences, research_grade = TRUE)
table(occ_inat$inaturalist_flag) # Number of records flagged (FALSE)

Description

Flags (validates) occurrence records based on known distribution data from the International Union for Conservation of Nature (IUCN) data. This function checks if an occurrence point for a given species falls within its documented distribution, allowing for user-defined buffers around the region. Records are flagged as valid (TRUE) if they fall inside the documented distribution (plus optional buffer) for the species in the IUCN dataset.

Usage

flag_iucn(
  data_dir,
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  origin = "native",
  presence = "all",
  buffer = 20,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named iucn_flag. This column is logical (TRUE/FALSE) indicating whether the record falls within the expected distribution (plus buffer) based on the IUCN data. Records for species not found in the IUCN data will have NA in the iucn_flag column.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Get only occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Set folder where distributional datasets were saved
# Here, just a sample provided in tha package
# You must run 'iucn_here()' beforehand to download the necessary data files
dataset_dir <- system.file("extdata/datasets", package = "RuHere")

# Flag records using IUCN specialist information
occ_iucn <- flag_iucn(data_dir = dataset_dir, occ = occ)

Description

A named character vector used to convert internal flag column names (produced by the package's flagging functions) into human-readable labels.

Usage

flag_names

Format

A named character vector of length 25. The names correspond to the original flag codes (e.g., "correct_country", "duplicated_flag", ".cen", "consensus_flag"), and the values are the cleaned, human-readable labels (e.g., "Wrong country", "Duplicated", "Country/Province centroid", "consensus").

Details

This object is used internally by functions such as mapview_here() and remove_flagged()to display more intuitive flag names to users.

Description

Flags (validates) occurrence records based on known distribution data from the World Checklist of Vascular Plants (WCVP) data. This function checks if an occurrence point for a given species falls within its documented distribution, allowing for user-defined buffers around the region. Records are flagged as valid (TRUE) if they fall inside the documented distribution (plus optional buffer) for the species in the WCVP dataset.

Usage

flag_wcvp(
  data_dir,
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  origin = "native",
  buffer = 20,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

Value

A data.frame that is the original occ data frame augmented with a new column named wcvp_flag. This column is logical (TRUE/FALSE) indicating whether the record falls within the expected distribution (plus buffer) based on the WCVP data. Records for species not found in the WCVP data will have NA in the wcvp_flag column.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Filter occurrences for Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Set folder where distributional datasets were saved
# Here, just a sample provided in the package
# You must run 'wcvp_here()' beforehand to download the necessary data files
dataset_dir <- system.file("extdata/datasets", package = "RuHere")

# Flag records using WCVP specialist information
occ_wcvp <- flag_wcvp(data_dir = dataset_dir, occ = occ)

Description

This function identifies occurrence records collected before or after user-specified years.

Usage

flag_year(
  occ,
  year_column = "year",
  lower_limit = NULL,
  upper_limit = NULL,
  flag_NA = FALSE
)

Arguments

Value

A data.frame identical to occ but with an additional column named year_flag. Records collected outside the year range specified are assigned FALSE.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Flag records collected before 1980 and after 2010
occ_year <- flag_year(occ = occurrences, lower_limit = 1980,
                      upper_limit = 2010)

Description

This function downloads the Flora e Funga do Brasil database, which is required for filtering occurrence records using specialists' information via the flag_florabr() function.

Usage

florabr_here(
  data_dir,
  data_version = "latest",
  solve_discrepancy = TRUE,
  overwrite = TRUE,
  remove_files = TRUE,
  verbose = TRUE
)

Arguments

Value

A message indicating that the data were successfully saved in the directory specified by data_dir.

Examples

# Define a directory to save the data
data_dir <- tempdir() # Here, a temporary directory

# Download the latest version of the Flora e Funga do Brasil database
florabr_here(data_dir = data_dir)

Description

Format and standardize column names and data types of an occurrence dataset

Usage

format_columns(
  occ,
  metadata,
  extract_binomial = TRUE,
  binomial_from = NULL,
  include_subspecies = FALSE,
  include_variety = FALSE,
  check_numeric = TRUE,
  numeric_columns = NULL,
  check_encoding = TRUE,
  data_source = NULL,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

Details

If a user-defined metadata data.frame is provided, it must include the following 21 columns: 'scientificName', 'collectionCode', 'catalogNumber', 'decimalLongitude', 'decimalLatitude', 'coordinateUncertaintyInMeters', 'elevation', 'country', 'stateProvince', 'municipality', 'locality', 'year', 'eventDate', 'recordedBy', 'identifiedBy', 'basisOfRecord', 'occurrenceRemarks', 'habitat', 'datasetName', 'datasetKey', and 'key'.

If check_encoding = TRUE, the function will inspect and, if necessary, fix the encoding of these columns: 'collectionCode', 'catalogNumber', 'country', 'stateProvince', municipality', 'locality', 'eventDate','recordedBy', 'identifiedBy', 'basisOfRecord', and 'datasetName'.

Value

A data.frame with standardized column names and data types according to the specified metadata.

Examples

# Example with GBIF
data("occ_gbif", package = "RuHere") #Import data example
gbif_standardized <- format_columns(occ_gbif, metadata = "gbif")
# Example with SpeciesLink
data("occ_splink", package = "RuHere") #Import data example
splink_standardized <- format_columns(occ_splink, metadata = "specieslink")
# Example with BIEN
data("occ_bien", package = "RuHere") #Import data example
bien_standardized <- format_columns(occ_bien, metadata = "bien")
# Example with idigbio
data("occ_idig", package = "RuHere") #Import data example
idig_standardized <- format_columns(occ_idig, metadata = "idigbio")

Description

Wrapper function to access and download occurrence records from the Botanical Information and Ecology Network (BIEN) database. It provides a unified interface to query BIEN data by species, genus, family, or by geographic or political boundaries.

Usage

get_bien(by = "species", cultivated = FALSE,
new.world = NULL, all.taxonomy = FALSE, native.status = FALSE,
natives.only = TRUE, observation.type = FALSE, political.boundaries = TRUE,
collection.info = TRUE, only.geovalid = TRUE, min.lat = NULL, max.lat = NULL,
min.long = NULL, max.long = NULL, species = NULL, genus = NULL,
country = NULL, country.code = NULL, state = NULL, county = NULL,
state.code = NULL, county.code = NULL, family = NULL, sf = NULL, dir,
filename = "bien_output", file.format = "csv", compress = FALSE,
save = FALSE, verbose = TRUE, ...)

Arguments

Value

A data.frame containing BIEN occurrence records that match the specified query. The structure and available columns depend on the chosen by value and the corresponding BIEN function.

Examples

# Example: download occurrence records for a single species
res_test <- get_bien(
    by = "species",
    species = "Paubrasilia echinata",
    cultivated = TRUE,
    native.status = TRUE,
    observation.type = TRUE,
    only.geovalid = TRUE
)

Description

This function creates a multidimensional grid in environmental space by splitting each environmental variable into n_bins equally sized intervals. It then assigns each occurrence record to an environmental block (bin combination) and identifies records that fall into the same block (i.e., records that are close to each other in environmental space).

The results can be visualized using the plot_env_bins() function.

Usage

get_env_bins(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  env_layers,
  n_bins = 5
)

Arguments

Value

A list with:

• data: a data frame including extracted environmental values, bin indices, and a unique block_id for each record.

• breaks: a named list of numeric vectors containing the break points for each variable (used by plot_env_bins()).

Examples

# Load example data
data("occurrences", package = "RuHere")
# Get only occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Load example of raster variables
data("worldclim", package = "RuHere")
# Unwrap Packed raster
r <- terra::unwrap(worldclim)
# Get bins
b <- get_env_bins(occ = occ, env_layers = r, n_bins = 5)

Description

Downloads species occurrence records from the iDigBio (Integrated Digitized Biocollections) database with flexible taxonomic and geographic filtering options.

Usage

get_idigbio(species = NULL, fields = "all", genus = NULL,
family = NULL, order = NULL, phylum = NULL, kingdom = NULL, country = NULL,
county = NULL, limit = NULL, offset = NULL, dir, filename = "idigbio_output",
save = FALSE, compress = FALSE, file.format = "csv", verbose = TRUE, ...)

Arguments

Value

A data.frame containing occurrence records from iDigBio with the requested fields.

Examples

## search for a single species
records_basic <- get_idigbio(species = "Arecaceae")

## search for multiple species
records_multiple <- get_idigbio(
  species = c("Araucaria angustifolia"),
  limit = 100)

## save results as a compressed RDS file
records_saved_rds <- get_idigbio(
  species = "Anacardiaceae",
  limit = 50,
  dir = tempdir(),
  filename = "anacardiaceae_records",
  save = TRUE,
  compress = TRUE,
  file.format = "rds")

Description

Retrieves occurrence data from the speciesLink network using user-defined filters. The function allows querying by taxonomic, geographic, and collection-related parameters.

Usage

get_specieslink(species = NULL, key = NULL, dir,
                       filename = "specieslink_output",save = FALSE,
                       basisOfRecord = NULL, family = NULL, institutionCode = NULL,
                       collectionID = NULL, catalogNumber = NULL,
                       kingdom = NULL, phylum = NULL, class = NULL,
                       order = NULL, genus = NULL, specificEpithet = NULL,
                       infraspecificEpithet = NULL, collectionCode = NULL,
                       identifiedBy = NULL, yearIdentified = NULL,
                       country = NULL, stateProvince = NULL, county = NULL,
                       typeStatus = NULL, recordedBy = NULL,
                       recordNumber = NULL, yearCollected = NULL,
                       locality = NULL, occurrenceRemarks = NULL,
                       barcode = NULL, bbox = NULL, landuse_1 = NULL,
                       landuse_year_1 = NULL, landuse_2 = NULL,
                       landuse_year_2 = NULL, phonetic = FALSE,
                       coordinates = NULL, scope = NULL, synonyms = NULL,
                       typus = FALSE, images = FALSE, redlist = NULL,
                       limit = NULL, file.format = "csv",
                       compress = FALSE, verbose = TRUE)

Arguments

set_specieslink_credentials("your_api_key")

Value

A data.frame containing the occurrence data fields returned by speciesLink.

Examples

## Not run: 
# Retrieve records for Arecaceae in São Paulo
res <- get_specieslink(
  family = "Arecaceae",
  country = "Brazil",
  stateProvince = "São Paulo",
  basisOfRecord = "PreservedSpecimen",
  limit = 10
)

# Save results as compressed CSV
get_specieslink(
  family = "Arecaceae",
  country = "Brazil",
  save = TRUE,
  dir = tempdir(),
  filename = "arecaceae_sp",
  compress = TRUE
)

## End(Not run)

Description

This function creates a static map of occurrence records using ggplot2, highlighting which points were flagged by data-validation functions. This visualization helps users quickly inspect spatial patterns of flagged and unflagged records and diagnose potential data-quality issues.

The function can also be used to plot the heatmap generated by the spatial_kde() function.

Usage

ggmap_here(
  occ,
  species = NULL,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  flags = "all",
  additional_flags = NULL,
  names_additional_flags = NULL,
  col_additional_flags = NULL,
  show_no_flagged = TRUE,
  col_points = NULL,
  size_points = 1,
  heatmap = NULL,
  low_color = "blue",
  mid_color = "yellow",
  high_color = "red",
  midpoint = 0.5,
  alpha_heatmap = 0.5,
  continent = NULL,
  continent_fill = "gray70",
  continent_linewidth = 0.3,
  continent_border = "white",
  ocean_fill = "aliceblue",
  extension = NULL,
  facet_wrap = FALSE,
  theme_plot = ggplot2::theme_minimal(),
  ...
)

Arguments

Details

This function expects an occurrence dataset that has already been processed by one or more flagging routines from RuHere or related packages such as CoordinateCleaner. Any logical column in occ can be used as a flag.

The following built-in flag names are recognized: From RuHere: correct_country, correct_state, cultivated, florabr, faunabr, wcvp, iucn, bien, duplicated, thin_geo, thin_env, consensus

From CoordinateCleaner: .val, .equ, .zer, .cap, .cen, .sea, .urb, .otl, .gbf, .inst, .aohi

Users may also supply additional logical columns using additional_flags, optionally providing alternative display names (names_additional_flags) and colors (col_additional_flags).

If continent is not provided, the background map is a simplified world polygon included with the package (a modified version of rnaturalearthdata::map_units110). To inspect this object, run:

terra::unwrap(getExportedValue("RuHere", "world"))

When facet_wrap = TRUE, each flag is plotted in a separate panel, allowing direct comparison among different types of data issues.

Value

An ggplot object displaying flagged and optionally unflagged occurrence records.

Examples

# Load example data
data("occ_flagged", package = "RuHere")
# Visualize all flags with ggplot
ggmap_here(occ = occ_flagged)
# Visualize each flag in a separate panel
ggmap_here(occ = occ_flagged, facet_wrap = TRUE)

Description

This function is the dedicated plotting tool for outputs from richness_here(). It automatically handles single-layer rasters (e.g., species richness) and multi-layer rasters (e.g., multiple biological traits or flags), creating a standardized visual using ggplot2.

Usage

ggrid_here(
  raster,
  low_color = "blue",
  mid_color = "yellow",
  high_color = "red",
  alpha = 0.8,
  continent = NULL,
  continent_fill = "gray70",
  continent_linewidth = 0.3,
  continent_border = "white",
  ocean_fill = "aliceblue",
  extension = NULL,
  theme_plot = ggplot2::theme_minimal(),
  ...
)

Arguments

Value

A ggplot object.

Examples

# Load example data
data("occ_flagged", package = "RuHere")

# Simple richness map
r_records <- richness_here(occ_flagged, summary = "records", res = 2)
ggrid_here(r_records)

# Density of specific flags
# Let's see where 'florabr' flags are concentrated
r_flags <- richness_here(occ_flagged, summary = "records",
                         field = "florabr_flag",
                         field_name = "Records flagged by florabr",
                         fun = function(x, ...) sum(!x, na.rm = TRUE),
                         res = 2)
ggrid_here(r_flags)

Description

This function imports a dataset downloaded from GBIF using a request key generated by the request_gbif() function. It optionally allows saving the imported occurrences to disk in CSV or GZIP format.

Usage

import_gbif(
  request_key,
  write_file = FALSE,
  output_dir = NULL,
  file.format = "gz",
  select_columns = TRUE,
  columns_to_import = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

A data frame containing the GBIF occurrence records. If write_file = TRUE, the function also saves the dataset to disk in the specified format.

Note

This function requires an active internet connection.

Examples

## Not run: 
# Prepare data to request GBIF download
gbif_prepared <- prepare_gbif_download(species = "Araucaria angustifolia")
# Submit a request to download occurrences
gbif_requested <- request_gbif(gbif_info = gbif_prepared)
# Check progress
rgbif::occ_download_wait(gbif_requested)
# After succeeded, import data
occ_gbif <- import_gbif(request_key = gbif_requested)

## End(Not run)

Description

Estimates expected species richness, sample coverage (inventory completeness), and coverage deficit for spatial units based on the framework proposed by Chao & Jost (2012).

Usage

inventory_completeness(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  raster_base,
  minimum_species = 3,
  maximum_expected = "equal_obs",
  remove_NA = TRUE,
  fill_NA = TRUE,
  return = c("completeness", "deficit")
)

Arguments

Details

The function calculates metrics based on the frequency of rare species (singletons and doubletons) within each cell of the raster_base.

• n: Total number of records.

• s_obs: Observed species richness (number of sampled species).

• s_exp: Estimated asymptotic species richness based on the Chao1 estimator.

• singletons: Species represented by exactly one record.

• doubletons: Species represented by exactly two records.

• completeness: Sample coverage, representing the proportion of the total individuals in occ that belong to the species in the sample.

• deficit: Coverage deficit, which is the probability that the next sampled individual represents a previously unsampled species (1 - completeness)

Value

A SpatRaster object containing the spatialized metrics defined in return.

References

Chao A, Jost L (2012) Coverage-based rarefaction and extrapolation: standardizing samples by completeness rather than size. Ecology 93:2533–2547. https://doi.org/10.1890/11-1952.1

Examples

# Load example of raster variables
data("worldclim", package = "RuHere")
r <- terra::unwrap(worldclim)
# Aggregate cells
r_base <- terra::aggregate(r, 5)

# Import data set of amphibian communities from the Atlantic Forest
data("atlantic_amphibians", package = "RuHere")

# Run analysis
res <- inventory_completeness(occ = atlantic_amphibians,  raster_base = r_base)
terra::plot(res)

Description

This function downloads information on species distributions from the IUCN Red List, required for filtering occurrence records using specialists' information via the flag_iucn() function.

Usage

iucn_here(
  data_dir,
  species,
  synonyms = NULL,
  iucn_credential = NULL,
  overwrite = FALSE,
  progress_bar = FALSE,
  verbose = FALSE,
  return_data = TRUE
)

Arguments

Details

This function uses the rredlist::rl_species() function to retrieve distribution data from the IUCN Red List. The data include information at the country and regional levels, following the World Geographical Scheme for Recording Plant Distributions (WGSRPD) — but applicable to both plants and animals.

Unfortunately, the range polygons available at https://www.iucnredlist.org/resources/spatial-data-download cannot be accessed automatically.

Because taxonomic information in IUCN may be outdated, you can optionally provide a table of synonyms to broaden the search. The synonyms data.frame should have the accepted species in the first column and their synonyms in the second. See RuHere::synonys for an example.

The function also downloads the WGSRPD map used to represent distribution regions.

Value

A message indicating that the data were successfully saved in the directory specified by data_dir. If return_data = TRUE, the function additionally returns a data frame containing the species distribution information retrieved from IUCN.

Examples

## Not run: 
# Define a directory to save the data
data_dir <- tempdir() # Here, a temporary directory

# Download species distribution information from IUCN
iucn_here(data_dir = data_dir, species = "Araucaria angustifolia")

## End(Not run)

Description

This function creates an interactive map of occurrence records using mapview, visually highlighting flags. This tool helps users explore which records were flagged by one or more validation functions and inspect them directly on the map.

Usage

map_here(
  occ,
  species = NULL,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  flags = "all",
  additional_flags = NULL,
  names_additional_flags = NULL,
  col_additional_flags = NULL,
  show_no_flagged = TRUE,
  cex = 6,
  lwd = 2,
  col_points = NULL,
  label = NULL,
  ...
)

Arguments

Details

The following flags are available: correct_country, correct_state, cultivated, fossil, inaturalist, faunabr, florabr, wcvp, iucn, duplicated, thin_geo, thin_env, .val, .equ, .zer, .cap, .cen, .sea, .urb, .otl, .gbf, .inst, and .aohi.

These flags are typically generated by functions in the RuHere or CoordinateCleanerworkflow to identify potential data-quality issues in occurrence records.

Users may also supply additional logical columns using additional_flags, optionally providing alternative display names (names_additional_flags) and colors (col_additional_flags).

Value

An interactive mapview object displaying flagged and optionally unflagged occurrence records.

Examples

# Load example data
data("occ_flagged", package = "RuHere")
# Visualize flags interactively
map_here(occ = occ_flagged, label = "record_id")

Description

This function computes Moran's I autocorrelation coefficient for a numeric vector x using a matrix of weights. The method follows Gittleman and Kot (1990). This function is an implementation of ape::Moran.I(), but rewritten in C++ to be substantially faster and more memory-efficient.

Usage

moranfast(
  x,
  weight,
  na_rm = TRUE,
  scaled = FALSE,
  alternative = c("two.sided")
)

Arguments

Value

A list with the following components:

• observed – The observed Moran's I.

• expected – The expected value of Moran's I under the null hypothesis.

• sd – The standard deviation of Moran's I under the null hypothesis.

• p.value – The p-value of the test based on the chosen alternative.

References

Gittleman, J. L., & Kot, M. (1990). Adaptation: statistics and a null model for estimating phylogenetic effects. Systematic Zoology, 39(3), 227–241.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Filter occurrences of Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Load example of raster variables
data("worldclim", package = "RuHere")
# Unwrap Packed raster
r <- terra::unwrap(worldclim)
# Extract values for bio_1
bio_1 <- terra::extract(r$bio_1,
                        occ[, c("decimalLongitude", "decimalLatitude")],
                        ID = FALSE, xy = TRUE)
#Remove NAs
bio_1 <- na.omit(bio_1)
# Convert values to numeric
v <- as.numeric(bio_1$bio_1)
# Compute geographic distance matrix
d <- fields::rdist.earth(x1 = as.matrix(bio_1[, c("x", "y")]), miles = FALSE)
# Inverse-distance weights
d <- 1/d
# Fill diagonal with 0
diag(d) <- 0
# Remove finite values
d[is.infinite(d)] <- 0
# Compute Moran's I
m <- moranfast(x = v, weight = d, scale = TRUE)
# Print results
m

Description

A cleaned dataset of occurrence records for Yellow Trumpet Tree (Handroanthus serratifolius) retrieved from the BIEN database. The raw data were downloaded using get_bien()

The dataset was subsequently processed with the package’s internal flagging workflow (flag_duplicates() and remove_flagged()) to remove duplicated records.

Usage

occ_bien

Format

A data frame containing spatial coordinates, taxonomic information, and metadata returned by BIEN, after cleaning. Columns include (but may not be limited to):

• scrubbed_species_binomial: Cleaned species name

• longitude, latitude: Geographic coordinates

• country, state_province, and other political boundary fields

See Also

get_bien()

Examples

# View dataset
head(occ_bien)

# Number of records
nrow(occ_bien)

Description

A dataset containing the occurrence records of Araucaria angustifolia after applying several of the package’s flagging and data-quality assessment functions.

Usage

occ_flagged

Format

A data frame where each row corresponds to a georeferenced occurrence of A. angustifolia.

See Also

occurrences, standardize_countries(), standardize_states(), flag_florabr(), flag_wcvp(), flag_iucn(), flag_cultivated(), flag_inaturalist(), flag_duplicates(), mapview_here()

Examples

# First rows
head(occ_flagged)

# Count flagged vs. unflagged records
table(occ_flagged$correct_country)

Description

A cleaned dataset of occurrence records for Araucaria angustifolia (Parana pine) retrieved from GBIF.

Records were downloaded using the package’s GBIF workflow (prepare_gbif_download(), request_gbif(), import_gbif()), and then cleaned using the internal flagging workflow (duplicate detection and removal).

Usage

occ_gbif

Format

A data frame containing georeferenced GBIF occurrence records for A. angustifolia after all cleaning steps.

See Also

prepare_gbif_download(), request_gbif(), import_gbif(), flag_duplicates(), remove_flagged()

Examples

# Preview dataset
head(occ_gbif)

# Number of cleaned records
nrow(occ_gbif)

Description

A cleaned dataset of occurrence records for azure jay (Cyanocorax caeruleus) retrieved from the iDigBio using get_idigbio().

Records were cleaned using the package's internal duplicate-flagging workflow.

Usage

occ_idig

Format

A data frame containing georeferenced iDigBio occurrence records for C. caeruleus after all cleaning steps.

See Also

get_idigbio(), flag_duplicates(), remove_flagged()

Examples

# First rows
head(occ_idig)

# Number of cleaned records
nrow(occ_idig)

Description

A cleaned dataset of occurrence records for azure jay (Cyanocorax caeruleus) retrieved from the SpeciesLink using get_specieslink().

Records were cleaned using the package's internal duplicate-flagging workflow.

Usage

occ_splink

Format

A data frame containing georeferenced SpeciesLink occurrence records for C. caeruleus after all cleaning steps.

See Also

get_specieslink(), flag_duplicates(), remove_flagged()

Examples

# First rows
head(occ_splink)

# Number of cleaned records
nrow(occ_splink)

Description

A harmonized, multi-source occurrence dataset containing cleaned georeferenced records for three species:

• Araucaria angustifolia (Parana pine)

• Cyanocorax caeruleus (Azure jay)

• Handroanthus serratifolius (Yellow trumpet tree)

Records were retrieved from GBIF, speciesLink, BIEN, and iDigBio, standardized through the package workflow, merged, and cleaned to remove duplicates.

Usage

occurrences

Format

A data frame where each row represents a georeferenced occurrence record for one of the three species.

Columns correspond to the standardized output of format_columns(), including:

• species: Cleaned binomial species name

• decimalLongitude, decimalLatitude: Coordinates

• year: Year of collection/observation

• Various taxonomic, temporal, locality, and metadata fields

• Source identifiers added by format_columns() (e.g., data_source)

See Also

format_columns(), bind_here(), flag_duplicates(), remove_flagged()

Examples

# Show the first rows
head(occurrences)

# Number of occurrences per species
table(occurrences$species)

Description

Visualize the output of get_env_bins() by plotting environmental blocks (bins) along two selected environmental variables. Each block is shown as a colored rectangle, and points falling inside the same rectangle share the same block_id.

Usage

plot_env_bins(
  env_bins,
  x_var,
  y_var,
  alpha_blocks = 0.3,
  color_points = "black",
  size_points = 2,
  alpha_points = 0.5,
  stroke_points = 1,
  xlab = NULL,
  ylab = NULL,
  theme_plot = ggplot2::theme_minimal()
)

Arguments

Value

A ggplot object showing the environmental blocks (colored rectangles) and the occurrence records in the selected environmental space.

Examples

# Load example data
data("occurrences", package = "RuHere")
# Get only occurrences from Araucaria
occ <- occurrences[occurrences$species == "Araucaria angustifolia", ]
# Load example of raster variables
data("worldclim", package = "RuHere")
# Unwrap Packed raster
r <- terra::unwrap(worldclim)
# Get bins
b <- get_env_bins(occ = occ, env_layers = r, n_bins = 10)
# Plot
plot_env_bins(b, x_var = "bio_1", y_var = "bio_12",
              xlab = "Temperature", ylab = "Precipitation")

Description

Prepare data to request GBIF download

Usage

prepare_gbif_download(
  species,
  rank = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  strict = FALSE,
  progress_bar = FALSE,
  ...
)

Arguments

Value

A data.frame with species information, including the number of occurrences and other related details.

Note

This function requires an active internet connection to access GBIF data.

Examples

gbif_prepared <- prepare_gbif_download(species = "Araucaria angustifolia")

Description

A named list of data frames containing metadata templates for the main biodiversity data providers supported by the package (GBIF, SpeciesLink, iDigBio, and BIEN).

These templates are used internally by format_columns() to harmonize columns.

Usage

prepared_metadata

Format

A named list of four data frames:

• ⁠$gbif⁠ — template for GBIF dataset.

• ⁠$specieslink⁠ — template for SpeciesLink dataset.

• ⁠$idigbio⁠ — template for iDigBio dataset.

• ⁠$bien⁠ — template for BIEN dataset.

Details

Each element of prepared_metadata is a single-row data frame where:

• column names correspond to the package’s standardized output fields

• values in the row represent the original column names used by each data provider

These mappings allow format_columns() to:

• rename fields (e.g., scientificname → scientificName)

• identify which variables are missing or provider-specific

• coerce classes consistently (e.g., dates, coordinates)

• ensure compatibility when combining datasets from different sources

See Also

format_columns()

Examples

# View template for GBIF records
prepared_metadata$gbif

Description

A subset of Atlantic mammals records obtained from the atlanticr::atlantic_mammals dataset, containing occurrences of Puma concolor.

This dataset is provided as an example to illustrate how to create user-defined metadata templates for occurrence records from external sources using the package’s create_metadata() function.

Usage

puma_atlanticr

Format

A data frame where each row represents a single occurrence record of Puma concolor. Columns include species name, location, and other relevant metadata fields provided by the atlantic_mammals dataset.

See Also

create_metadata(), format_columns()

Examples

# Preview first rows
head(puma_atlanticr)

# Count occurrences per year
table(puma_atlanticr$year)

Description

These functions move one column to a new position in a data frame, either immediately after or before another column, while preserving the order of all remaining columns. They are lightweight base-R utilities equivalent to dplyr::relocate(), but without external dependencies.

Usage

relocate_after(df, col, after)

relocate_before(df, col, before)

Arguments

Value

A data.frame with columns reordered.

Description

This function removes accents and replaces special characters from strings, returning a plain-text version suitable for data cleaning or standardization.

Usage

remove_accent(s)

Arguments

Value

A vector string without accents or special characters.

Examples

remove_accent(c("Colômbia", "São Paulo"))

Description

This function removes occurrence records flagged as invalid by one or more flagging functions. Additional manual control is available to force keeping or removing specific records, regardless of their flag values.

Usage

remove_flagged(
  occ,
  flags = "all",
  additional_flags = NULL,
  force_keep = NULL,
  force_remove = NULL,
  remove_NA = FALSE,
  column_id = "record_id",
  save_flagged = FALSE,
  output_dir = NULL,
  overwrite = FALSE,
  output_format = ".gz"
)

Arguments

Details

The following flags are available: correct_country, correct_state, cultivated, fossil, inaturalist, faunabr, florabr, wcvp, iucn, duplicated, thin_geo, thin_env, .val, .equ, .zer, .cap, .cen, .sea, .urb, .otl, .gbf, .inst, and .aohi.

Value

A data.frame containing only the valid (kept) records according to the flags and additional criteria.

Examples

# Load example data
data("occ_flagged", package = "RuHere")

# Remove all flagged records
occ_valid <- remove_flagged(occ = occ_flagged)

# Remove flagged records and force removal of some unflagged records
to_remove <- c("gbif_5987", "specieslink_2301", "gbif_18761")
occ_valid2 <- remove_flagged(occ = occ_flagged,
                             force_remove = to_remove)

# Remove flagged records but keep some flagged ones
to_keep <- c("gbif_14501", "gbif_12002", "gbif_5168")
occ_valid3 <- remove_flagged(occ = occ_flagged,
                            force_keep = to_keep)

Description

This function identifies and removes invalid geographic coordinates, including non-numeric values, NA or empty values, and coordinates outside the valid range for Earth (latitude > 90 or < -90, and longitude > 180 or < -180).

Usage

remove_invalid_coordinates(
  occ,
  long = "decimalLongitude",
  lat = "decimalLatitude",
  return_invalid = TRUE,
  save_invalid = FALSE,
  output_dir = NULL,
  overwrite = FALSE,
  output_format = ".gz",
  verbose = FALSE
)

Arguments

Value

If return_invalid = FALSE, returns the occurrence dataset containing only valid coordinates. If return_invalid = TRUE (default), returns a list with two elements:

• valid – the dataset with valid coordinates.

• invalid – the dataset with invalid coordinates removed.

Examples

# Create fake data example
occ <- data.frame("species" = "spp",
                  "decimalLongitude" = c(10, -190, 20, 50, NA),
                  "decimalLatitude" = c(20, 20, 240, 50, NA))
# Split valid and invalid coordinates
occ_valid <- remove_invalid_coordinates(occ)

Description

Submit a request to download occurrence data from GBIF.

Usage

request_gbif(gbif_info, hasCoordinate = TRUE,
                    hasGeospatialIssue = FALSE, format = "DWCA",
                    gbif_user = NULL, gbif_pwd = NULL, gbif_email = NULL,
                    additional_predicates = NULL)

Arguments

Details

You can use the object returned by this function to check the download request progress with rgbif::occ_download_wait()

Value

A download request key returned by the GBIF API, which can be used to monitor or retrieve the download.

Note

This function requires an active internet connection and valid GBIF credentials.

Examples

## Not run: 
# Prepare data to request GBIF download
gbif_prepared <- prepare_gbif_download(species = "Araucaria angustifolia")
# Submit a request to download occurrences
gbif_requested <- request_gbif(gbif_info = gbif_prepared)
# Check progress
rgbif::occ_download_wait(gbif_requested)

## End(Not run)

Description

This function generates spatial grids (rasters) of species richness, record density, or summarized biological traits from occurrence data. It supports custom resolutions, masking, and automatic coordinate reprojection to match reference rasters.

Usage

richness_here(
  occ,
  species = "species",
  long = "decimalLongitude",
  lat = "decimalLatitude",
  records = "record_id",
  raster_base = NULL,
  res = NULL,
  crs = "epsg:4326",
  mask = NULL,
  summary = "records",
  field = NULL,
  field_name = NULL,
  fun = mean,
  verbose = TRUE
)

Arguments