Added get_pam_areas, for finding areas when a PAM is input

Author: kmartinet

NAMESPACE

@@ -9,6 +9,7 @@ export(estimate_DR)
 export(estimate_MS)
 export(find_areas)
 export(find_land)
+export(find_pam_areas)
 export(get_island_areas)
 export(get_presence_absence)
 export(get_richness)

R/find_areas.R

@@ -21,7 +21,7 @@
 #'
 #' @param occs The dataframe that is returned by `ssarp::find_land()`. If using
 #' a custom occurrence record dataframe, ensure that it has the following
-#' columns: "acceptedScientificName", "genericName", "specificEpithet",
+#' columns: "genericName", "specificEpithet",
 #' "decimalLongitude", "decimalLatitude", "First", "Second", "Third",
 #' "datasetKey". The "datasetKey" column is important for GBIF records and
 #' identifies the dataset to which the occurrence record belongs. Custom
@@ -63,24 +63,32 @@ find_areas <- function(
   checkmate::assertDataFrame(occs)
   checkmate::testSubset(
     c(
-      "acceptedScientificName",
       "genericName",
       "specificEpithet",
-      "decimalLongitude",
-      "decimalLatitude",
       "First",
       "Second",
       "Third",
       "datasetKey"
     ),
     names(occs)
   )
-  # Ensure columns are correct type
-  checkmate::assertCharacter(occs$acceptedScientificName)
+  # If a shapefile is input, ensure that longitude and latitude are in occs
+  if(!is.null(shapefile)){
+    checkmate::testSubset(
+      c(
+        "decimalLongitude",
+        "decimalLatitude"
+      ),
+      names(occs)
+    )
+    # And ensure that they're numeric
+    checkmate::assertNumeric(occs$decimalLongitude)
+    checkmate::assertNumeric(occs$decimalLatitude)
+  }
+  
+  # Ensure other columns are correct type
   checkmate::assertCharacter(occs$genericName)
   checkmate::assertCharacter(occs$specificEpithet)
-  checkmate::assertNumeric(occs$decimalLongitude)
-  checkmate::assertNumeric(occs$decimalLatitude)
   checkmate::assertCharacter(occs$First)
   checkmate::assertCharacter(occs$Second)
   checkmate::assertCharacter(occs$Third)

R/find_pam_areas.R

@@ -0,0 +1,99 @@
+#' Find areas of islands using a presence-absence matrix (PAM)
+#'
+#' Use a presence-absense matrix (PAM) to create a dataframe that can be
+#' used to generate a species-area relationship (SAR) or speciation-area
+#' relationship (SpAR) in the `ssarp` pipeline.
+#'
+#' PAMs summarize the occurrence
+#' of species across different geographic locations. The column names of a PAM
+#' are species names, with the exception of the first column, which specifies
+#' the name of locations. For each cell corresponding to a species/location
+#' pair, either a 1 (presence) or a 0 (absence) is input depending on whether
+#' the species can be found at that location or not.
+#'
+#' Using a PAM, this function will find the areas of the land masses relevant
+#' to the taxon of interest with two options: a built-in database of island
+#' names and areas, or a user-provided list of island names and areas.
+#'
+#' The default method is to reference a built-in dataset of island names
+#' and areas to find the areas of the landmasses relevant to the taxon of
+#' interest. The user may also decide to input their own custom dataframe
+#' including names of relevant land masses and their associated areas to
+#' bypass using `ssarp`'s built-in dataset.
+#'
+#' While the word "landmasses" was used heavily in this documentation, users
+#' supplying their own custom area dataframe or shapefile are encouraged to
+#' use this function in the `ssarp` workflow to create species- and speciation-
+#' area relationships for island-like systems such as lakes, fragmented habitat,
+#' and mountain peaks.
+#'
+#' @param pam A presence-absence matrix (PAM), saved as a dataframe.
+#' Please ensure that the PAM has
+#' species names (include both generic name and specific epithet,
+#' with an underscore separating them) as the column
+#' names, with the exception of the first column
+#' that designates locations, which must be named "Island".
+#' @param area_custom A dataframe including names of land masses and their
+#' associated areas. This dataframe should be provided when the user would like
+#' to bypass using the built-in database of island names and areas. Please
+#' ensure that the custom dataframe includes the land mass's area in a column
+#' called "AREA" and the name in a column called "Name". (Optional)
+#' @return A dataframe of species names, island names, and island areas
+#' @examples
+#' pam <- read.csv(system.file("extdata",
+#'                             "example_pam.csv",
+#'                             package = "ssarp"))
+#' areas <- find_pam_areas(pam = pam)
+#' @export
+
+find_pam_areas <- function(pam, area_custom = NULL) {
+  # Checkmate input verification
+  checkmate::assertDataFrame(pam)
+  checkmate::testSubset(
+    c("Island"),
+    names(pam)
+  )
+
+  # Turn PAM into dataframe with three columns:
+  #  Island, genericName, specificEpithet
+  # First, create a list to hold data
+  dat <- list()
+  for (i in seq_len(nrow(pam))) {
+    # Get current island
+    island <- pam$Island[i]
+
+    # Figure out which species are on the island (1s in row)
+    # Species are column names, excluding the first (which is the island name)
+    sp <- names(pam)[-1][pam[i, -1] == 1]
+
+    # Just in case the user input a PAM where there are 0 species on an island,
+    #  check that there is at least one species in sp before continuing
+    if (length(sp) > 0) {
+      # Split species names into genericName and specificEpithet for downstream
+      split_sp <- strsplit(sp, "_")
+
+      # Turn into a dataframe
+      sp_df <- do.call(rbind.data.frame, split_sp)
+      # Fix colnames
+      colnames(sp_df) <- c("genericName", "specificEpithet")
+
+      # Add island to dataframe (call it "Third" for ssarp::find_areas())
+      sp_df$Third <- island
+
+      # Add this small dataframe to the list
+      dat[[length(dat) + 1]] <- sp_df
+    }
+  }
+
+  # Turn dat into a dataframe
+  occs <- do.call(rbind.data.frame, dat)
+
+  # Add "First" and "Second" columns so it can be used with ssarp::find_areas()
+  occs$First <- NA
+  occs$Second <- NA
+  # They also need to be characters
+  occs$First <- as.character(occs$First)
+  occs$Second <- as.character(occs$Second)
+
+  return(find_areas(occs, area_custom))
+}

inst/extdata/example_pam.csv

@@ -0,0 +1,28 @@
+Island,Anolis_ahli,Anolis_alayoni,Anolis_aliniger,Anolis_allisoni,Anolis_allogus,Anolis_altitudinalis,Anolis_alumina,Anolis_alutaceus,Anolis_angusticeps,Anolis_argenteolus,Anolis_armouri,Anolis_bahorucoensis,Anolis_baleatus,Anolis_baracoae,Anolis_barahonae,Anolis_barbatus,Anolis_barbouri,Anolis_bartschi,Anolis_brevirostris,Anolis_carolinensis,Anolis_chamaeleonides,Anolis_chlorocyanus,Anolis_christophei,Anolis_cooki,Anolis_cristatellus,Anolis_cuvieri,Anolis_cyanopleurus,Anolis_cybotes,Anolis_distichus,Anolis_equestris,Anolis_etheridgei,Anolis_evermanni,Anolis_fowleri,Anolis_garmani,Anolis_grahami,Anolis_guazuma,Anolis_gundlachi,Anolis_hendersoni,Anolis_homolechis,Anolis_inexpectatus,Anolis_insolitus,Anolis_isolepis,Anolis_jubar,Anolis_krugi,Anolis_lineatopus,Anolis_longitibialis,Anolis_lucius,Anolis_luteogularis,Anolis_marcanoi,Anolis_mestrei,Anolis_noblei,Anolis_occultus,Anolis_oculatus,Anolis_olssoni,Anolis_opalinus,Anolis_ophiolepis,Anolis_poncensis,Anolis_porcatus,Anolis_porcus,Anolis_pulchellus,Anolis_reconditus,Anolis_ricordii,Anolis_roquet,Anolis_rubribarbus,Anolis_sagrei
+Hog Cay,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Anguilla,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Cuba,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Little Cayman,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Cayman Brac,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Anegada,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0
+Dominican Republic,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+Providenciales Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Guantanamo,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0
+San Salvador,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Great Exuma Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Grand Cayman,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+New Providence Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Guantanamo,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,1,0,1,0,0,0,0,0,0,1
+Tortola,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+Cuba,0,0,0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,1
+Grenada,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Cat Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Eleuthera Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Dominica,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0
+Martinique,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0
+Grand Bahama Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Long Island,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1
+Puerto Rico,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,0,1,0,0,0,0,0,0,0,1,0,0,0,0,1,0,0,1,0,0,0,0,0
+Jamaica,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,1,0,0,0,1
+Dominican Republic,0,0,1,0,0,0,1,0,0,0,1,1,1,0,1,0,1,0,1,1,0,1,1,0,1,0,0,1,1,0,1,0,1,0,0,0,0,1,0,0,1,0,0,0,0,1,0,0,1,0,0,0,0,1,0,0,0,1,0,0,0,1,0,0,1
+Cuba,1,1,0,1,1,1,0,1,1,1,0,0,0,1,0,1,0,1,0,0,1,0,0,0,0,0,1,0,0,1,0,0,0,0,0,1,0,0,1,1,0,1,1,0,0,0,1,1,0,1,1,0,0,0,0,0,0,1,1,0,0,0,0,1,1

man/find_areas.Rd

@@ -123,5 +123,4 @@ test_that("Inputting something other than a shapefile in 'shapefile' will
           cause an error", {
             expect_error(find_areas(occs = occs_spat,
                                     shapefile = 1))
-})
-
+})

