import_data: Import survey data

In dkidney/gibbonsecr: SECR Analysis for Acoustic Gibbon Surveys

Description

The main arguments to this function are detections, posts and (optionally) covariates. The values of these arguments can be either (i) a string giving the the file path to a .csv file, or (ii) a data frame (see Details for a full description of the required format in each case).

The function returns a capthist object that can be used as an input to the gfit fitting function. The capthist object returned differs from the standard format used by the secr package in that arrays of estimated bearings and distances are attached as attributes (if present in the detections data).

Usage

import_data(detections, posts, covariates = NULL, details = list())

Arguments

detections	recapture data and (optionally) estimated bearings and distances to detected groups
posts	listening post coordinates (in metric units)
covariates	covariate values (optional)
details	list containing the type and units of the estimated bearings and distances (see Details)

Details

The format of the .csv files (or data frames) and the details argument are described below:

detections

This should contain one row per detection. For example, if group X was detected at array 1 on occasion 1 at posts A and B, and on occasion 2 at post C, then this would represent three detections. This data should contain the folowing columns:

array	array ID
occasion	sampling occasion (must be an integer)
post	listening post ID
group	group ID
bearing	estimated bearing (optional)
distance	estimated distance (optional)

posts

This should contain one row per listening post and contain the folowing columns:

array	array ID
post	listening post ID
x	listening post x-coordinate (in metric units)
y	listening post y-coordinate (in metric units)
usage	listening post usage (must be a string of 1s and 0s)

The values in the usage column should reflect the number of occasions. For single-occasion surveys all entries in the usage column should be "1". For multi-occasion surveys the length of each entry in the usage column should be equal to the number of occasions for that array. For example, in a three-occasion survey if post X was used on all occasions then the entry in the usage column should be "111", but if it was used on occasions 1 and 3 but not on occasion 2 then the entry would be "101".

covariates

This should contain one row per listening post-occasion combination. For example, if there are 3 listening posts at array X and 2 sampling occasions, the covariates data should contain 6 rows for that array (irrespective of the number of detections). This data should contain the folowing columns:

array	the array ID
occasion	the sampling occasion (must be an integer)
post	the listening post ID
<covariate1>	values for covariate 1
<covariate1>	values for covariate 2
...	...

For advice on model specification using covariates see gibbonsecr-covariates.

details

The value of the details argument should be a list. If there are no estimated bearings and no estimated distances then this should be an empty list (the default).

If the detections data contains estimated bearings, then one element of the details list should be named "bearings" and the value of this element should be a list with element names "units" and "type". The "units" element can be set to either "degrees" (the default) or "radians", and the "type" element should be set to "continuous" (currently the only available option). If bearings data exist and the "bearings" element is NULL then the default values are assumed.

If the detections data contains estimated bearings, then one element of the details list should be named "distances" and the value of this element should be a list with element names "units" and "type". The "units" element can be set to either "km" (the default) or "m", and the "type" element should be set to "continuous" (currently the only available option). If distances data exist and the "distances" element is NULL then the default values are assumed.

Author(s)

Darren Kidney [e-mail]

See Also

plot.gcapthist, import_shp

Examples

## Not run: 

# import from csv files --------------------------------------------------------

folder = system.file("extdata/N.annamensis", package = "gibbonsecr")
capthist = import_data(
    detections = file.path(folder, "detections.csv"),
    posts      = file.path(folder, "posts.csv"),
    covariates = file.path(folder, "covariates.csv"),
    details    = list(bearings = list(units = "degrees",
                                      type = "continuous"))
)
summary(capthist)

# import capthist data frames --------------------------------------------------

detections = read.csv(file.path(folder, "detections.csv"))
posts      = read.csv(file.path(folder, "posts.csv"))
covariates = read.csv(file.path(folder, "covariates.csv"))
head(detections)
head(posts)
head(covariates)
# using default details
capthist = import_data(
    detections = detections,
    posts      = posts,
    covariates = covariates,
    details    = list(bearings = list(units = "degrees",
                                      type = "continuous"))
)
summary(capthist)

## End(Not run)

dkidney/gibbonsecr documentation built on May 15, 2019, 9:11 a.m.