spatialDetectionHistory: Generate a 'capthist' object for spatial capture-recapture...

In camtrapR: Camera Trap Data Management and Preparation of Occupancy and Spatial Capture-Recapture Analyses

Generate a capthist object for spatial capture-recapture analyses from camera-trapping data

Description

This function generates spatial detection histories of individuals of a species for spatial capture-recapture analyses with package secr. Data are stored in a capthist object. The capthist object contains detection histories, camera-trap station location and possibly individual and station-level covariates. Detection histories can have adjustable occasion length and occasion start time (as in the function detectionHistory).

Usage

spatialDetectionHistory(
  recordTableIndividual,
  species,
  camOp,
  CTtable,
  output = c("binary", "count"),
  stationCol = "Station",
  speciesCol = "Species",
  sessionCol,
  Xcol,
  Ycol,
  stationCovariateCols,
  individualCol,
  individualCovariateCols,
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "ymd HMS",
  occasionLength,
  minActiveDaysPerOccasion,
  occasionStartTime = "deprecated",
  maxNumberDays,
  day1,
  buffer,
  includeEffort = TRUE,
  scaleEffort = FALSE,
  binaryEffort = FALSE,
  timeZone,
  makeRMarkInput
)

Arguments

recordTableIndividual	data.frame. the record table with individual IDs created by recordTableIndividual
species	character. the species for which to compute the detection history
camOp	The camera operability matrix as created by cameraOperation
CTtable	data.frame. contains station IDs and coordinates. Same as used in cameraOperation.
output	character. Return individual counts ("count") or binary observations ("binary")?
stationCol	character. name of the column specifying Station ID in recordTableIndividual and CTtable
speciesCol	character. name of the column specifying species in recordTableIndividual
sessionCol	character. name of the column specifying session IDs, either in recordTableIndividual or in CTtable. See 'Details' for more information. Session ID values must be a sequence of integer numbers beginning with 1 (i.e., 1,2,3,...).
Xcol	character. name of the column specifying x coordinates in CTtable
Ycol	character. name of the column specifying y coordinates in CTtable
stationCovariateCols	character. name of the column(s) specifying station-level covariates in CTtable
individualCol	character. name of the column specifying individual IDs in recordTableIndividual
individualCovariateCols	character. name of the column(s) specifying individual covariates in recordTableIndividual
recordDateTimeCol	character. name of the column specifying date and time in recordTableIndividual
recordDateTimeFormat	format of column recordDateTimeCol in recordTableIndividual
occasionLength	integer. occasion length in days
minActiveDaysPerOccasion	integer. minimum number of active trap days for occasions to be included (optional)
occasionStartTime	(DEPRECATED) integer. time of day (the full hour) at which to begin occasions. Please use argument occasionStartTime in cameraOperation instead.
maxNumberDays	integer. maximum number of trap days per station (optional)
day1	character. When should occasions begin: station setup date ("station"), first day of survey ("survey"), a specific date (e.g. "2015-12-31")?
buffer	integer. Makes the first occasion begin a number of days after station setup. (optional)
includeEffort	logical. Include trapping effort (number of active camera trap days per station and occasion) as usage in capthist object?
scaleEffort	logical. scale and center effort matrix to mean = 0 and sd = 1? Currently not used. Must be FALSE.
binaryEffort	logical. Should effort be binary (1 if >1 active day per occasion, 0 otherwise)?
timeZone	character. Must be a value returned by OlsonNames
makeRMarkInput	logical. If FALSE, output will be a data frame for RMark. If FALSE or not specified, a secr capthist object

Details

The function creates a capthist object by combining three different objects: 1) a record table of identified individuals of a species, 2) a camera trap station table with station coordinates and 3) a camera operation matrix computed with cameraOperation. The record table must contain a column with individual IDs and optionally individual covariates. The camera trap station table must contain station coordinates and optionally station-level covariates. The camera operation matrix provides the dates stations were active or not and the number of active stations.

day1 defines if each stations detection history will begin on that station's setup day (day1 = "station") or if all station's detection histories have a common origin (the day the first station was set up if day1 = "survey" or a fixed date if, e.g. day1 = "2015-12-31").

includeEffort controls whether an effort matrix is computed or not. If TRUE, effort will be used for object usage information in a traps. binaryEffort makes the effort information binary. scaleEffort is currently not used and must be set to FALSE. The reason is that usage can only be either binary, or nonnegative real values, whereas scaling effort would return negative values.

The number of days that are aggregated is controlled by occasionLength. occasionStartTime will be removed from the function. It has moved to cameraOperation, to ensure daily effort is computed correctly and takes the occasion start time into account. another hour than midnight (the default). This may be relevant for nocturnal animals, in which 1 whole night would be considered an occasion.

Output can be returned as individual counts per occasion (output = "count") or as binary observation (output = "binary").

