Learn R Programming

VTrack (version 1.11)

RunResidenceExtraction: Extract Residence and Nonresidence Events Within the Acoustic Detection Database

Description

Events when the transmitter remained within the detection field of a given receiver. The event is triggered when a transmitter is detected by a receiver and terminated when the transmitter is detected at another receiver, or if the transmitter is not detected by the same receiver within a user defined timeout window. nonresidences (i.e. when a transmitter moves between the detection fields of two receivers) are generated from the residences event table. The function returns a list object containing a residenceslog, a residences event table and a nonresidences event table.

Usage

RunResidenceExtraction(sInputFile, sLocation, iResidenceThreshold, iTimeThreshold, sDistanceMatrix = NULL)

Arguments

sInputFile
a data frame containing VTrack archive data, this archive is created using the ReadInputData function
sLocation
the location at which we wish to analyse our residence and non-residence events (i.e. RECEIVERID or STATIONNAME)
iResidenceThreshold
the minimum number of successive transmitter pings detected at a receiver before a residence event is recorded
iTimeThreshold
the minimum time period in seconds between pings before a residence event is recorded
sDistanceMatrix
an optional two dimensional array containing the distances between a set of points. This can be the distances between each receiver or between each station. The first column in this matrix must contain the names of the receivers/stations. The diagonal of the distance matrix should be printed as 0 if appropriate and the upper triange of the distance matrix should also be calculated. Row 1 must contain the names of the corresponding receivers/stations and column 1 should be named DM. If a distance matrix is not available, Distances moved and the rate of movement (ROM) are returned as 0 in the nonresidences event table

Value

A list object containing 3 tables. In the residenceslog table:
DATETIME
a POSIXct vector object containing the date and time that the information was logged at the receiver
RESIDENCEEVENT
a numeric vector indexing all the individual detections which make up each particular residence event listed in the residence event table
RECORD
a numeric vector indexing each detection within the event
TRANSMITTERID
a numeric or character vector indexing the transmitter from which residence events were determined
RECEIVERID
a numeric or character vector indexing the receiver where the event occurred. If STATIONNAME is specified in the function, STATIONNAME is returned
ELAPSED
a numeric vector containing the total time in seconds of the event
In the residences event table:
STARTTIME
a POSIXct vector object containing the date and time a residence event was initiated
ENDTIME
a POSIXct vector object containing the date and time a residence event ended
RESIDENCEEVENT
a numeric vector indexing each particular event back to the residenceslog table where all the individual detections making up the event can be viewed
TRANSMITTERID
a numeric or character vector indexing the transmitter from which residence events were determined
RECEIVERID
a numeric or character vector indexing the receiver where the event occurred. If STATIONNAME is specified in the function, STATIONNAME is returned
DURATION
a numeric vector containing the time in seconds from the first to last detection within the event
ENDREASON
a character vector containing the reason why the residence event ended. This may be due to the transmitter appearing at another receiver (receiver) or if the last detection had passed the user defined timeout threshold (timeout). signal lost indicates the last recording of each transmitter.
NUMRECS
a numeric vector containing the number of records detected within each event
In the nonresidences event table:
STARTTIME
a POSIXct vector object containing the date and time a transmitter left a receiver or station
ENDTIME
a POSIXct vector object containing the date and time a transmitter arrived at a different receiver orstation
NONRESIDENCEEVENT
a numeric vector indexing each nonresidence event
TRANSMITTERID
a numeric or character vector indexing the transmitter from which nonresidence events were determined
RECEIVERID1
a numeric or character vector indexing the receiver which the transmitter initially moved from. If STATIONNAME is specified in the function, STATIONNAME1 is returned
RECEIVERID2
a numeric or character vector indexing the receiver which the transmitter moved to. If STATIONNAME is specified in the function, STATIONNAME2 is returned
DURATION
a numeric vector containing the total ime in seconds taken for the transmitter to move between the two receivers
DISTANCE
a numeric vector containing the minimum distance travelled (m) between two receivers or stations according to the distance matrix. If a distance matrix was not attached (NULL), distance is returned as 0
ROM
a numeric vector containing the rate of movement (ROM) in m/s. This is calculated from the distance travelled (DISTANCE) divided by the time taken to move between the receivers (DURATION)

