VTrack (version 1.21)

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,iCores = 2)

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

iCores

the the number of cores with which to run the function in parallel. Default is 2.

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

# NOT RUN {
# }
# 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,
                        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)
# }