NCEP.flight: Simulate Trajectories
In RNCEP: Obtain, Organize, and Visualize NCEP Weather Data

Description Usage Arguments Details Value Author(s) References Examples

This function simulates a single trajectory for any time and location by default using wind data returned by NCEP.interp. Various flight behaviors are possible.

NCEP.flight(beg.loc, end.loc, begin.dt, flow.assist='NCEP.Tailwind', 
  fa.args=list(airspeed=12), path='loxodrome', calibrate.dir=FALSE, 
  calibrate.alt=TRUE, cutoff=0, when2stop=list('latitude','longitude',50),
  levels2consider=c(850,925), hours=12, evaluation.interval=60, id=1, 
  land.if.bad=FALSE, reanalysis2 = FALSE, query=TRUE)

`beg.loc`	A numeric vector of length two giving the starting location in decimal degrees i.e. c(latitude, longitude)
`end.loc`	A numeric vector of length two giving the end location (i.e. goal location) in decimal degrees i.e. c(latitude, longitude)
`begin.dt`	A character string in the format '%Y-%m-%d %H:%M:%S' indicating the day and time at which to initiate take-off.
`flow.assist`	A character string giving the name of the flow-assistance function to apply, which also specifies the behavior of the animal in relation to the flow conditions. See Details below.
`fa.args`	A list of arguments passed to the flow-assistance function. See Details below.
`path`	Either a numeric value indicating the preferred direction of movement in degrees from North, or one of 'loxodrome' or 'great.circle' describing the method of calculating the preferred direction.
`calibrate.dir`	A logical expression indicating whether or not to re-calibrate the `path` to the goal at each evaluation interval.
`calibrate.alt`	A logigal expression indicating whether or not to re-calibrate the altitude from which to obtain wind data at each evaluation interval.
`cutoff`	A numeric value indicating the minimum acceptable flow-assistance to initiate the simulation (and to continue the simulation if `land.if.bad = TRUE`).
`when2stop`	A list containing at least one of 'latitude', 'longitude', or a numeric value. See Details below.
`levels2consider`	A vector indicating the altitudes at which to consider wind conditions. Values may be numeric and describe specific pressure levels or may be a character string describing 'surface' and/or 'gaussian'. See `NCEP.interp`
`hours`	A numeric value indicating the maximum number of hours to continue the simulation, in case the spatial goal is not reached.
`evaluation.interval`	A numeric value indicating the interval (in minutes) in which to reassess the situation and recalibrate (if `calibrate.dir` or `calibrate.alt` is `TRUE`). Also the interval at which movement statistics are calculated.
`id`	A character string or numeric value giving an id for the simulation.
`land.if.bad`	A logical expression describing whether or not the simulation should be interrupted if the flow-assistance is `NA` or below the `cutoff`.
`reanalysis2`	A logical expression indicating whether wind data should come from the Reanalysis I dataset (`FALSE`) or from Reanalysis II (`TRUE`). See `NCEP.interp`.
`query`	A logical expression indicating whether or not to use `NCEP.interp` to retrieve wind data. See Details below.

This function simulates a single trajectory according to the behavioral rules specified in flow.assist.

The argument flow.assist gives the flow-assistance equation to apply. It also determines how the animal will behave in relation to the flow conditions and thus how the animal will move. Internal options for flow.assist include "NCEP.FlowSpeed", "NCEP.NegFlowSpeed", "NCEP.Tailwind", "NCEP.Groundspeed", "NCEP.M.Groundspeed", "NCEP.Airspeed",and "NCEP.PartialSpeed". Each flow-assistance equation requires further arguements that should be given as a list to fa.args.

Users are invited to create their own flow-assistance functions using one of the existing functions as a template. Any flow-assistance function that is used in the context of NCEP.flight must contain at least the arguments u, v, and direction, as these arguments are passed directly by NCEP.flight if query == TRUE. If query == FALSE, only the argument direction is passed directly by NCEP.flight. Any other arguments are possible, and their value may be set using fa.args. As well, any flow-assistance function that is used in the context of NCEP.flight must produce a data.frame as output. This data.frame must contain at least the variables fa, forward.move, and side.move, but may also contain as many other variables as desired. Note that forward.move and side.move should give forward and sideways speeds relative to the specified direction in meters per second and should already account for the animal's own airspeed.

If calibrate.dir is TRUE, the animal will adjust its direction at each evaluation.interval if necessary to reorient to its end.loc. The new direction is calculated according to the specification of path. If calibrate.dir is FALSE and path is not numeric, the direction to the end.loc is calculated before take-off but not again during the simulation. If path is 'loxodrome', the rhumb line or constant compass direction is calculated to the end.loc. See NCEP.loxodrome. If path is 'great.circle', the angle describing the shortest path to the end.loc is calculated using earth.bear. A warning is issued if path is numeric and calibrate.dir is TRUE.

If calibrate.alt is TRUE, the animal will select at each evaluation.interval from levels2consider the most supportive flow conditions according to the specified flow.assist equation. If calibrate.alt is FALSE and the length of levels2consider is greater than one, the animal will select from levels2consider the most supportive flow conditions according to the specified flow.assist equation only when initiating the simulation and will continue using conditions at that level thereafter.

