usage examples

.Rbuildignore

@@ -1,2 +1,4 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^README\.Rmd$
+^LICENSE\.md$

DESCRIPTION

@@ -1,13 +1,20 @@
 Package: afribat
 Type: Package
-Title: What the Package Does (Title Case)
+Title: African bat database in R
 Version: 0.1.0
-Author: Who wrote it
-Maintainer: The package maintainer <yourself@somewhere.net>
-Description: More about what it does (maybe more than one line)
-    Use four spaces when indenting paragraphs within the Description.
-License: What license is it under?
+Authors@R: 
+    person("Ousmane", "Ouedraogo", , "oousmane@proton.me", role = c("aut", "cre"),
+           comment = c(ORCID = "0000-0002-6349-4146"))
+Maintainer: The package maintainer <oousmane@proton.me>
+Description: A curated data of occurrences, distributions and conservation metrics for sub-Saharan bats
+License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 URL: https://github.com/oousmane/afribat
 BugReports: https://github.com/oousmane/afribat/issues
+RoxygenNote: 7.3.2
+Depends: 
+    R (>= 2.10)
+Imports: 
+    readr,
+    sf

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2024
+COPYRIGHT HOLDER: afribat authors

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 afribat authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

R/afribat.R

@@ -0,0 +1,24 @@
+#'  Bat records as tibble.
+#'  Occurrence records of 266 bat species from 53 genera and 12 families
+#'  (order Chiroptera, class Mammalia) from sub-Saharan Africa.
+#'
+#' @format A tibble with 17285 rows and 13 variables:
+#' \describe{
+#'   \item{family}{a character denoting family of bat record }
+#'   \item{genus}{a character denoting genus of bat record}
+#'   \item{species}{a character denoting species of bat record}
+#'   \item{museum}{ a character denoting museum accession number of bat record}
+#'   \item{date}{a date denoting date on which the bat was collected or otherwise recorded}
+#'   \item{year}{an integer denoting body mass (grams)}
+#'   \item{country}{a character denoting country in which the bat was recorded}
+#'   \item{location}{a character denoting name of the location or locality that the bat was recorded}
+#'   \item{latitude}{ a double denoting latitude in decimal degrees (EPSG:4326) of the record}
+#'   \item{longitude}{a double denoting longitude in decimal degrees (EPSG:4326) of the record}
+#'   \item{reference}{a character denoting source of the record, mostly papers}
+#'   \item{holotype}{a character denoting whether the record is a type specimen}
+#'   \item{checked}{a character denoting whether the bat specimen was examined by the authors}
+#' }
+#' @source {Originally published in: Monadjem, A., Montauban, C., Webala, P.W. et al. African bat database: curated data of occurrences, distributions and conservation metrics for sub-Saharan bats. Sci Data 11, 1309 (2024). https://doi.org/10.1038/s41597-024-04170-71}
+"afribats"
+
+

R/afribats_sf.R

@@ -0,0 +1,22 @@
+#'  Bat records as simple features.
+#'  Occurrence records of 266 bat species from 53 genera and 12 families
+#'  (order Chiroptera, class Mammalia) from sub-Saharan Africa.
+#'
+#' @format A tibble with 17255 rows and 12 variables:
+#' \describe{
+#'   \item{family}{a character denoting family of bat record }
+#'   \item{genus}{a character denoting genus of bat record}
+#'   \item{species}{a character denoting species of bat record}
+#'   \item{museum}{ a character denoting museum accession number of bat record}
+#'   \item{date}{a date denoting date on which the bat was collected or otherwise recorded}
+#'   \item{year}{an integer denoting body mass (grams)}
+#'   \item{country}{a character denoting country in which the bat was recorded}
+#'   \item{location}{a character denoting name of the location or locality that the bat was recorded}
+#'   \item{reference}{a character denoting source of the record, mostly papers}
+#'   \item{holotype}{a character denoting whether the record is a type specimen}
+#'   \item{checked}{a character denoting whether the bat specimen was examined by the authors}
+#'   \item{geometry}{ the geometry list column, crs is EPSG:4326}
+
+#' }
+#' @source {Originally published in: Monadjem, A., Montauban, C., Webala, P.W. et al. African bat database: curated data of occurrences, distributions and conservation metrics for sub-Saharan bats. Sci Data 11, 1309 (2024). https://doi.org/10.1038/s41597-024-04170-71}
+"afribats_sf"

R/diversity-indices.R