See Also

ReadInputData, RunSensorEventExtraction, RunTimeProfile

Examples

Run this code

## Not run: 
# 
# # Extract residence events from the archived crocodile data
# 
# # Load the crocodile dataset into the VTrack archive format
# data(crocs)
# Vcrocs <- ReadInputData(infile=crocs,
#                         iHoursToAdd=10,
#                         fAATAMS=FALSE,
#                         fVemcoDualSensor=FALSE,
#                         dateformat = NULL,
#                         sVemcoFormat='1.0')
# 
# # Load and generate the direct distance matrix
# data(PointsDirect_crocs)
# DirectDM <- GenerateDirectDistance(PointsDirect_crocs)
# 
# # Extract data for only transmitter #139
# T139 <- ExtractData(Vcrocs,sQueryTransmitterList = c("139"))
# T139_R <- ExtractUniqueValues(T139,5)
# 
# # Extract residences and nonresidences events.
# #   Events occur when >1 detection occurs at a receiver and detections
# #   are less than 43200 seconds apart
# #   The direct distance matrix is used for distance calculations
# T139Res<- RunResidenceExtraction(T139,  
#                                  "RECEIVERID",    
#                                  2,              
#                                  43200,
#                                  sDistanceMatrix=DirectDM)
# 
# # The residenceslog table
# T139log <- T139Res$residenceslog
# # The residences event file
# T139resid <- T139Res$residences
# # The nonresidences event file
# T139nonresid <- T139Res$nonresidences
# 
# # The RESIDENCEEVENT number in the residences event table corresponds
# # to the RESIDENCEEVENT number in the residenceslog table
# subset(T139log,T139log$RESIDENCEEVENT==2)
# subset(T139resid, T139resid$RESIDENCEEVENT==2)
# 
# subset(T139log,T139log$RESIDENCEEVENT==8)
# subset(T139resid, T139resid$RESIDENCEEVENT==8)
# 
# # Scale duration spent at receivers into 4 bins: <1min, <1hr, <1day, >1day  
# pchDURATION <- ifelse(T139resid$DURATION<60,0.1,
#                       ifelse(T139resid$DURATION<(60*60),0.5,
#                              ifelse(T139resid$DURATION<(60*60*24),1,3)))
# 
# # For TRANSMITTERID 139 plot the detections against time for each RECEIVERID 
# par(mfrow=c(1,1),las=1,bty="l")
# plot(as.Date(T139resid$STARTTIME),
#      as.numeric(as.factor(
#        as.numeric(as.character(T139resid$RECEIVERID)))),
#      ylab="RECEIVERID",xlab="DATETIME",
#      yaxt="n",pch=1,cex.axis=0.9,cex=pchDURATION,
#      main=unique(T139resid$TRANSMITTER))
# axis(side=2,las=1, at=seq(1,length(T139_R),1),cex.axis=0.7,
#      labels = T139_R[order(as.numeric(T139_R))])     
# 
# # Now plot the residence time at a receiver spatially and with 
# # each point representing the duration spent at each receiver
# myresid1 <- subset(T139resid, T139resid$ENDREASON=="receiver")
# totalDur <- tapply(myresid1$DURATION,myresid1$RECEIVERID,sum)
# totalDurT <- data.frame(LOCATION=names(totalDur), DURATION=as.vector(totalDur))
# XYDuration <- merge(PointsDirect_crocs,totalDurT)
# 
# plot(PointsDirect_crocs$LONGITUDE,PointsDirect_crocs$LATITUDE,
#      pch=1,cex=0.5,col="grey40",
#      xlim=c((min(PointsDirect_crocs$LONGITUDE)-0.01),(max(PointsDirect_crocs$LONGITUDE)+0.01)),
#      ylim=c((min(PointsDirect_crocs$LATITUDE)-0.01),(max(PointsDirect_crocs$LATITUDE)+0.01)),
#      xlab="Longitude",ylab="Latitude",
#      main=unique(T139resid$TRANSMITTER))
# points(XYDuration$LONGITUDE,XYDuration$LATITUDE,
#        cex=XYDuration$DURATION/500000, pch=16)
# ## End(Not run)

Run the code above in your browser using DataLab