detectionHistory: Species detection histories for occupancy analyses

In camtrapR: Camera Trap Data Management and Analysis Framework

Species detection histories for occupancy analyses

Description

This function generates species detection histories that can be used in single-species occupancy analyses with packages unmarked and ubms, as well as multi-species/community occupancy models via communityModel. It generates detection histories in different formats, with adjustable occasion length and occasion start time.

Usage

detectionHistory(
  recordTable,
  species,
  camOp,
  output = c("binary", "count"),
  stationCol = "Station",
  speciesCol = "Species",
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "ymd HMS",
  occasionLength,
  minActiveDaysPerOccasion,
  maxNumberDays,
  day1 = "survey",
  buffer,
  includeEffort = TRUE,
  scaleEffort = FALSE,
  occasionStartTime = "deprecated",
  datesAsOccasionNames = FALSE,
  timeZone,
  writecsv = FALSE,
  outDir,
  unmarkedMultFrameInput
)

Arguments

recordTable	data.frame. the record table created by recordTable
species	character. species name(s) for which to compute detection histories. Can be either a single species name (for use with unmarked/ubms) or a vector of multiple species names (for input to communityModel)
camOp	The camera operation matrix as created by cameraOperation
output	character. Return binary detections ("binary") or counts of detections ("count")
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	character. Format of column recordDateTimeCol in recordTable
occasionLength	integer. occasion length in days
minActiveDaysPerOccasion	integer. minimum number of active trap days for occasions to be included (optional)
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. Compute trapping effort (number of active camera trap days per station and occasion)?
scaleEffort	logical. scale and center effort matrix to mean = 0 and sd = 1?
occasionStartTime	(DEPRECATED) integer. time of day (the full hour) at which to begin occasions. Please use argument occasionStartTime in cameraOperation instead.
datesAsOccasionNames	If day1 = "survey", occasion names in the detection history will be composed of first and last day of that occasion.
timeZone	character. Must be a value returned by OlsonNames
writecsv	logical. Should the detection history be saved as a .csv?
outDir	character. Directory into which detection history .csv file is saved
unmarkedMultFrameInput	logical. Return input for multi-season occupancy models in unmarked (argument "y" in unmarkedMultFrame?

Details

The function creates species detection matrices in two possible formats: detection-by-date or detection-by-occasion. The start of detection histories is controlled by day1:

• "station": Each station's history begins on its setup day

• "survey": All stations begin on the first day of the survey

• A specific date (e.g., "2015-12-31"): All stations begin on this date

Dates must be in "YYYY-MM-DD" format if specified directly.

Two output formats are available via the output parameter:

• "binary": Records detection (1) or non-detection (0)

• "count": Records the number of detections per occasion

The includeEffort parameter determines how camera operation affects the output:

• If FALSE: Periods when cameras were not operational or only partly operational appear as NA in the detection history. This may lose species record from incomplete occasions.

• If TRUE: Incomplete occasions are retained. Outputs contain a separate effort matrix that can be used as an observation covariate in occupancy models.

It is generally advisable to include effort as a covariate to account for uneven sampling effort.

occasionLength controls how many days are aggregated into each sampling occasion. Note that occasionStartTime has moved to cameraOperation to ensure proper calculation of daily effort.

The values of stationCol in recordTable must be matched by the row names of camOp (case-insensitive), otherwise an error is raised.

For date/time formatting, recordDateTimeFormat accepts two syntax styles:

• Base R style (using %): e.g., "%Y-%m-%d %H:%M:%S"

• lubridate style: e.g., "ymd HMS"

lubridate will be used if there are no "%" characters in recordDateTimeFormat. The default and recommended format is "YYYY-MM-DD HH:MM:SS" (e.g., "2014-09-30 22:59:59").

For multi-season studies where sessionCol was used in cameraOperation, the function automatically detects this structure. Set unmarkedMultFrameInput = TRUE to format output for unmarkedMultFrame, with rows representing sites and columns ordered by season-major, occasion-minor (e.g., season1-occasion1, season1-occasion2, etc.).

Value

If a single species is provided (typical for unmarked/ubms analyses), returns a list with either 1, 2 or 3 elements depending on the value of includeEffort and scaleEffort:

detection_history	A species detection matrix
effort	A matrix giving the number of active camera trap days per station and occasion (= camera trapping effort). Only returned if includeEffort = TRUE
effort_scaling_parameters	Scaling parameters of the effort matrix. Only returned if includeEffort and scaleEffort are TRUE

If multiple species are provided (for use with communityModel), returns a similar list structure but with detection_history containing a named list of detection matrices, one for each species. The effort matrix is identical for all species and thus returned only once.

Warning

Setting output = "count" returns a count of detections, not individuals. These counts are not suitable for abundance modeling (e.g., N-mixture models) as they do not represent individual animals.

For important information about the timeZone parameter, please refer to the "Data Extraction" vignette (vignette("DataExtraction") or online at https://cran.r-project.org/package=camtrapR/vignettes/camtrapr3.pdf).

Author(s)

Juergen Niedballa

Examples

# define image directory
wd_images_ID <- system.file("pictures/sample_images_species_dir", 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   = "dmy"
)

## Not run: 
if (Sys.which("exiftool") != ""){        # only run this function if ExifTool is available
recordTableSample <- recordTable(inDir               = wd_images_ID,
                                 IDfrom              = "directory",
                                 minDeltaTime        = 60,
                                 deltaTimeComparedTo = "lastRecord",
                                 exclude             = "UNID",
                                 timeZone            = "Asia/Kuala_Lumpur"
)
}

## End(Not run)
data(recordTableSample)    # load the record history, as created above


# compute detection history for a species

# without trapping effort
DetHist1 <- detectionHistory(recordTable         = recordTableSample,
                            camOp                = camop_no_problem,
                            stationCol           = "Station",
                            speciesCol           = "Species",
                            recordDateTimeCol    = "DateTimeOriginal",
                            species              = "VTA",
                            occasionLength       = 7,
                            day1                 = "station",
                            datesAsOccasionNames = FALSE,
                            includeEffort        = FALSE,
                            timeZone             = "Asia/Kuala_Lumpur"
)

DetHist1                     # this is a list with 1 element
DetHist1$detection_history   # this is the contained detection/non-detection matrix


# with effort / using base R to define recordDateTimeFormat
DetHist2 <- detectionHistory(recordTable          = recordTableSample,
                             camOp                = camop_no_problem,
                             stationCol           = "Station",
                             speciesCol           = "Species",
                             recordDateTimeCol    = "DateTimeOriginal",
                             species              = "VTA",
                             occasionLength       = 7,
                             day1                 = "station",
                             datesAsOccasionNames = FALSE,
                             includeEffort        = TRUE,
                             scaleEffort          = FALSE,
                             timeZone             = "Asia/Kuala_Lumpur"
)

DetHist2$detection_history  # detection history  (alternatively, use: DetHist2[[1]])
DetHist2$effort             # effort (alternatively, use: DetHist2[[2]])

# with effort / using lubridate package to define recordDateTimeFormat
DetHist2_lub <- detectionHistory(recordTable          = recordTableSample,
                                 camOp                = camop_no_problem,
                                 stationCol           = "Station",
                                 speciesCol           = "Species",
                                 recordDateTimeCol    = "DateTimeOriginal",
                                 recordDateTimeFormat = "ymd HMS",
                                 species              = "VTA",
                                 occasionLength       = 7,
                                 day1                 = "station",
                                 datesAsOccasionNames = FALSE,
                                 includeEffort        = TRUE,
                                 scaleEffort          = FALSE,
                                 timeZone             = "Asia/Kuala_Lumpur"
)    

DetHist2_lub$detection_history  # detection history  (alternatively, use: DetHist2_lub[[1]])
DetHist2_lub$effort             # effort (alternatively, use: DetHist2_lub[[2]])


# multi-season detection history

# load multi-season data
data(camtrapsMultiSeason)
data(recordTableSampleMultiSeason)

# multi-season camera operation matrix
camop_season <- cameraOperation(CTtable          = camtrapsMultiSeason,
                                    stationCol   = "Station",
                                    setupCol     = "Setup_date",
                                    sessionCol   = "session",
                                    retrievalCol = "Retrieval_date",
                                    hasProblems  = TRUE,
                                    dateFormat   = "dmy"
)

# multi-season detection history
DetHist_multi_season <- detectionHistory(recordTable      = recordTableSampleMultiSeason,
                            camOp                  = camop_season,
                            stationCol             = "Station",
                            speciesCol             = "Species",
                            species                = "VTA",
                            occasionLength         = 10,
                            day1                   = "station",
                            recordDateTimeCol      = "DateTimeOriginal",
                            includeEffort          = TRUE,
                            scaleEffort            = FALSE,
                            timeZone               = "UTC",
                            unmarkedMultFrameInput = TRUE
)

DetHist_multi_season


# Multi-species example for community occupancy analysis with communityModel()
DetHist_multi_species <- detectionHistory(recordTable = recordTableSample,
                                 species = c("VTA", "PBE", "EGY"),   # multiple species
                                 camOp = camop_no_problem,
                                 stationCol = "Station",
                                 speciesCol = "Species",
                                 recordDateTimeCol = "DateTimeOriginal",
                                 occasionLength = 7,
                                 day1 = "station",
                                 includeEffort = TRUE,
                                 scaleEffort = FALSE,
                                 timeZone = "Asia/Kuala_Lumpur"
)


# bundle input data for communityModel
data_list <- list(ylist = DetHist_multi_species$detection_history,
                  siteCovs = camtraps,
                  obsCovs = list(effort = DetHist_multi_species$effort))


## Not run: 

# create community model
mod.jags <- communityModel(data_list,
                           ...) # model specification 

## End(Not run)

camtrapR documentation built on Nov. 5, 2025, 6:54 p.m.