@@ -0,0 +1,215 @@
+#' Calculate Margalef's Diversity Index
+#'
+#' This function calculates Margalef's diversity index, a measure of species richness
+#' relative to the total number of individuals, using species names.
+#'
+#' @param x A character vector of species names. Each element represents an individual of a species.
+#' @param details Logical. If `TRUE`, the function returns a list containing the
+#' Margalef index, the number of unique species (\code{S}), and the total number of individuals (\code{N}).
+#' Defaults to \code{FALSE}.
+#'
+#' @return If \code{return_details = FALSE} (default), a numeric value representing Margalef's diversity index.
+#' If \code{return_details = TRUE}, a list with the following components:
+#' \itemize{
+#'   \item \code{Margalef_Index}: The calculated Margalef index.
+#'   \item \code{S}: The number of unique species.
+#'   \item \code{N}: The total number of individuals.
+#' }
+#' Returns \code{NA} if the index is undefined (e.g., fewer than two species or individuals).
+#'
+#' @examples
+#' # Example 1: Calculate Margalef's index for a simple dataset
+#'  x <- c("jonesi","gambiensis","hispida","hispida","thebaica","helvum","helvum","gambianus","gambianus","pusillus","monstrosus","aegyptiacus")
+#' margalef(x) # Simple output
+#'
+#' # Example 2: Return detailed results
+#' margalef(x, details = TRUE)
+#'
+#' # Example 3: Handle edge cases
+#' margalef(c("gambiensis")) # Returns NA with a warning
+#'
+#' @note Margalef's index is undefined if there is only one species or individual.
+#' The function will return \code{NA} in such cases with a warning.
+#' @source Margalef, R. (1958) Information Theory in Ecology. General Systems, 3, 36-71.
+#' @export
+margalef <- function(x, details = FALSE) {
+
+  # Check for empty input
+  if (length(x) == 0) stop("x should not be empty")
+
+  # Check if input is a character vector
+  if (!is.character(x)) stop("x should be a vector of character")
+
+  # Calculate the number of unique species (s) and total individuals (n)
+  s <- length(unique(x))
+  n <- length(x)
+
+  # Handle edge cases
+  if (n <= 1 || s <= 1) {
+    warning("Margalef index is undefined for fewer than 2 species or individuals")
+    return(NA)
+  }
+
+  # Calculate Margalef's index
+  d <- (s - 1) / log(n)
+
+  # Return results
+  if (details) {
+    return(list(margalef_index = d, S = s, N = n))
+  } else {
+    return(d)
+  }
+}
+
+#' Calculate Shannon-Weiner Diversity Index
+#'
+#' This function calculates the Shannon-Weiner diversity index, a measure of species diversity
+#' based on species relative abundance.
+#'
+#' @param x A character vector of species names. Each element represents an individual of a species.
+#'
+#' @return A numeric value representing the Shannon-Weiner diversity index. Returns \code{NA} if the input
+#' vector is empty or contains fewer than two unique species.
+#'
+#' @examples
+#' # Example 1: Calculate Shannon-Weiner index for a dataset
+#' x <- c("jonesi","gambiensis","hispida","hispida","thebaica","helvum","helvum","gambianus","gambianus","pusillus","monstrosus","aegyptiacus")
+#' shannon_weiner(x)
+#'
+#' # Example 2: Handle edge cases
+#' shannon_weiner(c("jonesi")) # Returns 0
+#' shannon_weiner(character(0)) # Returns NA with a warning
+#'
+#' @note The Shannon-Weiner index is undefined for an empty vector or vectors with only one unique species.
+#' For such cases, the function will return \code{NA} or 0 as appropriate.
+#'
+#' @export
+shannon_weiner <- function(x) {
+  # Check if input is a character vector
+  if (!is.character(x)) stop("x should be a vector of character")
+
+  # Check for empty input
+  if (length(x) == 0) {
+    warning("Input vector is empty. Returning NA.")
+    return(NA_real_)
+  }
+
+  # Calculate relative abundance (p)
+  p <- table(x) / length(x)
+
+  # Handle edge case: only one species present
+  if (length(p) < 2) {
+    return(0) # Shannon-Weiner index is 0 for a single species
+  }
+
+  # Calculate Shannon-Weiner index
+  H <- -sum(p * log(p))
+  return(H)
+}
+
+#' Calculate Evenness Index
+#'
+#' This function calculates the species evenness, which is a measure of how evenly individuals
+#' are distributed among the different species in a community. It is based on the Shannon-Weiner diversity index.
+#'
+#' @param x A character vector of species names. Each element represents an individual of a species.
+#'
+#' @return A numeric value representing the evenness index. Returns \code{NA} if the input vector is empty
+#' or contains fewer than two unique species.
+#'
+#' @examples
+#' # Example 1: Calculate evenness for a dataset
+#' x <- c("jonesi","gambiensis","hispida","hispida","thebaica","helvum","helvum","gambianus","gambianus","pusillus","monstrosus","aegyptiacus")
+#' evenness(x)
+#'
+#' # Example 2: Handle edge cases
+#' evenness(c("thebaica")) # Returns NA with a warning
+#' evenness(character(0)) # Returns NA with a warning
+#'
+#' @note Evenness is undefined for empty vectors or vectors with fewer than two unique species.
+#' The function will return \code{NA} in such cases with a warning.
+#'
+#' @seealso \code{\link{shannon_weiner}} for the Shannon-Weiner diversity index.
+#'
+#' @export
+
+evenness <- function(x) {
+  # Check if input is a character vector
+  if (!is.character(x)) stop("x should be a vector of character")
+
+  # Check for empty input
+  if (length(x) == 0) {
+    warning("Input vector is empty. Returning NA.")
+    return(NA)
+  }
+
+  # Calculate the number of unique species
+  s <- length(unique(x))
+
+  # Handle edge case: only one species present
+  if (s < 2) {
+    warning("Evenness is undefined for fewer than 2 species. Returning NA.")
+    return(NA)
+  }
+
+  # Calculate Shannon-Weiner index
+  H <- shannon_weiner(x)
+
+  # Calculate evenness
+  J <- H / log(s)
+
+  return(J)
+}
+
+#' Calculate Simpson's Diversity Index
+#'
+#' This function calculates Simpson's diversity index, which measures the probability
+#' that two individuals randomly selected from a sample will belong to different species.
+#'
+#' @param x A character vector of species names. Each element represents an individual of a species.
+#'
+#' @return A numeric value representing Simpson's diversity index. Returns \code{NA} if the input vector
+#' is empty or contains fewer than two unique species.
+#'
+#' @examples
+#' # Example 1: Calculate Simpson's diversity index
+#' x <- c("jonesi","gambiensis","hispida","hispida","thebaica","helvum","helvum","gambianus","gambianus","pusillus","monstrosus","aegyptiacus")
+#' simpson(x)
+#'
+#' # Example 2: Handle edge cases
+#' simpson(c("pusillus")) # Returns NA with a warning
+#' simpson(character(0)) # Returns NA with a warning
+#'
+#' @note Simpson's index is undefined for an empty vector or vectors with only one unique species.
+#' The function will return \code{NA} in such cases with a warning.
+#'
+#' @export
+simpson <- function(x) {
+  # Check if input is a character vector
+  if (!is.character(x)) stop("x should be a vector of character")
+
+  # Check for empty input
+  if (length(x) == 0) {
+    warning("Input vector is empty. Returning NA.")
+    return(NA_real_)
+  }
+
+  # Calculate the number of unique species
+  species_count <- length(unique(x))
+
+  # Handle edge case: only one species present
+  if (species_count < 2) {
+    warning("Simpson's index is undefined for fewer than 2 species. Returning NA.")
+    return(NA_real_)
+  }
+
+  # Calculate relative abundances (p)
+  p <- table(x) / length(x)
+
+  # Calculate Simpson's index
+  D <- 1 / sum(p^2)
+
+  return(D)
+}
+
+

R/path-to-file.R

@@ -0,0 +1,29 @@
+#' Get file path to `afribats.csv` and `afribats_sf.gpkg` files
+#'
+#' afribat comes bundled with one csv and one gpkg file in its `inst/extdata`
+#' directory. This function make them easy to access.
+#'
+#' The data in each file is the almost the same. In gpkg file, all missing positions coordinates were removed.
+#'
+#'
+#' @param path Name of file in quotes with extension;
+#' `"afribats.csv"` and `"afribats_sf.gpkg"` will work.
+#' If `NULL`, the example files will be listed.
+#' @export
+#' @examples
+#' # load libraries
+#' library(sf)
+#' library(readr)
+#'
+#' path_to_file("afribats.csv")
+#' head(read_csv(path_to_file("afribats.csv")))
+#' head(read_sf(path_to_file("afribats_sf.gpkg")))
+#'
+#' @source This function is adapted from `readxl::readxl_example()`.
+path_to_file <- function(path = NULL) {
+  if (is.null(path)) {
+    dir(system.file("extdata", package = "afribat"))
+  } else {
+    system.file("extdata", path, package = "afribat", mustWork = TRUE)
+  }
+}