RunSensorEventExtraction: Extract Sensor Events within an Acoustic Detection Database
In VTrack: A Collection of Tools for the Analysis of Remote Acoustic Telemetry Data

Description Usage Arguments Value Author(s) See Also Examples

This function identifies, qualifies and quantifies increasing or decreasing sensor events within the acoustic detection database. Events are defined by the user and are based on sensor threshold and time-out parameters between detections. These are established from changes in sensor values between detections, over a user-defined period of time. The location of the event is determined by either the station or the receiver or location

1 2	RunSensorEventExtraction(sInputFile, iEventType, sLocation, iSensor, rTriggerThreshold, iTimeThresholdStart, iTimeThreshold, rTerminationThreshold)

`sInputFile`	a dataframe containing VTrack-transformed acoustic tracking data
`iEventType`	the type of event the user wants to extract. This can be either an event whereby the sensor values increase within a certain time period (= `"INCREASE"`) or an event whereby the sensor values decrease within a certain time period (= `"DECREASE"`)
`sLocation`	the location at which we wish to analyse our sensor events (i.e. `RECEIVERID` or `STATIONNAME`)
`iSensor`	the sensor data type to be extracted from the original file. This corresponds to the sensor units (`UNITS1`) contained within the `sInputFile` data frame (e.g. Depth = `m`)
`rTriggerThreshold`	the minimum change in sensor units for an event to commence
`iTimeThresholdStart`	the maximum time period (seconds) in which the `rTriggerThreshold` is reached before a sensor event commences
`iTimeThreshold`	the maximum time period (seconds) between detections before the sensor event is completed and the counter is reset
`rTerminationThreshold`	how close the sensor must be to the starting value before a sensor event is completed and the counter is reset

A list object 2 tables. In the sensor event logtable:

`DATETIME`	a vector of type POSIXct in Co-ordinated Universal Time (UTC)/ Greenwich Mean Time. The date and time that the location and sensor data was logged at the receiver
`SENSOREVENT`	a numeric vector indexing all the individual detections which make up each particular sensor event listed in the `event` table
`RECORD`	a numeric vector indexing each detection within the event
`TRANSMITTERID`	a numeric or character vector indexing the transmitter from which sensor events were determined
`RECEIVERID`	a numeric or character vector indexing the location where the event occurred. If `STATIONNAME` is specified in the function, the `STATIONNAME` where the event occurred is returned here
`SENSOR1`	a numeric vector containing the duration of the event in seconds
`ELAPSED`	a numeric vector containing the total time in seconds of the event

In the sensor event table:

`STARTTIME`	a POSIXct vector object containing the date and time a sensor event was initiated
`ENDTIME`	a POSIXct vector object containing the date and time a sensor event ended
`SENSOREVENT`	a numeric vector indexing each particular event back to the `logtable`, where all the individual detections making up the event can be viewed
`TRANSMITTERID`	a numeric vector indexing the transmitter from which sonsor events were determined
`RECEIVERID`	a numeric vector indexing the location where the event occurred. If `STATIONNAME` is specified in the function, the `STATIONNAME` where the event occurred is returned here
`DURATION`	a numeric vector containing the duration of the event in seconds
`STARTSENSOR`	a numeric vector containing the sensor value when the event was initialised
`ENDSENSOR`	a numeric vector containing the sensor value when the event was either completed or terminated
`MAXSENSOR`	a numeric vector containing the maximum sensor value attained during the event
`ENDREASON`	a character vector providing information on why the event was terminated. If the sensor returned to a value within the termination threshold from the `STARTSENSOR` value and within the time threshold (`= return`) or exceeded the timeout threshold between successive detections (`= timeout`)
`NUMRECS`	a number vector containing number of detections that compose the event

Ross Dwyer, Mathew Watts, Hamish Campbell

RunResidenceExtraction, RunTimeProfile

## Not run: 

## Example 1

# Extract depth events from transmitters attached
#   to crocodiles and plot a single diving event

# Load crocodile data
data(crocs)  
Vcrocs <- ReadInputData(infile=crocs,
                        iHoursToAdd=10,
                        dateformat = NULL,
                        sVemcoFormat='1.0')          

# Extract depth data for only the transmitter #139
T139 <- ExtractData(Vcrocs, 
                    sQueryTransmitterList = 139)

# Extract increasing depth sensor events
#   Start depth event when there is an depth increase of 0.5m within 1 hr 
#   Max interval between detections = 1 hr 
#   Complete event when sensor returns within 0.5 of the starting value
T139dives <- RunSensorEventExtraction(T139,
                                    "INCREASE", 
                                    "RECEIVERID",
                                    "m", 
                                    0.5,          
                                    (1*60*60),    
                                    (60*60),      
                                    0.5)          

# The sensor logfile
T139divelog <- T139dives$logtable
# The sensor event file
T139diveevent <- T139dives$event

# Return list of event numbers where sensor events were complete
T139diveevent[which(T139diveevent$ENDREASON=="return"),"SENSOREVENT"]

# Now extract and plot a single sensor event (we have swapped the axes round 
#   to show the diving behaviour)
mylog <- subset(T139divelog,T139divelog$SENSOREVENT==19)
par(mfrow=c(1,1),las=1,bty="l")
plot(mylog$DATETIME,(mylog$SENSOR1),
     xlab="Event duration (mins)",ylab="Depth (m)",type="b",
     yaxs = "i", xaxs = "i", ylim = rev(c(0,max(mylog$SENSOR1+0.5))),
     xlim = (range(mylog$DATETIME)+(c(-60,30))),
     pch=as.character(mylog$RECORD))
title(main=paste("Id=",mylog[1,4],", event=",mylog[1,2], sep=" "))

######################################################


## End(Not run)