R/surveyReport.R
surveyReport.RdThis 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.
surveyReport(
recordTable,
CTtable,
camOp,
speciesCol = "Species",
stationCol = "Station",
cameraCol,
setupCol,
retrievalCol,
CTDateFormat = "ymd",
CTHasProblems = "deprecated",
recordDateTimeCol = "DateTimeOriginal",
recordDateTimeFormat = "ymd HMS",
Xcol,
Ycol,
sinkpath,
makezip
)data.frame containing a species record table as given by
recordTable
data.frame containing information about location and trapping
period of camera trap stations (equivalent to camtraps
camera operation matrix created with
cameraOperation
character. name of the column specifying Species ID in
recordTable
character. name of the column specifying Station ID in
CTtable and recordTable
character. name of the column specifying Camera ID in
CTtable and recordTable
character. name of the column containing camera setup dates
in CTtable
character. name of the column containing camera
retrieval dates in CTtable
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.
deprecated (since version 2.1)
character. The name of the column containing date
and time of records in recordTable
character. The date/time format of column
recordDateTimeCol in recordTable.
character. name of the column specifying x coordinates in
CTtable. Used to create detection maps if makezip is TRUE.
(optional)
character. name of the column specifying y coordinates in
CTtable. Used to create detection maps if makezip is TRUE.
(optional)
character. The directory into which the survey report is saved (optional)
logical. Create a zip file containing tables, plots and maps
in sinkpath?
An invisible list containing 5 data.frames.
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 numbers by station
number of events and stations by species
number of events for every species by station (only species that were recorded)
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.
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.
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")
#>
#> -------------------------------------------------------
#> [1] "Total number of stations: 3"
#>
#> -------------------------------------------------------
#> [1] "Number of operational stations: 3"
#>
#> -------------------------------------------------------
#> [1] "Trap nights (number of active 24 hour cycles completed by independent cameras): 128"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up and active (trap nights - LECAGY CALCULATION - WHOLE DAYS): 123"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up (LECAGY CALCULATION - WHOLE DAYS): 128"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up (operational or not): 131"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up and active: 131"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up but inactive: 0"
#>
#> -------------------------------------------------------
#> [1] "total trapping period: 2009-04-02 - 2009-05-17"
class(reportTest) # a list with
#> [1] "list"
length(reportTest) # 5 elements
#> [1] 5
reportTest[[1]] # camera trap operation times and image date ranges
#> Station setup retrieval image_first image_last n_cameras
#> 1 StationA 2009-04-02 2009-05-14 2009-04-10 2009-05-07 1
#> 2 StationB 2009-04-03 2009-05-16 2009-04-05 2009-05-14 1
#> 3 StationC 2009-04-04 2009-05-17 2009-04-06 2009-05-12 1
#> n_calendar_days_total n_calendar_days_active n_calendar_days_inactive
#> 1 43 43 0
#> 2 44 44 0
#> 3 44 44 0
#> n_trap_nights_active n_nights_active_legacy n_nights_total_legacy
#> 1 42 42 42
#> 2 43 43 43
#> 3 43 38 43
reportTest[[2]] # number of species by station
#> Station n_species
#> 1 StationA 2
#> 2 StationB 3
#> 3 StationC 4
reportTest[[3]] # number of events and number of stations by species
#> species n_events n_stations
#> 1 EGY 6 1
#> 2 MNE 2 1
#> 3 PBE 18 3
#> 4 TRA 8 1
#> 5 VTA 5 3
reportTest[[4]] # number of species events by station
#> Station Species n_events
#> 1 StationA PBE 4
#> 2 StationA VTA 2
#> 3 StationB MNE 2
#> 4 StationB PBE 8
#> 5 StationB VTA 2
#> 6 StationC EGY 6
#> 7 StationC PBE 6
#> 8 StationC TRA 8
#> 9 StationC VTA 1
reportTest[[5]] # number of species events by station including 0s (non-observed species)
#> Station Species n_events
#> 1 StationA EGY 0
#> 2 StationA MNE 0
#> 3 StationA PBE 4
#> 4 StationA TRA 0
#> 5 StationA VTA 2
#> 6 StationB EGY 0
#> 7 StationB MNE 2
#> 8 StationB PBE 8
#> 9 StationB TRA 0
#> 10 StationB VTA 2
#> 11 StationC EGY 6
#> 12 StationC MNE 0
#> 13 StationC PBE 6
#> 14 StationC TRA 8
#> 15 StationC VTA 1
# 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")
#>
#> -------------------------------------------------------
#> [1] "Total number of stations: 3"
#>
#> -------------------------------------------------------
#> [1] "Number of operational stations: 3"
#>
#> -------------------------------------------------------
#> [1] "Trap nights (number of active 24 hour cycles completed by independent cameras): 122.5"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up and active (trap nights - LECAGY CALCULATION - WHOLE DAYS): 123"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up (LECAGY CALCULATION - WHOLE DAYS): 128"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up (operational or not): 131"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up and active: 125"
#>
#> -------------------------------------------------------
#> [1] "Calendar days with cameras set up but inactive: 6"
#>
#> -------------------------------------------------------
#> [1] "total trapping period: 2009-04-02 - 2009-05-17"
reportTest_problem$survey_dates
#> Station setup retrieval image_first image_last n_cameras
#> 1 StationA 2009-04-02 2009-05-14 2009-04-10 2009-05-07 1
#> 2 StationB 2009-04-03 2009-05-16 2009-04-05 2009-05-14 1
#> 3 StationC 2009-04-04 2009-05-17 2009-04-06 2009-05-12 1
#> n_calendar_days_total n_calendar_days_active n_calendar_days_inactive
#> 1 43 43 0
#> 2 44 44 0
#> 3 44 38 6
#> n_trap_nights_active n_nights_active_legacy n_nights_total_legacy
#> 1 42.0 42 42
#> 2 43.0 43 43
#> 3 37.5 38 43
## 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")
#> Warning: Argument 'camOp' is missing (expected since camtrapR 2.1). Will run legacy version of surveyReport (from camtrapR 2.0.3). See: news(package = 'camtrapR') and ?surveyReport. This warning may be raised to an error in the future, so please adapt your code.
#>
#> -------------------------------------------------------
#> [1] "Total number of stations: 3"
#>
#> -------------------------------------------------------
#> [1] "Number of operational stations: 3"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up (operational or not. NOTE: only correct if 1 camera per station): 128"
#>
#> -------------------------------------------------------
#> [1] "n nights with cameras set up and active (trap nights. NOTE: only correct if 1 camera per station): 128"
#>
#> -------------------------------------------------------
#> [1] "total trapping period: 2009-04-02 - 2009-05-17"
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))
}