In mlammens/occUncertain: Functions For Addressing Occurence Point Uncertainty When Calculating Spatial Metrics

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(occUncertain)
data(Leopardus_wiedii_gbif)
# load("../data/Leopardus_wiedii_gbif.rda")
Leopardus_wiedii_gbif <- Leopardus_wiedii_gbif

---

---

1. Introduction

This vignette goes through the use of uncertainty measures of species occurrence records in "occUncertainty: An R package for addressing uncertainty of species occurrence in species distribution". Here we demonstrate how occUncertain can be used to transform uncertainty measures from meters to decimal degrees. Perform iterations to assess occurrence records variability in the quantification of the extent area that encompass the inferred or projected sites of occurrence of a species, and the area within the extent polygon they occupy.

Input file

To demonstrate the use of the package occUncertain we used a set of 229 verified, georeferenced occurrence records for the margay (Leopardus weidii), a small wild cat native to Central and South America. These occurrences data set are from the Global Biodiversity Information Facility (GBIF) and are included as part of the occUncertain package.

The data set includes the following four columns:

1. Latitude in decimal degrees
2. Longitude in decimal degrees
3. Coordinate uncertainty in meters.
4. Name of taxa

#Leopardus_wiedii_gbif <- dplyr::select(Leopardus_wiedii_gbif, latitude, longitude, coordinateUncertaintyInMeters, species)
knitr::kable(head(Leopardus_wiedii_gbif))

2. meters_to_decdeg function

The function meters_to_decdeg transforms uncertainty from meters into decimal degrees for each occurrence point.

**Note 1: Is important to consider the fact that as one moves away from the equator towards a pole, one degree of longitude is multiplied by the cosine of the latitude, decreasing the distance, approaching zero at the pole.

The function allows interpretation of NA uncertainty values through the conditional parameter na_action.

The options are:

1. NA as Zero, assigns zero to all NA values,

Unc_Meters_to_DecDeg_NAZero <-
  meters_to_decdeg(
    occs_df,
    lat_col = "latitude",
    lon_col = "longitude",
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as 0"
    )

