surveyReport: Create a report about a camera trapping survey and species detections

Description

This function creates a report about a camera trapping survey and species records. It uses a camera trap station information table and a record table (generated with recordTable) as input. Output tables can be saved and a zip file for simple data sharing can be created easily.

Usage

surveyReport(
  recordTable,
  CTtable,
  camOp,
  speciesCol = "Species",
  stationCol = "Station",
  cameraCol,
  setupCol,
  retrievalCol,
  CTDateFormat = "ymd",
  CTHasProblems = "deprecated",
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "ymd HMS",
  Xcol,
  Ycol,
  sinkpath,
  makezip
)

Value

An invisible list containing 5 data.frames.

survey_dates: station and image date ranges, number of total and active trap days (calendar days and taking into account independent effort of multiple cameras, if applicable), number of cameras per station
species_by_station: species numbers by station
events_by_species: number of events and stations by species
events_by_station: number of events for every species by station (only species that were recorded)
events_by_station2: number of events for all species at all stations (including species that were not recorded)

The output will be saved to a .txt file if sinkpath is defined.

If makezip is TRUE, a zip file will be created in sinkpath. It contains single-species activity plots, detection maps (if Xcol and Ycol are defined), the survey report tables, the record table and the camera trap station table, and an example R script.

Arguments

recordTable: data.frame containing a species record table as given by recordTable
CTtable: data.frame containing information about location and trapping period of camera trap stations (equivalent to camtraps
camOp: camera operation matrix created with cameraOperation
speciesCol: character. name of the column specifying Species ID in recordTable
stationCol: character. name of the column specifying Station ID in CTtable and recordTable
cameraCol: character. name of the column specifying Camera ID in CTtable and recordTable
setupCol: character. name of the column containing camera setup dates in CTtable
retrievalCol: character. name of the column containing camera retrieval dates in CTtable
CTDateFormat: 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.
CTHasProblems: deprecated (since version 2.1)
recordDateTimeCol: character. The name of the column containing date and time of records in recordTable
recordDateTimeFormat: character. The date/time format of column recordDateTimeCol in recordTable.
Xcol: character. name of the column specifying x coordinates in CTtable. Used to create detection maps if makezip is TRUE. (optional)
Ycol: character. name of the column specifying y coordinates in CTtable. Used to create detection maps if makezip is TRUE. (optional)
sinkpath: character. The directory into which the survey report is saved (optional)
makezip: logical. Create a zip file containing tables, plots and maps in sinkpath?

Author

Juergen Niedballa

Details

dateFormat defaults to "YYYY-MM-DD", e.g. "2014-10-31". 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" or "ymd".

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.

Note: as of version 2.1, argument CTHasProblems is deprecated and defunct. Please use camOp instead to provide information about periods of camera activity and malfunction. If camOp is not provided the legacy version of surveyReport (from camtrapR 2.0.3) will be run with a warning.

Examples

Run this code


data(camtraps)
data(recordTableSample)

# since version 2.1, camera operation matrix is required as input

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

reportTest <- surveyReport (recordTable          = recordTableSample,
                            CTtable              = camtraps,
                            camOp                = camop_no_problem,
                            speciesCol           = "Species",
                            stationCol           = "Station",
                            setupCol             = "Setup_date",
                            retrievalCol         = "Retrieval_date",
                            CTDateFormat         = "dmy", 
                            recordDateTimeCol    = "DateTimeOriginal",
                            recordDateTimeFormat = "ymd HMS")

class(reportTest)  # a list with
length(reportTest) # 5 elements

reportTest[[1]]    # camera trap operation times and image date ranges
reportTest[[2]]    # number of species by station
reportTest[[3]]    # number of events and number of stations by species
reportTest[[4]]    # number of species events by station
reportTest[[5]]    # number of species events by station including 0s (non-observed species)

# with camera problems

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

reportTest_problem <- surveyReport (recordTable          = recordTableSample,
                                    CTtable              = camtraps,
                                    camOp                = camop_problem,
                                    speciesCol           = "Species",
                                    stationCol           = "Station",
                                    setupCol             = "Setup_date",
                                    retrievalCol         = "Retrieval_date",
                                    CTDateFormat         = "dmy", 
                                    recordDateTimeCol    = "DateTimeOriginal",
                                    recordDateTimeFormat = "ymd HMS")

reportTest_problem$survey_dates



## if camOp is missing, the legacy version (from 2.0.3) will be used:

reportTest_problem_old <- surveyReport (recordTable          = recordTableSample,
                                        CTtable              = camtraps,
                                       # camOp                = camop_problem,
                                        speciesCol           = "Species",
                                        stationCol           = "Station",
                                        setupCol             = "Setup_date",
                                        retrievalCol         = "Retrieval_date",
                                        CTDateFormat         = "dmy", 
                                        recordDateTimeCol    = "DateTimeOriginal",
                                        recordDateTimeFormat = "ymd HMS")

if (FALSE) {
# run again with sinkpath defined
reportTest <- surveyReport (recordTable          = recordTableSample,
                            CTtable              = camtraps,
                            camOp                = camop_no_problem,
                            speciesCol           = "Species",
                            stationCol           = "Station",
                            setupCol             = "Setup_date",
                            retrievalCol         = "Retrieval_date",
                            CTDateFormat         = "dmy",, 
                            recordDateTimeCol    = "DateTimeOriginal",
                            recordDateTimeFormat = "ymd HMS",
                            sinkpath             = getwd())

# have a look at the text file
readLines(list.files(getwd(), pattern = paste("survey_report_", Sys.Date(), ".txt", sep = ""), 
					 full.names = TRUE))
}

Run the code above in your browser using DataLab