If the list passed to when2stop includes the character strings 'latitude' or 'longitude' the simulation will stop when the latitude or longitude, respectively, of the end.loc is reached. A numeric argument passed to the when2stop list indicates a distance from the end.loc in kilometers at which to stop the simulation. The simulation will end when any of the when2stop arguments are satisfied.

The argument query indicates whether or not to use NCEP.interp to retrieve wind data from the NCEP database via the Internet. This is intended to facilitate the use of flow conditions from sources other than NCEP. For example, one could use the time and location of the animal at each timestep to retrieve data from an oceanic dataset or an atmospheric dataset with higher resolution than NCEP. Alternatively, one could examine the trajectory of an animal that encounters consistent flow conditions of a given intensity for its entire journey. Since the user supplies the flow information, there is no need to query wind data from NCEP, and the function will run much faster. See the examples for a demonstration.

A data.frame containing at least the flow-assistance (i.e. fa), forward.move, and side.move each in meters per second.

Michael U. Kemp mukemp+RNCEP@gmail.com

To cite package 'RNCEP' in publications use:

Kemp, M. U., van Loon, E. E., Shamoun-Baranes, J., and Bouten, W. 2011. RNCEP:global weather and climate data at your fingertips. – Methods in Ecology and Evolution. DOI:10.1111/j.2041-210X.2011.00138.x.

For more information on flow-assistance and NCEP.flight see:

Kemp, M.U., Shamoun-Baranes, J., van Loon, E. E., and Bouten, W. 2012. Quantifying flow-assistance and implications for movement research. – Journal of Theoretical Biology. In prep.

library(RNCEP)
## Use NCEP.flight(), to simulate a flight over the North Sea 
## from Norway to the Netherlands using NCEP wind data
## queried automatically from the NCEP Reanalysis datset ##
## Not run: tst <- NCEP.flight(beg.loc=c(58.00,7.00), 
  end.loc=c(53.00,7.00), begin.dt='2007-10-01 18:00:00',
  flow.assist='NCEP.Tailwind', fa.args=list(airspeed=12),
  path='loxodrome', calibrate.dir=FALSE, calibrate.alt=FALSE,
  cutoff=0, when2stop='latitude', levels2consider=c(850,925),
  hours=12, evaluation.interval=60, id=1, land.if.bad=FALSE,
  reanalysis2 = FALSE)
## End(Not run)
  

#######################################################
## Use NCEP.flight(), to simulate a flight without 
## querying the NCEP database.  In this case, we use
## constant wind conditions (i.e. u=2 and v=0). ##
tst2 <- NCEP.flight(beg.loc=c(58.00,7.00), end.loc=c(53.00,7.00), 
  begin.dt='2007-10-01 18:00:00', flow.assist='NCEP.Tailwind', 
  fa.args=list(u=2, v=0, airspeed=12), path='loxodrome',
  calibrate.dir=TRUE, calibrate.alt=FALSE, cutoff=-10, when2stop='latitude', 
  levels2consider=850, hours=12, evaluation.interval=60, 
  id=1, land.if.bad=FALSE, reanalysis2 = FALSE, query=FALSE)

#######################################################
## Use NCEP.flight(), to simulate a flight without 
## querying the NCEP database.  In this case, we use
## wind conditions that depend on the animal's location ##

## First create a flow assistance function that will
## generate u and v flow components based on the animal's
## location
## Note that to use the datetime and the animal's location,
## the function MUST have the arguments lat.x, lon.x, and dt.x
Ex.FA <- function(direction, lat.x, lon.x, dt.x, airspeed){
    deg2rad = pi/180
    rad2deg = 180/pi
    ## Generate U and V flow component based on lat and lon
    u.x <- sin(lat.x*deg2rad) 
    v.x <- cos(lon.x*deg2rad)
    ## Apply NCEP.Tailwind with generated flow data
    return(cbind(NCEP.Tailwind(u=u.x, v=v.x,
        direction=direction, airspeed=airspeed), u.x, v.x))
    }

## Now use the function we just created in NCEP.flight
## The location and datetime are passed to the flow-
## assistance function automatically as lat.x, lon.x, and dt.x
tst3 <- NCEP.flight(beg.loc=c(58.00,7.00), end.loc=c(53.00,7.00), 
  begin.dt='2007-10-01 18:00:00', flow.assist='Ex.FA', 
  fa.args=list(airspeed=12), path='loxodrome',calibrate.dir=TRUE, 
  calibrate.alt=FALSE, cutoff=-10, when2stop='latitude',
  levels2consider=850, hours=12, evaluation.interval=60, 
  id=1, land.if.bad=FALSE, reanalysis2 = FALSE, query=FALSE)

## Confirm that the U and V wind components were determined
## by the latitude and longitude at each timestep
sin(tst3$lat[3] * (pi/180)) == tst3$u.x[3]
cos(tst3$lon[7] * (pi/180)) == tst3$v.x[7]