camtrapR (version 3.0.2)

cameraOperation: Create a camera trap station operation matrix

Description

Construct a matrix of daily camera trap station operation for use in detectionHistory and spatialDetectionHistory, where it is needed for calculating trapping effort per occasion. It is also used in surveyReport to calculate the number of trap nights durig a survey. If several cameras were deployed per station, the matrix can contain camera- or station-specific trap operation information, or information about sessions during repeated surveys.

Usage

cameraOperation(
  CTtable,
  stationCol = "Station",
  cameraCol,
  sessionCol,
  setupCol,
  retrievalCol,
  hasProblems = FALSE,
  byCamera,
  allCamsOn,
  camerasIndependent,
  dateFormat = "ymd",
  occasionStartTime = 0,
  writecsv = FALSE,
  outDir
)

Value

A matrix. Row names always indicate Station IDs. If sessionCol and/or cameraCol are defined, they are contained in the row names also (camera ID only if byCamera = TRUE). Column names are dates.
Legend: NA: camera(s) not set up, 0: camera(s) not operational, 1 (or higher): number of operational camera(s) or an indicator for whether the station was operational (depending on camerasIndependent and allCamsOn)

Arguments

CTtable

data.frame containing information about location and trapping period of camera trap stations

stationCol

character. name of the column specifying Station ID in CTtable

cameraCol

character. name of the column specifying Camera ID in CTtable (optional). If empty, 1 camera per station is assumed.

sessionCol

character. name of the column specifying session ID in CTtable (optional). Use it for creating multi-session / multi-season detection histories (unmarked: unmarkedMultFrame; secr: capthist )

setupCol

character. name of the column containing camera setup dates in CTtable

retrievalCol

character. name of the column containing camera retrieval dates in CTtable

hasProblems

logical. If TRUE, function will look for columns specifying malfunction periods in CTtable (naming convention: ProblemX_from and ProblemX_to, where X is a number)

byCamera

logical. If TRUE, camera operation matrix is computed by camera, not by station (requires cameraCol)

allCamsOn

logical. Takes effect only if cameraCol is defined and if byCamera is FALSE. If allCamsOn = TRUE, all cameras at a station need to be operational for the station to be operational (e.g. 1 camera out of 2 malfunctioning renders the station inoperational). Output values can be 1/0/NA only (all cameras at a station operational/ at least 1 camera not operational/ no camera set up). If allCamsOn = FALSE, at least 1 active camera makes a station operational.

camerasIndependent

logical. Return number of active camera traps by station? Only if byCamera is FALSE and allCamsOn is FALSE. If camerasIndependent is TRUE, output values will be the number of operational cameras at a station. If camerasIndependent is FALSE, the value is 1 if at least 1 camera was operational, otherwise 0. In both cases, values are NA if no camera was set up.

dateFormat

character. The format of columns setupCol and retrievalCol (and potential problem columns) in CTtable. Must be interpretable by either as.Date or the "orders" argument parse_date_time in lubridate. Can be a date or (since version 2.1) a date-time.

occasionStartTime

integer. time of day (the full hour) at which to begin occasions. Replaces occasionStartTime from detectionHistory and spatialDetectionHistory.

writecsv

logical. Should the camera operation matrix be saved as a .csv?

outDir

character. Directory into which csv is saved

Author

Juergen Niedballa

Details

cameraCol is NULL by default, meaning the function assumes there was 1 camera per station in CTtable. If more than 1 camera was deployed per station, cameraCol needs to be specified to identify individual cameras within a station. Likewise, sessionCol can be used to if camera trap stations were operated during multiple sessions / trapping seasons.

dateFormat defaults to "YYYY-MM-DD", e.g. "2014-10-31", but can be any other date format or date-time also. It can be specified either in the format required by strptime or the 'orders' argument in parse_date_time in lubridate. In the example above, "YYYY-MM-DD" would be specified as "%Y-%m-%d" in base R or "ymd" in lubridate.

Since version 2.1, dateFormat can be a date-time. That makes it possible to specify the exact time cameras were set up / retrieved / malfunctioned / worked again. This information is used to calculate the daily trapping effort more precisely on days with incomplete effort.

Previously, setup and retrival day were counted as 1, indicating a whole day of effort on those days. Since version 2.1, setup and retrieval are assumed to have happened at 12 noon (resulting in daily effort of 0.5 instead of 1). Users can also specify the exact time cameras were set up (by providing a date-time in the setup / retrieval / problem columns). See vignette 3 for more details.

If hasProblems is TRUE, the function tries to find columns ProblemX_from and ProblemX_to in CTtable. X is a consecutive number from 1 to n, specifying periods in which a camera or station was not operational. If hasProblems is FALSE, cameras are assumed to have been operational uninterruptedly from setup to retrieval (see camtraps for details).

allCamsOn only has an effect if there was more than 1 camera at a station. If TRUE, for the station to be considered operational, all cameras at a station need to be operational. If FALSE, at least 1 active camera renders the station operational. Argument camerasIndependent defines if cameras record animals independently (it thus only has an effect if there was more than 1 camera at a station). This is the case if an observation at one camera does not increase the probability for detection at another camera (cameras face different trails at a distance of one another). Non-independence occurs if an animal is likely to trigger both camers (as would be the case with 2 cameras facing each other).

If camerasIndependent is TRUE, 2 active cameras at a station will result in a station operation value of 2 in the resulting matrix, i.e., 2 independent trap days at 1 station and day. If camerasIndependent is FALSE, 2 active cameras will return value 1, i.e., 1 trap night at 1 station per day.

Row names depend on the input arguments and contain the station name and potentially session and camera names (if sessionCol and/or cameraCol are defined).

Naming convention is (since version 1.2) Bold information are from the columns stationCol, sessionCol and cameraCol in CTtable:

Station
Station__SESS_SessionID
Station__CAM_CameraID
Station__SESS_SessionID__CAM_CameraID

Session are designated with prefix "__SESS_", cameras with prefix "__CAM_". Therefore, these are reserved words and may not be part of station, session or camera names. Here's what it may look like in real life:

Station1
Station1__SESS_2019
Station1__CAM_1024152
Station1__SESS_2019__CAM_1024152

Functions detectionHistory and spatialDetectionHistory recognize these and use the information accordingly.

Examples

data(camtraps)

# no problems/malfunction
camop_no_problem <- cameraOperation(CTtable      = camtraps,
                                    stationCol   = "Station",
                                    setupCol     = "Setup_date",
                                    retrievalCol = "Retrieval_date",
                                    writecsv     = FALSE,
                                    hasProblems  = FALSE,
                                    dateFormat   = "dmy"
)

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

# The examples above specified dateFormat using lubdridate package, which is more intuitive. 
# Alternatively one can used in base-R date conversions (strptime) as below:

# with problems/malfunction / dateFormat in strptime format
camop_problem_oldformat <- cameraOperation(CTtable      = camtraps,
                                           stationCol   = "Station",
                                           setupCol     = "Setup_date",
                                           retrievalCol = "Retrieval_date",
                                           writecsv     = FALSE,
                                           hasProblems  = TRUE,
                                           dateFormat   = "%d/%m/%Y"
)

camop_no_problem
camop_problem
camop_problem_oldformat