auk_zerofill: Read and zero-fill an EBD file

Description Usage Arguments Details Value Methods (by class) Examples

Description

Read an eBird Basic Dataset file, and associated sampling event data file, to produce a zero-filled, presence-absence dataset. The EBD contains bird sightings and the sampling event data is a set of all checklists, they can be combined to infer absence data by assuming any species not reported on a checklist was had a count of zero.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
auk_zerofill(x, ...)

## S3 method for class 'data.frame'
auk_zerofill(x, sampling_events, species, unique = TRUE,
  collapse = FALSE, setclass = c("tbl", "data.frame", "data.table"), ...)

## S3 method for class 'character'
auk_zerofill(x, sampling_events, species, sep = "\t",
  unique = TRUE, collapse = FALSE, setclass = c("tbl", "data.frame",
  "data.table"), ...)

## S3 method for class 'auk_ebd'
auk_zerofill(x, species, sep = "\t", unique = TRUE,
  collapse = FALSE, setclass = c("tbl", "data.frame", "data.table"), ...)

collapse_zerofill(x, setclass = c("tbl", "data.frame", "data.table"))

Arguments

x

filename, data.frame of EBD observations, or auk_ebd object with associated output files as created by auk_filter(). If a filename is provided, it must point to the EBD and the sampling_events argument must point to the sampling event data file. If a data.frame is provided it should have been imported with read_ebd(), to ensure the variables names have been set correctly, and it must have been passed through auk_unique() to ensure duplicate group checklists have been removed.

...

additional arguments passed to methods.

sampling_events

character or data.frame; filename for the sampling event data or a data.frame of the same data. If a data.frame is provided it should have been imported with read_sampling(), to ensure the variables names have been set correctly, and it must have been passed through auk_unique() to ensure duplicate group checklists have been removed.

species

character; species to include in zero-filled dataset, provided as scientific or English common names, or a mixture of both. These names must match the official eBird Taxomony (ebird_taxonomy). To include all species, don't pass anything to this argument.

unique

logical; should auk_unique() be run on the input data if it hasn't already. The check that auk_unique() has been run is simplistic: is there a checklist_id field or not.

collapse

logical; whether to call zerofill_collapse() to return a data frame rather than an auk_zerofill object.

setclass

tbl, data.frame, or data.table; optionally set additional classes to set on the output data. All return objects are data frames, but may additionally be tbl (for use with dplyr and the tidyverse) or data.table (for use with data.table). The default is to return a tibble.

sep

character; single character used to separate fields within a row.

Details

auk_zerofill() generates an auk_zerofill object consisting of a list with elements observations and sampling_events. observations is a data frame giving counts and binary presence/absence data for each species. sampling_events is a data frame with checklist level information. The two data frames can be connected via the checklist_id field. This format is efficient for storage since the checklist columns are not duplicated for each species, however, working with the data often requires joining the two data frames together.

To return a data frame, set collapse = TRUE. Alternatively, zerofill_collapse() generates a data frame from an auk_zerofill object, by joining the two data frames together to produce a single data frame in which each row provides both checklist and species information for a sighting.

Value

By default, an auk_zerofill object, or a data frame if collapse = TRUE.

Methods (by class)

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# read and zero-fill the sampling data
f_ebd <- system.file("extdata/zerofill-ex_ebd.txt", package = "auk")
f_smpl <- system.file("extdata/zerofill-ex_sampling.txt", package = "auk")
auk_zerofill(x = f_ebd, sampling_events = f_smpl)

# use the species argument to only include a subset of species
auk_zerofill(x = f_ebd, sampling_events = f_smpl,
             species = "Collared Kingfisher")

# to return a data frame use collapse = TRUE
ebd_df <- auk_zerofill(x = f_ebd, sampling_events = f_smpl, collapse = TRUE)

mstrimas/auk documentation built on May 20, 2019, 5:26 p.m.