From d5248ad7b554081de484b8c7ffb45672d5936055 Mon Sep 17 00:00:00 2001 From: Alejandro Ruete Date: Wed, 20 Nov 2019 13:27:01 +0100 Subject: [PATCH] release 0.0.3 --- DESCRIPTION | 23 ++++++++++++++++++++--- man/BIRDS.Rd | 1 - man/createVisits.Rd | 8 ++++++-- man/exploreVisits.Rd | 3 +-- man/focalSpReport.Rd | 10 ++++++++-- man/makeGrid.Rd | 11 +++++++++-- man/organizeBirds.Rd | 34 ++++++++++++++++++++++++---------- man/spatialVisits.Rd | 8 ++++++-- vignettes/BIRDS.R | 10 +++++----- vignettes/BIRDS.Rmd | 2 +- vignettes/BIRDS.html | 43 +++++++++++++++++++++---------------------- 11 files changed, 101 insertions(+), 52 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 0ab8117..0b3df50 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: BIRDS Type: Package Title: A set of tools for Biodiversity Information Review and Decision Support -Version: 0.0.2 +Version: 0.0.3 URL: https://github.com/greensway/BIRDS Authors@R: c( person("Debora", "Arlt", email = "debora.arlt@slu.se", role = "aut", @@ -10,7 +10,24 @@ Authors@R: c( comment = c(ORCID = "0000-0001-7681-2812")), person("Anton", "Hammarström", email = "anton@greensway.se", role = "aut")) Description: A set of tools to review and make decisions upon the use of - biodiversity data. + biodiversity data. This R package helps making the evaluation and preparation + of biodiversity data easy, systematic and reproducible. It also helps the users + to overlay the point observations into a custom grid that is useful for further + analysis. The review summarise statistics that helps evaluate whether a set + of species observations is fit-for-use and take decisions upon its use of on + further analyses. It does so by quantifying the sampling effort (amount of + effort expended during an event) and data completeness (data gaps) to help + judge whether the data is representative, valid and fit for any intended + purpose. The `BIRDS` package is most useful when working with heterogeneous + data sets with variation in the sampling process, i.e. where data have been + collected and reported in various ways and therefore varying in sampling effort + and data completeness (i.e. how well the reported observations describe the + “true” state). Primary biodiversity data (PBD) combining data from different + data sets, like e.g. GBIF mediated data, commonly vary in the ways data has + been generated - containing opportunistically collected presence-only data + toghether with and data from systematic monitoring programs. The set of tools + provided is aimed at understanding the process that generated the data (i.e. + observing, recording and reporting species into databases). License: GPL-3 Encoding: UTF-8 LazyData: true @@ -50,5 +67,5 @@ Suggests: taxize, testthat, utils -RoxygenNote: 6.1.1 +RoxygenNote: 7.0.0 VignetteBuilder: knitr diff --git a/man/BIRDS.Rd b/man/BIRDS.Rd index 77a73af..94b14cf 100644 --- a/man/BIRDS.Rd +++ b/man/BIRDS.Rd @@ -3,7 +3,6 @@ \docType{package} \name{BIRDS} \alias{BIRDS} -\alias{BIRDS-package} \title{BIRDS: A set of tools for Biodiversity Information Review and Decision Support.} \description{ BIRDS: A set of tools for Biodiversity Information Review and Decision Support. diff --git a/man/createVisits.Rd b/man/createVisits.Rd index eac462d..be5c5b8 100644 --- a/man/createVisits.Rd +++ b/man/createVisits.Rd @@ -4,8 +4,12 @@ \alias{createVisits} \title{Create unique visits IDs} \usage{ -createVisits(x, idCols = c("locality", "recordedBy"), - timeCols = c("day", "month", "year"), grid = NULL) +createVisits( + x, + idCols = c("locality", "recordedBy"), + timeCols = c("day", "month", "year"), + grid = NULL +) } \arguments{ \item{x}{An object of class \code{data.frame} or \code{SpatialPointsDataFrame} diff --git a/man/exploreVisits.Rd b/man/exploreVisits.Rd index f06656a..da70f08 100644 --- a/man/exploreVisits.Rd +++ b/man/exploreVisits.Rd @@ -4,8 +4,7 @@ \alias{exploreVisits} \title{A function to explore the definition of field visits} \usage{ -exploreVisits(x, visitCol = attr(x, "visitCol"), - sppCol = "scientificName") +exploreVisits(x, visitCol = attr(x, "visitCol"), sppCol = "scientificName") } \arguments{ \item{x}{an object of class \sQuote{OrganizedBirds} (organised BIRDS Spatial Dataframe). diff --git a/man/focalSpReport.Rd b/man/focalSpReport.Rd index f83f883..06c9273 100644 --- a/man/focalSpReport.Rd +++ b/man/focalSpReport.Rd @@ -4,8 +4,14 @@ \alias{focalSpReport} \title{Summarise all records for a species} \usage{ -focalSpReport(x, focalSp = NULL, long = TRUE, colVis = "grey", - colPres = "red", ...) +focalSpReport( + x, + focalSp = NULL, + long = TRUE, + colVis = "grey", + colPres = "red", + ... +) } \arguments{ \item{x}{an object of class \sQuote{SummarizeBirds}.} diff --git a/man/makeGrid.Rd b/man/makeGrid.Rd index 1884290..1c40f82 100644 --- a/man/makeGrid.Rd +++ b/man/makeGrid.Rd @@ -4,8 +4,15 @@ \alias{makeGrid} \title{Make a grid} \usage{ -makeGrid(polygon, gridSize, buffer = FALSE, hexGrid = TRUE, - offset = NULL, simplify = FALSE, tol = 0.01) +makeGrid( + polygon, + gridSize, + buffer = FALSE, + hexGrid = TRUE, + offset = NULL, + simplify = FALSE, + tol = 0.01 +) } \arguments{ \item{polygon}{an object of class \sQuote{SpatialPolygon} or diff --git a/man/organizeBirds.Rd b/man/organizeBirds.Rd index f0feff7..52d9919 100644 --- a/man/organizeBirds.Rd +++ b/man/organizeBirds.Rd @@ -5,21 +5,35 @@ \alias{organiseBirds} \title{Organize a dataframe to a usable format} \usage{ -organizeBirds(x, sppCol = "scientificName", idCols = c("locality", - "recordedBy"), timeCols = c("year", "month", "day"), - timeInVisits = "day", grid = NULL, presenceCol = NULL, +organizeBirds( + x, + sppCol = "scientificName", + idCols = c("locality", "recordedBy"), + timeCols = c("year", "month", "day"), + timeInVisits = "day", + grid = NULL, + presenceCol = NULL, xyCols = c("decimalLongitude", "decimalLatitude"), - dataCRS = "+init=epsg:4326", taxonRankCol = NULL, + dataCRS = "+init=epsg:4326", + taxonRankCol = NULL, taxonRank = c("SPECIES", "SUBSPECIES", "VARIETY"), - simplifySppName = FALSE) + simplifySppName = FALSE +) -organiseBirds(x, sppCol = "scientificName", idCols = c("locality", - "recordedBy"), timeCols = c("year", "month", "day"), - timeInVisits = "day", grid = NULL, presenceCol = NULL, +organiseBirds( + x, + sppCol = "scientificName", + idCols = c("locality", "recordedBy"), + timeCols = c("year", "month", "day"), + timeInVisits = "day", + grid = NULL, + presenceCol = NULL, xyCols = c("decimalLongitude", "decimalLatitude"), - dataCRS = "+init=epsg:4326", taxonRankCol = NULL, + dataCRS = "+init=epsg:4326", + taxonRankCol = NULL, taxonRank = c("SPECIES", "SUBSPECIES", "VARIETY"), - simplifySppName = FALSE) + simplifySppName = FALSE +) } \arguments{ \item{x}{A dataframe or a SpatialPointsDataFrame containing at least a diff --git a/man/spatialVisits.Rd b/man/spatialVisits.Rd index 9d64ab1..9b4a953 100644 --- a/man/spatialVisits.Rd +++ b/man/spatialVisits.Rd @@ -4,8 +4,12 @@ \alias{spatialVisits} \title{A function to make the exploreVisits Spatial} \usage{ -spatialVisits(x, xyCols = c("centroidX", "centroidY"), - dataCRS = "+init=epsg:4326", radius = "medianDist") +spatialVisits( + x, + xyCols = c("centroidX", "centroidY"), + dataCRS = "+init=epsg:4326", + radius = "medianDist" +) } \arguments{ \item{x}{an object of class \sQuote{data.frame}.} diff --git a/vignettes/BIRDS.R b/vignettes/BIRDS.R index e37580f..689ada2 100644 --- a/vignettes/BIRDS.R +++ b/vignettes/BIRDS.R @@ -1,14 +1,14 @@ -## ----setup, include = FALSE---------------------------------------------- +## ----setup, include = FALSE--------------------------------------------------- knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) -## ----install package, eval = F------------------------------------------- +## ----install package, eval = F------------------------------------------------ # install.packages('remotes') # remotes::install_github('Greensway/BIRDS') -## ----basic example, eval = TRUE------------------------------------------ +## ----basic example, eval = TRUE----------------------------------------------- library(BIRDS) # Create a grid for your sample area that will be used to summarise the data: grid <- makeGrid(gotaland, gridSize = 10) @@ -58,7 +58,7 @@ legend("topleft", legend=c("n.observations","n.visits"), legend("bottomright", legend=c("n.observations / n.visits", "avg. SLL per cell"), lty = 1, lwd = 3, col = c("#78D2EB", "#FFB3B5"), bty = "n") -## ----figure 2, fig.show='hold', fig.width= 7, fig.height= 3-------------- +## ----figure 2, fig.show='hold', fig.width= 7, fig.height= 3------------------- library(sp) wNonEmpty<-unname( which( unlist(lapply(SB$overlaid, nrow)) != 0) ) EB <- exportBirds(SB, "Spatial", "Month", "nYears", "sum") @@ -83,7 +83,7 @@ legend("bottomleft", legend=seq(0, max(EB@data, na.rm = TRUE), length.out = 5), col = palBW(seq(0, max(EB@data, na.rm = TRUE), length.out = 5)), title = "Number of years", pch = 15, bty="n") -## ----figure 3, fig.show='hold', fig.width= 7, fig.height= 4-------------- +## ----figure 3, fig.show='hold', fig.width= 7, fig.height= 4------------------- par(mfrow=c(1,2), mar=c(1,1,1,1)) palBW <- leaflet::colorNumeric(c("white", "navyblue"), c(0, max(SB$spatial@data$nVis, na.rm = TRUE)), diff --git a/vignettes/BIRDS.Rmd b/vignettes/BIRDS.Rmd index edd1261..3d58929 100644 --- a/vignettes/BIRDS.Rmd +++ b/vignettes/BIRDS.Rmd @@ -40,7 +40,7 @@ three basic steps: organizing the data into a sampling event-based format, summa the data producing summary variables that inform about sampling effort and data completeness, and reviewing the summarized variables. -This package works with `data.frame` tables containing raw species observations +This package works with `data.frame` and `data.table` tables containing raw species observations as rows (i.e. primary biodiversity data, PBD), with minimal information required for each observation in the following columns: diff --git a/vignettes/BIRDS.html b/vignettes/BIRDS.html index f445b82..44d5f50 100644 --- a/vignettes/BIRDS.html +++ b/vignettes/BIRDS.html @@ -13,7 +13,7 @@ - + Introduction to BIRDS @@ -306,7 +306,7 @@

