Documentation updates (pkgdown, speciation methods)

Author: kmartinet

NAMESPACE

@@ -4,6 +4,7 @@ S3method(plot,SAR)
 S3method(print,SAR)
 export(create_SAR)
 export(create_SpAR)
+export(estimate_BAMM)
 export(estimate_DR)
 export(estimate_MS)
 export(find_areas)
@@ -15,7 +16,6 @@ export(get_presence_absence)
 export(get_sources)
 export(quick_create_SAR)
 export(remove_continents)
-export(speciationBAMM)
 import(mapdata)
 import(maps)
 importFrom(stringi,stri_unescape_unicode)

R/estimate_BAMM.R

@@ -2,6 +2,7 @@
 #' 
 #' Use the BAMMtools package (Rabosky et al. 2014) to extract tip speciation 
 #' rates from user-supplied BAMM analysis objects.
+#' 
 #' @param label_type Either "epithet" or "binomial" (default): describes the 
 #' type of tip label in the tree used for the BAMM analysis. If "epithet," only 
 #' the species epithet will be used to match speciation rates to tips in the 
@@ -15,6 +16,13 @@
 #' `BAMMtools::getEventData()` function
 #' @return A dataframe that includes speciation rates for each species in the 
 #' occurrence record dataframe
+#' @references 
+#' - Rabosky, D.L. (2014). Automatic Detection of Key Innovations, Rate Shifts, 
+#' and Diversity-Dependence on Phylogenetic Trees. PLOS ONE, 9(2): e89543.
+#' - Rabosky, D.L., Grundler, M., Anderson, C., Title, P., Shi, J.J., 
+#' Brown, J.W., Huang, H., & Larson, J.G. (2014), BAMMtools: an R package for 
+#' the analysis of evolutionary dynamics on phylogenetic trees. Methods in 
+#' Ecology and Evolution, 5: 701-707.
 #' @examples 
 #' \dontrun{
 #' key <- get_key(query = "Anolis", rank = "genus")
@@ -39,7 +47,7 @@
 #' }
 #' @export
 
