camtrapR (version 0.97.0)

detectionHistory: Species detection histories for occupancy analysis

Description

This function generates species detection histories that can be used in occupancy analyses, e.g. with package unmarked. It generates detection histories in different formats, with adjustable session length and session start time (other than midnight).

Usage

detectionHistory(recordTable, 
  species, 
  camOp, 
  stationCol = "Station", 
  speciesCol = "Species",
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "%Y-%m-%d %H:%M:%S",
  sessionLength, 
  maxNumberDays,
  BeginWithDay1 = FALSE,
  includeEffort = TRUE,
  minimumEffort,
  scaleEffort,
  SessionStartTime = 0, 
  DatesAsSessionNames = FALSE,
  timeZone,
  writecsv = FALSE, 
  outDir
)

Arguments

recordTable

data.frame. the record table created by recordDatabase

species

character. the species for which to compute the detection history

camOp

The camera operability matrix as created by cameraOperation

stationCol

character. name of the column specifying Station ID in recordTable

speciesCol

character. name of the column specifying species in recordTable

recordDateTimeCol

character. name of the column specifying date and time in recordTable

recordDateTimeFormat

format of column recordDateTimeCol in recordTable

sessionLength

integer. session length in days

maxNumberDays

integer. maximum number of trap days per session (optional)

BeginWithDay1

logical. If TRUE, each station's detection history will begin at its respective setup day. If FALSE, sessions for all station will begin on the day the first station was set up.

includeEffort

logical. Compute effort (active camera trap days per station and session)?

minimumEffort

integer. minimum number of active trap days (effort) for a station to be considered active

scaleEffort

logical. scale and center effort matrix to mean = 0 and sd = 1?

SessionStartTime

integer. time of day (the full hour) at which to begin sessions.

DatesAsSessionNames

If BeginWithDay1 is FALSE, session names in the detecion history will be composed of first and last day of that session.

timeZone

character. must be an argument of OlsonNames

writecsv

logical. Should the detection history be saved as a .csv?

outDir

character. Directory into which detection history .csv file is saved

Value

• Depending on the value of includeEffort and scaleEffort, a list with either 1, 2 or 3 elements. The first element is the species detection history, the second the optional effort matrix.
• detectionHistory
  A species detection matrix
• Effort
  A matrix giving the number of active camera trap days per station and session (= camera trapping effort). It is only returned if includeEffort is TRUE

Details

The function computes a species detection matrix, either as a detection-by-date or a detection-by-session matrix. The behaviour is controlled by the argument BeginWithDay1. If BeginWithDay1 is TRUE, each stations history will begin on that station's setup day. If BeginWithDay1 is FALSE, all station's detection histories have a common origin (the day the first station was set up). includeEffort controls whether an effort matrix is computed or not. This also affects the detection matrices. If FALSE, all sessions in which a station was not set up or malfunctioning (NA or 0 in camOp) will result in NAs in the detection history. If TRUE, the record history will only contain 0 and 1, and no NAs. The effort matrix can then be included in occupancy models as a (continuous) observation covariate to estimate the effect of effort on detection probability. The number of days that are aggregated is controlled by sessionLength, which must be between 1 and half the number of days in camOp. SessionStartTime can be used to make sessions begin another hour than midnight (the default). This may be relevant for nocturnal animals, in which 1 whole night would be considered an occasion. The values of stationCol in recordTable must be matched by the row names of camOp (case-insensitive), otherwise an error is raised. DateTimeFormat defaults to "%Y-%m-%d %H:%M:%S", e.g. "2014-09-30 22:59:59". For details on how to specify date and time formats in R see strptime.

Examples

# define image directory
wd_images_ID <- system.file("pictures/sample_images", package = "camtrapR")

# load station information
data(camtraps)

# create camera operation matrix
camop_no_problem <- cameraOperation(CTtable = camtraps,
  stationCol = "Station",
  setupCol = "Setup_date",
  retrievalCol = "Retrieval_date",
  hasProblems = FALSE,
  dateFormat = "%d/%m/%Y"
)

# create record database
minDeltaT <- 60   # minutes between independent observations

if (Sys.which("exiftool") != ""){        # only run this function if Exiftool is available
recordDatabaseSample <- recordDatabase(inDir = wd_images_ID,
  minDeltaTime = minDeltaT,
  exclude = "NO_ID"
)
} else {
data(recordDatabaseSample)
}

# compute detection history for a species
species_for_DetHist <- "VTA"    # = Viverra tangalunga, Malay Civet
days_per_session <- 7

DetHist1 <- detectionHistory(recordTable = recordDatabaseSample,
  camOp = camop_no_problem,
  stationCol = "Station",
  speciesCol = "Species",
  recordDateTimeCol = "DateTimeOriginal",
  species = species_for_DetHist,
  sessionLength = days_per_session,
  BeginWithDay1 = TRUE,
  DatesAsSessionNames = FALSE,
  includeEffort = FALSE
)

DetHist1