Spatial-temporal replication of data sets

Functions to examine the number of temporal replicates contained within each spatial replication level of a dataset. pplr_site_rep_plot plots the temporal replicates available for each site. pplr_site_rep produces logical vectors that identify the spatial replicates with enough temporal replication, or summary tables.

Usage

pplr_site_rep(input, freq = 1, duration = 10, rep_level = 1,
  return_logical = TRUE)

pplr_site_rep_plot(input, return_plot = FALSE)

Arguments

input

An object of produced by pplr_get_data. Note that this is not an output from pplr_browse, as the raw data is required to calculate the amount of replication.

freq

A number corresponding to the desired annual frequency of replicates. Studies that are replicated more frequently will be included in the counts and those that replicated less frequently will be excluded. If return_logical = TRUE, rows that contain information from sites that are replicated at the desired frequency will have a TRUE value, and rows that are not will have a FALSE value. Values greater than 1 will select sampling done multiple times per year. For example, freq = 2 indicates a desired sampling frequency of 6 months. Conversely, freq = 0.5 indicates a desired sampling done once every 2 years.

duration

An integer corresponding to the desired number of yearly replicates. Rows containing site information from sites with more replication will be included, while those with less will be excluded.

rep_level

An integer corresponding to the level of spatial replication over which verify yearly temporal replication. Values between 1 and 5 are possible (though higher levels may not be present for some datasets). Higher values correspond to higher levels of spatial nestedness. The default value of rep_level = 1 corresponds to sites.

return_logical

logical; if TRUE, the function returns a logical vector. This vector can be used to subset the dataset. If FALSE, the function returns a summary table of class tbl. This table shows, in variable number_of_samples, how many temporal replicates per year are contained by each spatial replicate. Default is TRUE.

return_plot

A logical indicating whether to return a copy of the input data or the ggplot object created by the function. Use TRUE to return the ggplot object for subsequent modification. Use FALSE to return an invisible copy of the input object (useful for piping). Default is FALSE.

Value

pplr_site_rep_plot: input object (invisibly) or a ggplot2 object. Use return_plot to control.

pplr_site_rep: A tbl or a logical vector of length dim(input)[1]. Use return_logical to control.

Details

pplr_site_rep_plot produces a scatterplot showing the sites (spatial_replication_level_1) and years for which data is available.

pplr_site_rep works with any level of spatial replication and produces either a summary table of temporal replication or a logical vector that can be used to subset a data set based on the desired frequency and length of time.

Examples

if (FALSE) {

library(ggplot2)
library(dplyr)

# produce logical vector and subset using it. This can also be piped into a 
# the plotting function for visiualization

good_studies <- pplr_get_data(lterid == 'SEV') %>%
                   .[pplr_site_rep(input = .,
                                   duration = 12, 
                                   rep_level = 3), ] %>%
                   pplr_site_rep_plot()
                                       

# Or, make a neat summary table and decide where to go from there
SEV <- pplr_get_data(lterid == 'SEV')

rep_table <- pplr_site_rep(input = SEV,
                           freq = 0.5,
                           duration = 12,
                           return_logical = FALSE)
 
# pplr_site_rep_plot ---------------
                                                     
# create an unmodified figure
BNZ <- pplr_get_data(lterid == 'BNZ')

pplr_site_rep_plot(BNZ)

# Return the figure instead of the data for subsequent modification
Antarctica <- pplr_get_data(lterid == 'PAL')

pplr_site_rep_plot(Antarctica,
              return_plot = TRUE) + 
   ggtitle("Penguins Rock!")
   
# Use within pipes. Cannot return and modify the figure this way.
pplr_get_data(lterid == 'SEV') %>% 
  pplr_site_rep_plot(return_plot = FALSE) %>%
  pplr_report_metadata()
}