L_wiedii_uncertainty_naZero <-
  meters_to_decdeg(occs_df = Leopardus_wiedii_gbif,
    lat_col = "latitude",
    lon_col = "longitude",
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as 0")

knitr::kable(head(L_wiedii_uncertainty_naZero))

2. NA as NA, leaves NA values as NA, and

Unc_Meters_to_DecDeg_NANA <-
  meters_to_decdeg(
    occs_df,
    lat_col = "latitude",
    lon_col = "longitude",
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as NA"
    )

L_wiedii_uncertainty_naNA <-
  meters_to_decdeg(occs_df = Leopardus_wiedii_gbif,
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as NA")

knitr::kable(head(L_wiedii_uncertainty_naNA))

3. NA as Mean, assigns the uncertainty mean value to NA latitude and longitude values.

Unc_Meters_to_DecDeg_NAMean <-
  meters_to_decdeg(
    occs_df,
    lat_col = "latitude",
    lon_col = "longitude",
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as mean"
    )

L_wiedii_uncertainty_naMean <-
  meters_to_decdeg(occs_df = Leopardus_wiedii_gbif,
    distance = "coordinateUncertaintyInMeters",
    na_action = "NA as mean")

knitr::kable(head(L_wiedii_uncertainty_naMean))

3. generate_occ_uncertain function

The function generate_occ_uncertain produces a random latitude and longitude coordinates data frame, accounting latitude and longitude uncertainty values in decimal degrees. The function requires to have an input data.frame with occurrences and uncertainty in decimal degrees and the species name:

1. Latitude.
2. Longitude.
3. Latitude uncertainty.
4. Longitude uncertainty.
5. Name of Taxa.

This function generates random latitude and longitude coordinates with decimal degrees uncertainty values.

L_wiedii_random <-
  generate_occ_uncertain(
    occ_df,
    lat_col = "latitude",
    lon_col = "longitude",
    lat_uncertainty = "lat_uncertainty",
    lon_uncertainty = "lon_uncertainty",
    taxa_col = "species"
  )

1. NA as zero, uses the latitude and longitude uncertainty values as Zero ,

L_wiedii_uncertainty_naZero <-
  cbind(Leopardus_wiedii_gbif, L_wiedii_uncertainty_naZero)

L_wiedii_generate_Zero <-
  generate_occ_uncertain(
    L_wiedii_uncertainty_naZero,
    lat_col = "latitude",
    lon_col = "longitude",
    lat_uncertainty = "lat_uncertainty",
    lon_uncertainty = "lon_uncertainty",
    taxa_col = "species"
  )

knitr::kable(head(L_wiedii_generate_Zero))

2. NA as NA, random lat and lon after removing !NA lat and lon uncertainty

L_wiedii_uncertainty_naNA <-
  cbind(Leopardus_wiedii_gbif, L_wiedii_uncertainty_naNA)

L_wiedii_uncertainty_naNA <-
  dplyr::select(
    L_wiedii_uncertainty_naNA,
    latitude,
    longitude,
    lon_uncertainty,
    lat_uncertainty,
    species
  )
#filter !is.NA lat and lon uncertinaty 
L_wiedii_uncertainty_naNA <- dplyr::filter(L_wiedii_uncertainty_naNA, !is.na(lon_uncertainty))

L_wiedii_generate_NA <-
  generate_occ_uncertain(
    L_wiedii_uncertainty_naNA,
    lat_col = "latitude",
    lon_col = "longitude",
    lat_uncertainty = "lat_uncertainty",
    lon_uncertainty = "lon_uncertainty",
    taxa_col = "species"
  )

knitr::kable(head(L_wiedii_generate_NA))

3. NA as Mean

#combine observed and prodataset with radian 
L_wiedii_uncertainty_naMean <-
  cbind(Leopardus_wiedii_gbif, L_wiedii_uncertainty_naMean)

L_wiedii_uncertainty_naMean <-
  dplyr::select(
    L_wiedii_uncertainty_naMean,
    latitude,
    longitude,
    lon_uncertainty,
    lat_uncertainty,
    species
  )

knitr::kable(head(L_wiedii_uncertainty_naMean))

L_wiedii_generate_Mean <-
  generate_occ_uncertain(
    L_wiedii_uncertainty_naMean,
    lat_col = "latitude",
    lon_col = "longitude",
    lat_uncertainty = "lat_uncertainty",
    lon_uncertainty = "lon_uncertainty",
    taxa_col = "species"
  )

knitr::kable(head(L_wiedii_generate_Mean))

Lets visualize

#You can add easily get a map of countries using the package [rnaturalearth](https://CRAN.R-project.org/package=rnaturalearth):
land <- 
  rnaturalearth::ne_countries(scale = 50, returnclass = "sp")

library(ggplot2)
data(land)
map <- ggplot2::map_data("world")

ggplot2::theme_set(theme_bw())

#observed data
ggplot2::ggplot(
  data = Leopardus_wiedii_gbif,
  aes(x = longitude, y = latitude,
  colour = "Observed occ"),
  size = 0.1,
  fill = NA,
  shape = 1,
  alpha = 0.2
) +


  geom_polygon(
    data = map,
    aes(x = long, y = lat, group = group),
    fill = NA,
    colour = "grey"
  ) +
  coord_fixed(xlim = c(-85,-70), ylim = c(-5, 10)) +

  #different NA_option results
  geom_point() +
   geom_point(
    data = L_wiedii_generate_Mean,
    aes(x = lon_random, y = lat_random,
    colour = "NA as Mean"),
    #size = 0.01,
    fill = NA,
    shape = 1,
    alpha = 0.5
  ) +
  geom_point(
    data = L_wiedii_generate_Zero,
    aes(x = lon_random, y = lat_random,
    colour = "NA as Zero"),
    shape = 1,
        #size = 1,
    fill = NA,
    alpha = 0.5
  ) +
  geom_point(
    data = L_wiedii_generate_NA,
    aes(x = lon_random, y = lat_random,
    colour = "NA as NA"),
    #size = 0.01,
    fill = NA,
    shape = 1,
    alpha = 0.5
  ) +
  scale_colour_manual(
    "",
    values = c(
      "Observed occ" = "yellow",
      "NA as Mean" = "green",
      "NA as Zero" = "blue",
      "NA as NA" = "red"
    )
  ) +

  labs(title = "L. wiedii observed and generated occurrences", subtitle = "Generated occurrences with meters to decimal degree uncertainty NA_action parameters "
    )

"NA as Zero generated occurrences" "NA as NA generated occurrences" "NA as mean generated occurrences"

4. random_geo_range function

The function random_geo_range accounts for uncertainty and uses a for loop to randomize occurrence points. Produces a data frame with values for extent of occurrence (EOO)and area of occupancy (AOO), with ConR package functions (compute.EOO and compute.AOO). The function requires an input data frame with three different columns in order:

1. lat_random: Latitude in decimal degrees
2. lon_random: Longitude in decimal degrees
3. Name of taxa

The Extent of Occurrence is the area contained within the shortest continuous imaginary boundary which can be drawn to encompass all the known, inferred or projected sites of present occurrence of a taxon, excluding cases of vagrancy. (IUCN 2012)

The function logical argument exclude.area, crops areas not suitable for the species. The excluded areas are defined by a shapefile with the argument country_map. Note that it is mandatory to provide a shapefile for country_map if exclude.area is TRUE.

The area occupied by a taxon within its extent of occurrence; known as Area of occupancy (AOO), reflects the fact that a taxon will not usually occur throughout the area of its extent of occurrence. Metric calculated as the area of all known or predicted cells for the species, without unsuitable or unoccupied habitats. The resolution will be 2x2km as required by IUCN.

For this example, the function random_geo_range uses n_length = 10, to randomly generate latitudes and longitudes occurrences with the function generate_occ_uncertain, using mean uncertainty for NA values obtained with meters_to_decdeg.

L_weidii_random_geo_range <- random_geo_range(
  n_length = 10,
  occs_df,
  lat_col = "latitude",
  lon_col = "longitude",
  lon_uncertainty = "lon_uncertainty",
  lat_uncertainty = "lat_uncertainty",
  taxa_col = "species"
)

**Note: The rest of this vignette will use the data frame produced with conditional na_action = "NA as mean" in the meters_to_decdeg function

L_weidii_random_geo_range <- random_geo_range(
  n_length = 10,
  occs_df = L_wiedii_uncertainty_naMean,
  lat_col = "latitude",
  lon_col = "longitude",
  lon_uncertainty = "lon_uncertainty",
  lat_uncertainty = "lat_uncertainty",
  taxa_col = "species"
)

knitr::kable(head(L_weidii_random_geo_range))

## 5 Computing from observed dataset with ConR 
library(ConR)
data(land)
L_weidii_EOO <-
  EOO.computing(
    Leopardus_wiedii_random,
    exclude.area = T,
    country_map = land,
    write_results = F
  )

L_weidii_AOO <- AOO.computing(Leopardus_wiedii_random)

## 6.4 Runing IUCN.eval function## 6.4 Runing IUCN.eval function
L_weidii_IUCN.eval <- IUCN.eval(Leopardus_wiedii_random,
  country_map = land,
  write_results = F)

mlammens/occUncertain documentation built on May 6, 2024, 11:19 p.m.