VTrack (version 1.21)

RunSensorEventExtraction: Extract Sensor Events within an Acoustic Detection Database

Description

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

Usage

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

Arguments

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

Value

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

See Also

RunResidenceExtraction, RunTimeProfile

Examples

# 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=" "))

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

# }