surveyReport: Create a report about camera trap surveys and species captures

Description

This function creates a report about camera trap surveys and species captures from a camera information table and a record database (generated with recordDatabase). The function calls cameraOperation internally.

Usage

surveyReport (recordTable,
  CTtable,
  speciesCol = "Species",
  stationCol = "Station",
  cameraCol, 
  setupCol,
  retrievalCol,
  CTDateFormat = "%Y-%m-%d", 
  CTHasProblems = FALSE,
  recordDateTimeCol = "DateTimeOriginal",
  recordDateTimeFormat = "%Y-%m-%d %H:%M:%S",
  sinkpath
)

Arguments

recordTable

data.frame containing a species record database as calculated by recordDatabase

CTtable

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

speciesCol

character. name of the column specifying Species ID in CTtable

stationCol

character. name of the column specifying Station ID in CTtable

cameraCol

character. name of the column specifying Camera ID in CTtable

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 in CTtable.

CTHasProblems

logical. Are there periods of camera malfunction specified in CTtable? This is passed as argument hasProblems to the function cameraOperation, which is called internally.

recordDateTimeCol

character. The names of the column containing date and time of record in recordTable

recordDateTimeFormat

character. The date/time format of column recordDateTimeCol in recordTable.

sinkpath

character. The directory into which the survey report is saved (optional)

Value

A list containing 5 data.frames.
survey_datesstation and image date ranges, number of trap days
species_by_stationspecies number by station
events_by_speciesnumber of events and stations by species
events_by_stationnumber of events for every species by station (only species that were recorded)
events_by_station2number 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.

Details

The value of CTDateFormat should be an interpretable by as.Date If sinkpath is defined, a txt file with the survey information will be saved there. If not, results will be shown in the console. The function will call cameraOperation internally to compute survey information from the camera operability database. cameraCol is "Camera" by default. cameraOperation (called internally) will check if there is more than 1 entry for any station and return an error if TRUE and the camera ID column of CTtable is not "Camera". In that case cameraCol needs to be changed accordingly. CTDateFormat defaults to "YYYY-MM-DD", e.g. "2014-10-31". See strptime for how to format date and time strings in R. In the cameraOperation call the argument hasProblems is set to TRUE, i.e. the function tries to find columns ProblemX_from and ProblemX_to in CTtable. X designates numbers from 1 to n in which a camera or station was not operational. If there are no such columns all stations are assumed to have been operational from setup to retrieval.

Examples

Run this code

data(camtraps)
data(recordDatabaseSample)

reportTest <- surveyReport (recordTable = recordDatabaseSample,
              CTtable = camtraps,
              speciesCol = "Species",
              stationCol = "Station",
              setupCol = "Setup_date",
              retrievalCol = "Retrieval_date",
              CTDateFormat = "%d/%m/%Y", 
              recordDateTimeCol = "DateTimeOriginal",
              recordDateTimeFormat = "%Y-%m-%d %H:%M:%S")

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)


# run again with sinkpath defined
reportTest <- surveyReport (recordTable = recordDatabaseSample,
                            CTtable = camtraps,
                            speciesCol = "Species",
                            stationCol = "Station",
                            setupCol = "Setup_date",
                            retrievalCol = "Retrieval_date",
                            CTDateFormat = "%d/%m/%Y", 
                            recordDateTimeCol = "DateTimeOriginal",
                            recordDateTimeFormat = "%Y-%m-%d %H:%M:%S",
                            sinkpath = getwd())

# have a look at the text file
readLines(list.files(getwd(), pattern = ".txt$", full.names = TRUE))