dead_reckoning: Create a course steered and course made good using the...

In EdFarrell/animalTrack: Animal track reconstruction for high frequency 2-dimensional (2D) or 3-dimensional (3D) movement data

Description

Calculate past, present, or future position using "dead reckoning" Bowditch (1995). Specifically, the function calculates the "course steered" and the "course made good" (if end position is known).

Usage

dead_reckoning(speed, heading, angle = "degree", ret = TRUE, depth = NULL,
         pitch = NULL, startcoords=c(0,0), endcoords=NULL, coordsystem = "Cartesian",
         speedhorizontal = "corrected")

Arguments

speed	an object containing the values for measured speed (i.e. speed through water). (Note: this is assumed to be horizontal speed (i.e. no pitch), unless specified in the speedhorizontal argument.
heading	an object containing the values for measured heading. Can be one of c("degree", "radian").
angle	Unit of angular measure for heading. Default is "degree", but will accept "radian".
ret	Does the animal return to the same position as where it started? (i.e. (0,0))
depth	an object containing the values for measured depth (e.g pressure sensor, or altitude sensor).optional.
pitch	an object containing the values for calculated pitch. Both the pitch or pitch2 functions can be used. (Note: must be in radians). Optional.
startcoords	Coordinates for known location at the start of the track, c(x,y). This defaults to NULL, in which case the start coordinates will default to 0,0. If coordsystem = "Cartesian ", the default will still be (0,0), unless the user provides input. If coordsystem = "Cartesian", the user input x and y coordinates should be in meters. If coordsystem = "Geographic", then the user should provide x and y coordinates in decimal degrees.
endcoords	Coordinates for known location at the end of the track, c(x,y). If ret == F, the user must provide the ending coordinates (i.e. (x,y)) of the track. This is the location where dead_reckoning will correct the course to based on a constant set and drift.(NOTE: ret must be FALSE). If coordsystem = "Cartesian", the default will still be (0,0), unless the user provides input. If coordsystem = "Cartesian", the user input x and y coordinates should be in meters. If coordsystem = "Geographic", then the user should provide x and y coordinates in decimal degrees.
coordsystem	Coordinate system of startcoords and endcoords variables. This can be one of "Cartesian" (default), "Geographic", "UTM". "Cartesian" will return coordinates (CSx, CSy, CMGx, CMGy)from the function in meters on a Cartesian plane. "Geographic" will return geographic coordinates in decimal degrees. For "Geographic", the startcoords variable must have values in decimal degrees. "UTM" will return coordinates in Universal Tranverse Mercator (based on specified zone) in meters.
speedhorizontal	Indicates how the input speed values should be handled. Default is "corrected", which indicates that the input speed values are horizontal speeds (i.e. speed across a plane tangent to the surface of the earth). If "pitch", then speed is assumed to be a 3D vector and will be corrected to horizontal using speedh = cos(φ)*speed. If "depth", then speed is assumed to be a 3D vector and will be corrected to horizontal using speedh = √ (speed^2 - Δ depth^2). Optional.

Details

See Bowditch (1995) for a complete discussion of dead reckoning and navigation. This function extends traditional navigation calculations by providing the flexibility for 3-dimensional parameters common in animal tracking data.

Value

Object of class dr, which is a list with the following components:

CSx	a numeric vector with the x-coordinates for the calculated course steered. Position ascertained through "dead reckoning".
CSy	a numeric vector with the y-coordinates for the calculated course steered. Position ascertained through "dead reckoning".
CMGx	a numeric vector with the x-coordinates for the calculated course made good. Will be NA if end location is unknown (i.e. ret == F and endcoords = NULL. This is what Bowdith refers to as an "estimated position".)
CMGy	a numeric vector with the y-coordinates for the calculated course made good. Will be NA if end location is unknown (i.e. ret == F and endcoords = NULL. This is what Bowdith refers to as an "estimated position".)
depth	a numeric vector of depth (or altitude), which is the same as the user input. Depth should be in the same units as x and y (preferably meters).
speedh	speed horizontal. A numeric vector of corrected horizontal speed values. If speedhorizontal = "corrected" , then this will be the same as the input speed
speedmg	speed made good. A numeric vector of speed made good values. These are the speeds between observations after correcting the animal track for a course made good
drift	the speed of the current that resulted in the course steered. This is the distance between the course steered end location and the known (i.e. real) end location, divided by time. This represents the speed of the prevailing current, which is assumed to be constant
errordistance	This is the distance between the course steered end location and the known (i.e. real) end location
set	compass direction of the current. 0 <= set < 2π
coordsystem	The coordinate system of the output coordinates (i.e. CSx, CSy, CMGx, CMGy)

Author(s)

Ed Farrell <[e-mail]>

References

Bowditch, N. (1995), The New American Practical Navigator. Bethesda, MD: Defense Mapping Agency Hydrographic Topographic Center.

Examples

## Import the "missionbay2" dataset. See help(missionbay2)
## for full documentation.
data(missionbay2)

trial.1 <- missionbay2[missionbay2$trial == 1,]
trial.2 <- missionbay2[missionbay2$trial == 2,]
trial.3 <- missionbay2[missionbay2$trial == 3,]
trial.4 <- missionbay2[missionbay2$trial == 4,]

## Calculate the course made good for the four trials. Each returns
## to the starting position.
CS1 <- dead_reckoning(trial.1$speed, trial.1$heading_geo,angle="radian")
CS2 <- dead_reckoning(trial.2$speed, trial.2$heading_geo,angle="radian")
CS3 <- dead_reckoning(trial.3$speed, trial.3$heading_geo,angle="radian")
CS4 <- dead_reckoning(trial.4$speed, trial.4$heading_geo,angle="radian")

## Plot the course steered for each trial.
plot(CS1$CSx,CS1$CSy,type='l',col='blue',xlab="X-coordinate (unprojected)",
     ylab="Y-coordinate (unprojected)",ylim=c(-400,150))
lines(CS2$CSx,CS2$CSy,col='green')
lines(CS3$CSx,CS3$CSy,col='red')
lines(CS4$CSx,CS4$CSy,col='magenta')
legend(-300,100,legend=c("Run1","Run2","Run3","Run4"),col=c("blue","green",
       "red","magenta"),lty=c(1,1,1,1),bty="n")
title('Course Steered for Mission Bay Trials')
grid()

## Plot the course steered vs. course made good
plot(CS1$CSx,CS1$CSy,type='l',col='blue',xlab="X-coordinate (unprojected)",
     ylab="Y-coordinate (unprojected)",ylim=c(-400,150))
lines(CS1$CMGx,CS1$CMGy,col='black')
t.set <- paste("Track 1, Set Angle: ",as.character(round(CS1$set*(180/pi),2)))
t.drift <- paste("Track 1, Drift: ",as.character(round(CS1$drift,2))," m/s")
t.error <- paste("Track 1, Error Distance: ",as.character(round(CS1$errordistance,2))," m")
title(paste(t.set,"\n",t.drift,"\n",t.error))
legend(-300,100,legend=c("Course Steered","Course Made Good"),
       col=c("blue","black"),lty=c(1,1),bty="n")
grid()

EdFarrell/animalTrack documentation built on May 6, 2019, 3:12 p.m.