-speciationBAMM <- function(label_type = "binomial", occurrences, edata) {
+estimate_BAMM <- function(label_type = "binomial", occurrences, edata) {
   # Checkmate input validation
   checkmate::assertString(label_type)
   checkmate::assertDataFrame(occurrences)

R/estimate_DR.R

@@ -1,11 +1,16 @@
 #' Get speciation rates using the DR statistic (Jetz et al. 2012)
 #' 
-#' Use methodology from Sun and Folk (2020) to calculate the DR statistic for 
-#' each tip of a given tree and output a dataframe for use in SSARP's 
-#' speciation-area relationship pipeline. This method also removes any species 
-#' rows without rates (this is most likely to occur when the tree does not have 
-#' all of the species included in the occurrence record dataframe). The tree
-#' read in the examples below is modified from Patton et al. (2021).
+#' DR stands for “diversification rate,” but it is ultimately a better 
+#' estimation of speciation rate than net diversification (Belmaker and Jetz 
+#' 2015; Quintero and Jetz 2018) and returns results similar to BAMM’s tip 
+#' speciation rate estimations (Title and Rabosky 2019).
+#' 
+#' This function uses methodology from Sun and Folk (2020) to calculate the DR 
+#' statistic for each tip of a given tree and output a dataframe for use in 
+#' SSARP's speciation-area relationship pipeline. This method also removes any 
+#' species rows without rates (this is most likely to occur when the tree does 
+#' not have all of the species included in the occurrence record dataframe). 
+#' The tree read in the examples below is modified from Patton et al. (2021).
 #' @param tree The dated phylogenetic tree that corresponds with the taxa to be 
 #' included in a speciation-area relationship
 #' @param label_type Either "epithet" or "binomial" (default): describes the 
@@ -20,15 +25,23 @@
 #' @return A dataframe that includes speciation rates for each species in the 
 #' occurrence record dataframe
 #' @references 
+#' - Belmaker, J., & Jetz, W. (2015). Relative roles of ecological and 
+#' energetic constraints, diversification rates and region history on global 
+#' species richness gradients. Ecology Letters, 18: 563–571.
 #' - Jetz, W., Thomas, G.H, Joy, J.B., Harmann, K., & Mooers, A.O. (2012). The 
 #' global diversity of birds in space and time. Nature, 491: 444-448.
 #' - Patton, A.H., Harmon, L.J., del Rosario Castañeda, M., 
 #' Frank, H.K., Donihue, C.M., Herrel, A., & Losos, J.B. (2021). When adaptive 
 #' radiations collide: Different evolutionary trajectories between and within 
 #' island and mainland lizard clades. PNAS, 118(42): e2024451118.
+#' - Quintero, I., & Jetz, W. (2018). Global elevational diversity and 
+#' diversification of birds. Nature, 555, 246–250.
 #' - Sun, M. & Folk, R.A. (2020). Cactusolo/rosid_NCOMMS-19-37964-T: Code and 
 #' data for rosid_NCOMMS-19-37964 (Version V.1.0). Zenodo.
 #'  http://doi.org/10.5281/zenodo.3843441
+#' - Title P.O. & Rabosky D.L. (2019). Tip rates, phylogenies and 
+#' diversification: What are we estimating, and how good are the estimates? 
+#' Methods in Ecology and Evolution. 10: 821–834.
 #' @examples 
 #' # The GBIF key for the Anolis genus is 8782549
 #' #  Obtained with: key <- get_key(query = "Anolis", rank = "genus")

R/estimate_MS.R

@@ -16,7 +16,7 @@
 #' there are columns titled "Genus", "Species", and "areas"
 #' @return A dataframe that includes speciation rates for each island in the 
 #' user-provided occurrence record dataframe.
-#' #' @references 
+#' @references 
 #' - Magallόn, S. & Sanderson, M.J. (2001). Absolute Diversification Rates in 
 #' Angiosperm Clades. Evolution, 55(9): 1762-1780.
 #' @examples 

_pkgdown.yml

@@ -14,3 +14,31 @@ navbar:
         href: articles/Create_SAR.html
       - text: Create Speciation-Area Relationship
         href: articles/Create_SpAR.html
+
+reference:
+- title: Prepare Occurrence Records
+  contents:
+  - find_land
+  - find_areas
+  - remove_continents
+
+- title: Estimate Speciation Rates
+  contents:
+  - estimate_DR
+  - estimate_MS
+  - estimate_BAMM
+
+- title: Create Relationships
+  contents:
+  - create_SAR
+  - create_SpAR
+  - quick_create_SAR
+
+- title: Other Utilities
+  contents:
+  - get_island_areas
+  - get_presence_absence
+  - get_sources
+  - plot
+  - print
+

man/speciationBAMM.Rd man/estimate_BAMM.Rdman/speciationBAMM.Rd renamed to man/estimate_BAMM.Rd

@@ -86,23 +86,23 @@ occ_mat <- as.matrix(occ_simple)
 
 test_that("Inputting a matrix instead of a dataframe for occurrence records 
           will cause an error", {
-  expect_error(speciationBAMM(label_type = "epithet", 
+  expect_error(estimate_BAMM(label_type = "epithet", 
                               occurrences = occ_mat, edata = edata_test))
 })
 
 test_that("Inputting a non-string for the label type will cause an error", {
-  expect_error(speciationBAMM(label_type = 1, 
+  expect_error(estimate_BAMM(label_type = 1, 
                               occurrences = occ_simple, edata = edata_test))
 })
 
-test_that("The speciationBAMM function returns a dataframe (epithet labels)", {
-  expect_s3_class(speciationBAMM(label_type = "epithet", 
+test_that("The estimate_BAMM function returns a dataframe (epithet labels)", {
+  expect_s3_class(estimate_BAMM(label_type = "epithet", 
                                  occurrences = occ_simple, 
                                  edata = edata_test), "data.frame")
 })
 
-test_that("The speciationBAMM function returns a dataframe (binomial labels)", {
-  expect_s3_class(speciationBAMM(label_type = "binomial", 
+test_that("The estimate_BAMM function returns a dataframe (binomial labels)", {
+  expect_s3_class(estimate_BAMM(label_type = "binomial", 
                                  occurrences = occ_simple, 
                                  edata = edata_test), "data.frame")
 })