Introduction to BIRDS

Alejandro Ruete and Debora Arlt

-

2019-10-30

+

2019-11-20

@@ -321,7 +321,7 @@

Installing BIRDS

Basic example and data requirements

Starting with a primary biodiversity data set (species observations) BIRDS employs three basic steps: organizing the data into a sampling event-based format, summarizing the data producing summary variables that inform about sampling effort and data completeness, and reviewing the summarized variables.

-

This package works with data.frame tables containing raw species observations as rows (i.e. primary biodiversity data, PBD), with minimal information required for each observation in the following columns:

+

This package works with data.frame and data.table tables containing raw species observations as rows (i.e. primary biodiversity data, PBD), with minimal information required for each observation in the following columns:

  1. species identification
  2. x and y spatial coordinates in two columns (epsg:4326 assumed if not otherwise specified)
    3. @@ -344,24 +344,23 @@

    Basic example and data requirements

    # Convert the data from an observation-based to a visit-based format, adding a # unique identifier for each visit: OB <- organizeBirds(PBD, sppCol = "scientificName", simplifySppName = TRUE) -#> [1] "just keep going" - -# Summarise the data: -SB <- summariseBirds(OB, grid=grid) - -# Look at some summarised variables: -# Number of observations -EBnObs <- exportBirds(SB, dimension = "temporal", timeRes = "yearly", - variable = "nObs", method = "sum") -# Number of visits -EBnVis <- exportBirds(SB, dimension = "temporal", timeRes = "yearly", - variable = "nVis", method = "sum") -# The ratio of number of observations over number of visits -relObs<-EBnObs/EBnVis - -# Average species list length (SLL) per year (a double-average, i.e. the mean -# over cell values for the median SLL from all visits per year and cell) -EBavgSll <- colMeans(SB$spatioTemporal[,,"Yearly","avgSll"], na.rm = TRUE)
