Skip to contents

Visualize refined records on interactive maps

Source: R/map_records.R
map_records.Rd

Renders refined occurrence records on interactive maps for spatial exploration and quality assessment. Records are deduplicated with geohashes and color-coded by their native status.

Usage

map_records(
  native_detected_coord = NA,
  species = "all",
  precision = 3,
  cex = 3
)

Arguments

native_detected_coord

A nativeDetected object returned by detect_native_coord(), containing records with validated coordinates.

species

Either "all" (the default) to map every species, or a single species name to restrict the map to that species. The name is matched exactly against the Accepted_name column, so "Saxifraga hirculus" maps the records of that species. Records whose native_status is "unknown" are excluded either way.

precision

Positive integer controlling the spatial resolution of geohash-based deduplication. Higher values produce finer-grained cells. For reference, precision values of 4, 3, and 2 represent approximately 20 km, 156 km, and 1,250 km resolution, respectively. Defaults to 3.

cex

Numeric value controlling the point size of occurrence records on the map. Defaults to 3.

Value

A mapview interactive map object displaying refined occurrence records color-coded by native_status. The map contains a native-status legend, three switchable basemap layers, and clickable popups with record metadata.

Details

The function works in four steps:

  • Record selection: Reads the classified records from detect_native_coord(), keeping those whose native_status is not "unknown", optionally restricted to a single species named by species.

  • Geohash deduplication: Encodes coordinates at the requested precision and retains one representative record per species, geohash cell, and native status.

  • Interactive visualization: Builds a multi-layer map with records color-coded by native_status.

  • Basemap selection: Provides OpenStreetMap, Esri World Imagery, and Stadia Stamen Watercolor basemaps.

Record selection

Both the classification and the coordinates are read from native_detected_coord, which carries every column of the input records. Records with native_status = "unknown" are excluded. When species names a species rather than "all", the selection is narrowed further to the records whose Accepted_name equals that name; the comparison is exact, so the spelling must match the column value. A name that selects nothing is an error, because an empty map is read as "this species has no native records". Records with missing longitude or latitude are excluded as a guard; detect_native_coord() only classifies records with validated coordinates, so none are expected, and inputs that carry missing coordinates (such as the output of detect_native_country()) are rejected outright.

Geohash deduplication

Geohash encoding converts latitude-longitude pairs into alphanumeric strings representing grid cells of varying sizes. The function groups records by species name, geohash cell, and native status, then retains the first record from each group. This reduces visual overplotting while preserving the broad spatial distribution pattern, which is useful for densely sampled regions.

Map layers and interactivity

The generated map includes:

  • A color-coded legend based on native_status categories.

  • Popups displaying record attributes such as GBIF ID, GBIF issues, and taxon name.

  • Toggleable basemap layers for different visualization contexts.

  • Point transparency set to alpha.regions = 0.6 to improve density perception.

See also

detect_native_coord() for the object consumed by this function; gh_encode() for geohash encoding and mapView() for interactive map construction.

Examples

if (FALSE) { # interactive() && exists("native_detected_coord")
# Every species in the classification
map_records(
  native_detected_coord = native_detected_coord,
  precision = 3,
  cex = 3
)

# A single species
map_records(
  native_detected_coord = native_detected_coord,
  species = "Saxifraga hirculus"
)
}