auk (version 0.2.2)

auk_zerofill: Read and zero-fill an eBird data file

Description

Read an eBird Basic Dataset (EBD) 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

auk_zerofill(x, ...)
# S3 method for data.frame
auk_zerofill(x, sampling_events, species,
  unique = TRUE, collapse = FALSE, ...)
# S3 method for character
auk_zerofill(x, sampling_events, species,
  sep = "\t", unique = TRUE, collapse = FALSE, ...)
# S3 method for auk_ebd
auk_zerofill(x, species, sep = "\t", unique = TRUE,
  collapse = FALSE, ...)
collapse_zerofill(x)

Arguments

x

filename, data.frame of eBird 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, leave this argument blank.

unique

logical; should auk_unique() be run on the input data if it hasn't already.

collapse

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

sep

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

Value

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

Methods (by class)

• data.frame: EBD data frame.

• character: Filename of EBD.

• auk_ebd: auk_ebd object output from auk_filter(). Must have had a sampling event data file set in the original call to auk_ebd().

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.

See Also

Other import: read_ebd

Examples

# NOT RUN {
# 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)
# }