man/find_pam_areas.Rd

@@ -0,0 +1,36 @@
+# Create test PAM
+pam <- as.data.frame(matrix(ncol = 3, nrow = 2))
+colnames(pam) <- c("Island", "G_Sp1", "G_Sp2")
+pam[1,] <- c("Cuba", 0, 1)
+pam[2,] <- c("Dominican Republic", 1, 0)
+
+# Test PAM with incorrect column names
+pam_name <- pam
+colnames(pam_name) <- c("one", "two", "three")
+
+# Matrix PAM
+pam_mat <- as.matrix(pam)
+
+########
+
+test_that("The find_pam_areas function returns a dataframe", {
+  expect_s3_class(find_pam_areas(pam), "data.frame")
+})
+
+test_that("The find_pam_areas function returns a dataframe with 6 columns", {
+  expect_equal(ncol(find_pam_areas(pam)), 6)
+})
+
+test_that("Inputting a dataframe without the correct column names will cause
+          an error", {
+  expect_error(find_pam_areas(pam_name))
+})
+
+test_that("Inputting a matrix instead of a dataframe will cause an error", {
+  expect_error(find_pam_areas(pam_mat))
+})
+
+test_that("Correct island areas are returned", {
+  test <- find_pam_areas(pam)
+  expect_equal(test[1,6], 1.22e+11)
+})