Argument sessionCol can be used to a create multi-session capthist object. There are two different ways in which the argument is interpreted. It depends on whether a column with the name you specify in argument sessionCol exists in recordTableIndividual or in CTtable. If sessionCol is found in recordTableIndividual, the records will be assigned to the specified sessions, and it will be assumed that all camera trap station were used in all sessions. Alternatively, if sessionCol is found inCTtable, it will be assumed that only a subset of stations was used in each session, and the records will be assigned automatically (using the station IDs to identify which session they belong into). In both cases, session information must be provided as a sequence of integer numbers beginnign with 1, i.e., you provide the session number directly in sessionCol. See session for more information about sessions in secr.

capthist objects (as created by spatialDetectionHistory for spatial capture-recapture analyses) expect the units of coordinates (Xcol and col in CTtable) to be meters. Therefore, please use a suitable coordinate system (e.g. UTM).

recordDateTimeFormat defaults to the "YYYY-MM-DD HH:MM:SS" convention, e.g. "2014-09-30 22:59:59". recordDateTimeFormat can be interpreted either by base-R via strptime or in lubridate via parse_date_time (argument "orders"). lubridate will be used if there are no "%" characters in recordDateTimeFormat.

For "YYYY-MM-DD HH:MM:SS", recordDateTimeFormat would be either "%Y-%m-%d %H:%M:%S" or "ymd HMS". For details on how to specify date and time formats in R see strptime or parse_date_time.

Value

Output depends on argument makeRMarkInput:

list("makeRMarkInput = FALSE")	A capthist object
list("makeRMarkInput = TRUE")	A data frame for use in RMark

Warning

Please note the section about defining argument timeZone in the vignette on data extraction (accessible via vignette("DataExtraction") or online (https://cran.r-project.org/package=camtrapR/vignettes/camtrapr3.pdf)).

Author(s)

Juergen Niedballa

See Also

secr RMark

Examples

data(recordTableIndividualSample)
data(camtraps)

# create camera operation matrix (with problems/malfunction)
camop_problem <- cameraOperation(CTtable      = camtraps,
                                 stationCol   = "Station",
                                 setupCol     = "Setup_date",
                                 retrievalCol = "Retrieval_date",
                                 writecsv     = FALSE,
                                 hasProblems  = TRUE,
                                 dateFormat   = "dmy"
)

sdh <- spatialDetectionHistory(recordTableIndividual = recordTableIndividualSample,
                               species               = "LeopardCat",
                               camOp                 = camop_problem,
                               CTtable               = camtraps,
                               output                = "binary",
                               stationCol            = "Station",
                               speciesCol            = "Species",
                               Xcol                  = "utm_x",
                               Ycol                  = "utm_y",
                               individualCol         = "Individual",
                               recordDateTimeCol     = "DateTimeOriginal",
                               recordDateTimeFormat  = "ymd HMS",
                               occasionLength        = 10,
                               day1                  = "survey",
                               includeEffort         = TRUE,
                               timeZone              = "Asia/Kuala_Lumpur"
  )

# missing space in species = "LeopardCat" was introduced by recordTableIndividual
# (because of CRAN package policies.
# In your data you can have spaces in your directory names)

  summary(sdh)
  plot(sdh, tracks = TRUE)

  ## multi-season capthist object
  # see vignette "3. Extracting Data from Camera Trapping Images, creating occupancy & secr input"
  
  data(camtrapsMultiSeason)
  camtrapsMultiSeason$session[camtrapsMultiSeason$session == 2009] <- 1
  camtrapsMultiSeason$session[camtrapsMultiSeason$session == 2010] <- 2

  data(recordTableIndividualSampleMultiSeason)

  # create camera operation matrix (with problems/malfunction)
  camop_session <- cameraOperation(CTtable         = camtrapsMultiSeason,
                                      stationCol   = "Station",
                                      setupCol     = "Setup_date",
                                      sessionCol   = "session",
                                      retrievalCol = "Retrieval_date",
                                      hasProblems  = TRUE,
                                      dateFormat   = "dmy"
  )

sdh_multi <- spatialDetectionHistory(recordTableIndividual = recordTableIndividualSampleMultiSeason,
                               species               = "LeopardCat",
                               output                = "binary",
                               camOp                 = camop_session,
                               CTtable               = camtrapsMultiSeason,
                               stationCol            = "Station",
                               speciesCol            = "Species",
                               sessionCol            = "session",
                               Xcol                  = "utm_x",
                               Ycol                  = "utm_y",
                               individualCol         = "Individual",
                               recordDateTimeCol     = "DateTimeOriginal",
                               recordDateTimeFormat  = "ymd HMS",
                               occasionLength        = 10,
                               day1                  = "survey",
                               includeEffort         = TRUE,
                               timeZone              = "Asia/Kuala_Lumpur",
                               stationCovariateCols  = "utm_y",         # example
                               individualCovariateCols = "Individual"   # example
  )

  summary(sdh_multi)
  plot(sdh_multi, tracks = TRUE)

camtrapR documentation built on May 29, 2024, 6:45 a.m.