+ +# Summarise the data: +SB <- summariseBirds(OB, grid=grid) + +# Look at some summarised variables: +# Number of observations +EBnObs <- exportBirds(SB, dimension = "temporal", timeRes = "yearly", + variable = "nObs", method = "sum") +# Number of visits +EBnVis <- exportBirds(SB, dimension = "temporal", timeRes = "yearly", + variable = "nVis", method = "sum") +# The ratio of number of observations over number of visits +relObs<-EBnObs/EBnVis + +# Average species list length (SLL) per year (a double-average, i.e. the mean +# over cell values for the median SLL from all visits per year and cell) +EBavgSll <- colMeans(SB$spatioTemporal[,,"Yearly","avgSll"], na.rm = TRUE)

Then, with functions you already know, plot this into a time series.

par(mar=c(4,4,1,6), las=1)
 plot(time(EBnObs), EBnObs, type = "l", lwd = 3, xlab = "Year", ylab = "Number", 
@@ -409,7 +408,7 @@ 
Basic example and data requirements

 legend("bottomleft", legend=seq(0, max(EB@data, na.rm = TRUE), length.out = 5),
       col = palBW(seq(0, max(EB@data, na.rm = TRUE), length.out = 5)),
       title = "Number of years", pch = 15, bty="n")
-

+

We could also map the ignorance scores based on the either the number of observations or visits using the function exposeIgnorance(). Ignorance scores are a proxy for the lack of sampling effort, computed by making the number of observations relative to a reference number of observations that is considered to be enough to reduce the ignorance score by half (henceforth the Half-ignorance approach). The algorithm behind the Ignorance Score is designed for comparison of bias and gaps in primary biodiversity data across taxonomy, time and space Read more here: Ruete 2015 Biodiv Data J 3:e5361, doi:10.3897/BDJ.3.e5361

par(mfrow=c(1,2), mar=c(1,1,1,1))
 palBW <- leaflet::colorNumeric(c("white", "navyblue"),