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 occasion length and occasion start time.
detectionHistory(
recordTable,
species,
camOp,
output = c("binary", "count"),
stationCol = "Station",
speciesCol = "Species",
recordDateTimeCol = "DateTimeOriginal",
recordDateTimeFormat = "ymd HMS",
occasionLength,
minActiveDaysPerOccasion,
maxNumberDays,
day1,
buffer,
includeEffort = TRUE,
scaleEffort = FALSE,
occasionStartTime = "deprecated",
datesAsOccasionNames = FALSE,
timeZone,
writecsv = FALSE,
outDir,
unmarkedMultFrameInput
)data.frame. the record table created by
recordTable
character. the species for which to compute the detection history
The camera operability matrix as created by
cameraOperation
character. Return binary detections ("binary") or counts of detections ("count")
character. name of the column specifying Station ID in
recordTable
character. name of the column specifying species in
recordTable
character. name of the column specifying date and
time in recordTable
character. Format of column
recordDateTimeCol in recordTable
integer. occasion length in days
integer. minimum number of active trap days for occasions to be included (optional)
integer. maximum number of trap days per station (optional)
character. When should occasions begin: station setup date ("station"), first day of survey ("survey"), a specific date (e.g. "2015-12-31")?
integer. Makes the first occasion begin a number of days after station setup. (optional)
logical. Compute trapping effort (number of active camera trap days per station and occasion)?
logical. scale and center effort matrix to mean = 0 and sd = 1?
(DEPRECATED) integer. time of day (the full hour)
at which to begin occasions. Please use argument occasionStartTime in
cameraOperation instead.
If day1 = "survey", occasion names in the
detection history will be composed of first and last day of that occasion.
character. Must be a value returned by
OlsonNames
logical. Should the detection history be saved as a .csv?
character. Directory into which detection history .csv file is saved
logical. Return input for multi-season
occupancy models in unmarked (argument "y" in
unmarkedMultFrame?
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 is the optional effort matrix
and the third contains the effort scaling parameters.
A species detection matrix
A matrix
giving the number of active camera trap days per station and occasion (=
camera trapping effort). It is only returned if includeEffort = TRUE
Scaling parameters of the effort matrix. It
is only returned if includeEffort and scaleEffort are
TRUE
The function computes a species detection matrix, either as a
detection-by-date or a detection-by-occasion matrix. 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"). If
day1 is a date, as.Date must be able to
understand it. The most suitable format is "YYYY-MM-DD", e.g. "2015-12-31".
output is analogous to spatialDetectionHistory. It
makes the function return either counts of detections during occasions, or a
binary indicator for whether the species was detected.
includeEffort controls whether an additional effort matrix is
computed or not. This also affects the detection matrices. If
includeEffort = FALSE, all occasions in which a station was not set
up or malfunctioning (NA or 0 in camOp) will result in NAs in the
detection history. If includeEffort = 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
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.
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.
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.
If the camera operation matrix (camOp) was created for a multi-season
study (argument sesssionCol in cameraOperation was set,
it will be detected automatically. Output can be for unmarkedMultFrame by
setting unmarkedMultFrameInput = TRUE. Each row corresponds to a
site, and the columns are in season-major, occasion-minor order, e.g.
season1-occasion1, season1-occasion2, etc.).
Setting output = "count" returns a count of
detections, not individuals. We strongly advise against using it as input
for models of animal abundance (such as N-Mixture models) models which use
counts as input.
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)).
# 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"
)
if (FALSE) {
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"
)
}
}
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
#> $detection_history
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 0 1 0 0 1 0 NA
#> StationB 0 1 0 1 0 0 NA
#> StationC 0 0 1 0 0 0 NA
#>
DetHist1$detection_history # this is the contained detection/non-detection matrix
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 0 1 0 0 1 0 NA
#> StationB 0 1 0 1 0 0 NA
#> StationC 0 0 1 0 0 0 NA
# 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]])
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 0 1 0 0 1 0 0
#> StationB 0 1 0 1 0 0 0
#> StationC 0 0 1 0 0 0 0
DetHist2$effort # effort (alternatively, use: DetHist2[[2]])
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 6.5 7 7 7 7 7 0.5
#> StationB 6.5 7 7 7 7 7 1.5
#> StationC 6.5 7 7 7 7 7 1.5
# 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]])
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 0 1 0 0 1 0 0
#> StationB 0 1 0 1 0 0 0
#> StationC 0 0 1 0 0 0 0
DetHist2_lub$effort # effort (alternatively, use: DetHist2_lub[[2]])
#> o1 o2 o3 o4 o5 o6 o7
#> StationA 6.5 7 7 7 7 7 0.5
#> StationB 6.5 7 7 7 7 7 1.5
#> StationC 6.5 7 7 7 7 7 1.5
# 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 <- 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
#> $detection_history
#> o1 o2 o3 o4 o5 o6 o7 o8 o1 o2 o3 o4 o5 o6 o7 o8
#> StationA 1 0 0 1 0 NA NA NA 1 0 0 1 0 NA NA NA
#> StationB 0 1 1 0 0 NA NA NA 0 1 1 0 0 NA NA NA
#> StationC 0 0 1 0 NA NA NA NA 0 0 1 0 NA NA NA NA
#> StationD NA NA NA NA NA NA NA NA 0 0 0 0 0 0 0 0
#>
#> $effort
#> o1 o2 o3 o4 o5 o6 o7 o8 o1 o2 o3 o4 o5 o6 o7 o8
#> StationA 9.5 10 10 10 2.5 NA NA NA 9.5 10 10 10 2.5 NA NA NA
#> StationB 9.5 10 10 10 3.5 NA NA NA 9.5 10 10 10 3.5 NA NA NA
#> StationC 9.5 10 10 8 NA NA NA NA 9.5 10 10 8 NA NA NA NA
#> StationD NA NA NA NA NA NA NA NA 9.5 10 10 10 6.0 3 10 4.5
#>