In AldoCompagnoni/poplerr: Popler R Package

Introduction: identifying groups of data sets

The popler R package was built to foster scientific synthesis using LTER long-term population data. The premise of such synthesis is using data from many research projects that share characteristics of scientific interest. To identify projects sharing salient attributes, popler uses the metadata information associated with each LTER project. In particular, it is fairly easy to select projects based on one or more of the following features:

1. Replication, temporal or spatial.
2. Taxonomic group(s).
3. Study characteristics.
4. Geographic location.

Vetting the database based on these criteria is intuitive. However, popler also facilitates identifying data sets in other ways. Below we provide several examples on how to select LTER data based on the four types of features described above. Moreover, in the final section we also show how to carry out more complicated types of searches.

1. Replication

Temporal replication

If you are interested in long-term data, you will likely want to select projects based on how many years the data was collected for. This is straightforward:

library(popler)
pplr_browse(duration_years > 10)

Note that most LTER projects contemplate sampling at a yearly or sub-yearly frequency. Thus, studies longer than 10 years often guarantee a longitudinal series of 10 or more observations. Note that the duration_years variable is calculated as studyendyr - studystartyr. Thus, an additional variable named samplefreq characterizes the approximate sample frequency of each study.

pplr_dictionary(samplefreq)
pplr_browse(samplefreq == "monthly")

Note that samplefreq is not a default variable included in the pplr_dictionary or pplr_browse() functions. This can be viewed by specifying the full_tbl = TRUE argument in either of the above functions.

1. Spatial replication

Before downloading data

If you wish to select data sets based on their spatial replication, you need to consider that popler organizes data in nested spatial levels. For example, in many plant studies data is collected at the plot level, which can be nested within block, which in turn can be nested within site. popler labels spatial levels using numbers. Spatial level 1 is the coarsest level of replication which contains all other spatial replicates. In the example above, spatial level 1 is site, spatial level 2 is block, and spatial level 3 is plot. popler allows for a total of 5 spatial levels. Given the above, you can select studies based on three criteria:

1. The total number of spatial replicates.

2. The number of replicates within a specific spatial level.

3. The number of nested spatial replicates.

Below we provide three examples for each one of these respective cases.

pplr_browse(tot_spat_rep > 100)
pplr_browse(spatial_replication_level_5_number_of_unique_reps > 1)
pplr_browse(n_spat_levs == 3)

After downloading data

Users can also explore the spatial and temporal replication of the data more explicitly after downloading it with pplr_get_data() through two function: pplr_site_rep() and pplr_site_rep_plot().

pplr_site_rep() provides two options for exploring data that meet temporal replication requirements at a given spatial resolution. The user can choose to filter data by specifying a minimum sampling frequency per year and a minimum number of years that sample with that frequency. Because this function uses the sampling dates to calculate the frequency, it provides additional information that is not contained in the samplefreq column of the main metadata table.

# download some data (note: this download is >100MB)
SEV <- pplr_get_data(proj_metadata_key == 21)

# Create a summary table containing names of replication levels that contain 2 samples per year for 10 years. 
SEV_long_studies <- pplr_site_rep(SEV, 
                                  freq = 2, 
                                  duration = 10, 
                                  return_logical = FALSE)

# you can also subset it directly using the function and specifying it to return a logical vector
subset_vec <- pplr_site_rep(SEV,
                            freq = 2,
                            duration = 10,
                            return_logical = TRUE)
# store subset of data
SEV_long_data <- SEV[subset_vec, ]

Users can also visualize the frequency of sampling at the coarsest level of spatial replication using the pplr_site_rep_plot() function. This generates a ggplot that denotes whether or not a particular site was sampled in a particular year. Note that the coarsest level of spatial replication is called site and it is contained in the variable spatial_replication_level_1.

library(ggplot2)

# return the plot object w/ return_plot = TRUE
pplr_site_rep_plot(SEV_long_data, return_plot = TRUE) +
  ggtitle("Long Term Data from Sevilleta LTER")

# or return an invisible copy of the input data and keep piping
library(dplyr)
SEV_long_data %>%
  pplr_site_rep_plot(return_plot = FALSE) %>%
  pplr_report_metadata()

2. Taxonomic group

popler is not limited to specific taxonomic groups, and it currently contains mostly data on animals and plants. To select information based on taxonomic groups, simply specify which group and which category you wish to select. The default settings of popler provide seven taxonomic groups: kingdom, phylum, class, order, family, genus, and species in each request. Column sppcode provides the identifier, usually an alphanumeric code, associated with each taxonomic entity in the original dataset. Note that not all LTER studies provide full taxonomic information; hence, browsing studies by taxonomic information will provide partial results (in the example below, not all insects studies will be identified).

pplr_dictionary(class)
pplr_browse(class == "Insecta")

Note that the taxonomic information returned in pplr_browse() is housed in a data structure called list column. Each entry of this list column is itself a list that contains a data.frame with eight columns. Users can access this information using the following syntax.

insects <- pplr_browse(class == 'Insecta')

# access the taxonomic table from the first project in the insects object
insects$taxas[[1]]

# second table (etc.)
insects$taxas[[2]]

3. Study characteristics

Metadata information provides a few variables to select studies based on their design. In particular:

• studytype: indicates whether the study is observational or experimental. Options are obs or exp for observational and experimental studies, respectively.
• treatment_type: type of treatments, if study is experimental.
• community: indicates whether the project provides data on multiple species. Options are yes or no.
• structured_data: indicates whether the project provides information on population structure. For example, a population can be sub-divided in age, size, or developmental classes. Options are yes or no.

Below we show how to use these three fields.

pplr_dictionary(community)
pplr_browse(community == "no") # 20 single-species studies

pplr_dictionary(treatment)
nrow( pplr_browse(treatment == "fire") ) # 21 fire studies

pplr_dictionary(studytype)
nrow( pplr_browse(studytype == "obs") ) # 78 observational studies

4. Geographic location.

To select studies based on the latitude and longitude of LTER headquarters around which datasets were, or are being collected, simply use the lat_lter and lng_lter numeric variables:

pplr_dictionary( lat_lter, lng_lter )
pplr_browse( lat_lter > 40 & lng_lter < -100 ) # single-species studies

5. More complicated searches

Popler allows carrying out more complicated searches by allowing to i) simultaneously search several types of metadata variables, and ii) search studies matching a string pattern. In the first case, simply provide the function pplr_browse() with a logical statement regarding more than one metadata variable. For example, if you want studies on plants with at least 4 nested spatial levels, and 10 years of data:

pplr_browse(kingdom == "Plantae" & n_spat_levs == 4 & duration_years > 10)

In the second case, the keyword argument in function pplr_browse() will search for string patterns within the metadata of each study. For example, in case we were interested in studies using traps:

pplr_browse(keyword = 'trap')

Note that the keyword argument works with regular expressions as well:

# look for studies that include the words "trap" or "spatial"
pplr_browse(keyword = 'trap|spatial')

AldoCompagnoni/poplerr documentation built on Nov. 15, 2019, 9:14 a.m.