ECSAS.extract: Extract data from ECSAS database

In RoyChristian/ECSASconnect: Import and export data from the Eastern Canada Seabirds at Sea (ECSAS) and the Suivi des oiseaux en mer de l'est du Canada (SOMEC) databases

Extract data from ECSAS database

Description

This function will connect to the Access database, create a series of queries and import the desired information in a data frame.

Usage

ECSAS.extract(
  species = NULL,
  years = NULL,
  cruise.ids = NULL,
  lat = c(-90, 90),
  long = c(-180, 180),
  obs.keep = NA,
  obs.exclude = NA,
  sub.program = c("All", "Atlantic", "Quebec", "Arctic", "ESRF", "AZMP", "FSRS"),
  intransect = NULL,
  intransect.only = TRUE,
  distMeth = c(14, 20),
  ind.tables.only = FALSE,
  ecsas.path = NULL,
  ecsas.drive = "C:/Users/christian/Dropbox/ECSAS",
  ecsas.file = "Master ECSAS_backend v 3.31.mdb",
  debug = FALSE
)

Arguments

species	[character, default: ‘NULL’] Optional. Alpha code (or vector of Alpha codes, e.g., c("COMU,"TBMU", "UNMU")) for the species desired in the extraction.
years	[integer, default: ‘NULL’] Optional. Either a single year or a vector of two years denoting "from" and "to" (inclusive).
cruise.ids	[integer, default: ‘NULL’] Optional. Integer vector of cruise ID's to extract.
lat	[numeric(2), default: ‘c(-90, 90)’] Vector of two numbers giving the southern and northern limits of the range desired.
long	[numeric(2), default: ‘c(-180, 180)’] Vector of two numbers giving the western and eastern limits of the range desired. Note that west longitude values must be negative.
obs.keep	[character, default: ‘NA’] Names of the observers to keep for the extraction. Name format: Surname_FirstName (eg: "Bolduc_Francois").
obs.exclude	[character, default: ‘NA’] Name of the observer to exclude for the extraction. Name format: Surname_FirstName (eg: "Bolduc_Francois").
sub.program	[character, default: ‘c("All","Atlantic","Quebec","Arctic","ESRF","AZMP","FSRS")’] From which sub.program the extraction must be made. ‘All’ subprograms will include the observations made in the PIROP program.
intransect	DEPRECATED - please use intransect.only.
intransect.only	[logical(1), default: ‘TRUE’] If TRUE, return only observations coded as "In Transect", otherwise return all observations. See the ECSAS survey protocol for more details: Gjerdrum, C., D.A. Fifield, and S.I. Wilhelm. 2012. Eastern Canada Seabirds at Sea (ECSAS) standardized protocol for pelagic seabird surveys from moving and stationary platforms. Canadian Wildlife Service Technical Report Series No. 515. Atlantic Region. vi + 37 pp.
distMeth	[integer or character, default: ‘c(14,20)’] Integer(s) specifying the distance sampling method code(s) (see tblWatch.DistMeth in ECSAS). Acceptable values are a single integer, a vector of integers, or ‘All’. The default will includes all watches with perpendicular distances for both flying and swimming birds. If ‘All’, then observations from all distance sampling methods will be returned, which may include observations from the PIROP program if no other options preclude this.
ind.tables.only	[logical(1), default: ‘FALSE’] Indicates if two individual tables for watch/cruise, and observations should be returned rather than a single table with all columns combined. See Value section.
ecsas.path	[character, default: ‘NULL’] Full path name to the ECSAS database. If NULL, the path is built from ecsas.drive and ecsas.file.
ecsas.drive	[character, default: ‘"C:/Users/christian/Dropbox/ECSAS"’] Path to folder containing the ECSAS Access database. The default value is likely no longer useful and should be deprecated.
ecsas.file	[character, default: ‘"Master ECSAS_backend v 3.31.mdb"’] Name of the ECSAS Access database file. The default value is likely no longer useful and should be deprecated.

Details

Using the default values of intransect.only = TRUE and distMeth = c(14,20) has the side-effect of excluding data collected under the old PIROP protocl. To include these data, set intransect.only = FALSE and distMeth = "All".

The distance traveled during the watch is returned in the column WatchLenKm. If lat/long coordinates are available for both the start and end locations of the watch, then it is calculated as the shortest distance between these two points on the WGS84 ellipsoid using geosphere::distGeo() and, in this case, WatchLenKmHow will contain "distGeo". Otherwise WatchLenKm is calculated as the PlatformSpeed * CalcDurMin where CalcDurMin is the length of the watch in minutes computed from start and end times. In this case, WatchLenKmHow will contain "Dead Reckoning".

Value

By default the function will produce a data frame that contains all the pertinent information. Note that watches with no observations (the so called "zeros" are included by default).

If ind.tables.only is FALSE (the default), then a single dataframe is returned containing all pertinent cruise, watch and sightings table info for each observation. If a given watch had no observations, then sighting related fields will be NA.

If ind.tables.only is TRUE, then a list is returned with the following elements:

watches	the combined columns from the watch and cruise tables only.
sightings	the columns from the sightings table only.

Note it is not currently possible to extract the watch and cruise tables separately.

Author

Christian Roy, Dave Fifield

See Also

QC.extract

RoyChristian/ECSASconnect documentation built on April 23, 2024, 3:36 a.m.