spatialDetectionHistory: 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 (other than midnight).

Usage

spatialDetectionHistory(recordTable, 
  species, 
  camOp, 
  CTtable,
  stationCol = "Station", 
  speciesCol = "Species",
  Xcol,
  Ycol,
  stationCovariateCols,
  individualCol,
  individualCovariateCols,
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "%Y-%m-%d %H:%M:%S",
  occasionLength, 
  occasionStartTime = 0, 
  maxNumberDays,
  beginWithDay1,
  includeEffort,
  scaleEffort,
  binaryEffort,
  timeZone
)

Arguments

recordTable

data.frame. the record table created by recordDatabaseIndividual (or recordDatabase)

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

stationCol

character. name of the column specifying Station ID in recordTable and CTtable

speciesCol

character. name of the column specifying species in recordTable

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 recordTable

individualCovariateCols

character. name of the column(s) specifying individual covariates in recordTable

recordDateTimeCol

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

recordDateTimeFormat

format of column recordDateTimeCol in recordTable

occasionLength

integer. occasion length in days

occasionStartTime

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

maxNumberDays

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

beginWithDay1

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

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?

binaryEffort

logical. Should effort be binary (1 if >1 active day per occasion, 0 otherwise)?

timeZone

character. must be an argument of OlsonNames

Value

A 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 trap 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. beginWithDay1 defines if each stations detection history will begin on that station's setup day (beginWithDay1 = TRUE) or if all station's detection histories have a common origin (the day the first station was set up, beginWithDay1 = TRUE). includeEffort controls whether an effort matrix is computed or not. If TRUE, effort will be used for object usage) information in a traps). scaleEffort and binaryEffort further define the behaviour. The number of days that are aggregated is controlled by occasionLength, which must be between 1 and half the number of days in camOp. occasionStartTime can be used to make occasions begin another hour than midnight (the default). This may be relevant for nocturnal animals, in which 1 whole night would be considered an occasion.

Examples

Run this code

data(recordDatabaseIndividualSample)
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   = "%d/%m/%Y"
)

sdh <- spatialDetectionHistory(recordTable          = recordDatabaseIndividualSample, 
                               species              = "LeopardCat",    
                               camOp                = camop_problem, 
                               CTtable              = camtraps,
                               stationCol           = "Station", 
                               speciesCol           = "Species",
                               Xcol                 = "utm_x",
                               Ycol                 = "utm_y",
                               individualCol        = "Individual",
                               recordDateTimeCol    = "DateTimeOriginal",
                               recordDateTimeFormat = "%Y-%m-%d %H:%M:%S",
                               occasionLength       = 10, 
                               beginWithDay1        = FALSE,
                               includeEffort        = TRUE,
                               timeZone             = "Asia/Kuala_Lumpur"
  )
  
# missing space in species = "LeopardCat" was introduced by recordDatabaseIndividual 
# (because of CRAN package policies. You can have spaces in your directory names)

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