Package move. July 7, 2015

Transcription

1 Type Package Package move July 7, 2015 Title Visualizing and Analyzing Animal Track Data Version Date Author Bart Kranstauber Maintainer Bart Kranstauber Contains functions to access movement data stored in movebank.org as well as tools to visualize and statistically analyze animal movement data, among others functions to calculate dynamic Brownian Bridge Movement Models. Move helps addressing movement ecology questions. License GPL (>= 3) URL LazyLoad yes Depends geosphere (>= 1.4-3), methods, sp, raster (>= ), rgdal, R (>= ) Suggests RCurl, adehabitathr, adehabitatlt, circular, ggmap, mapproj, maptools, testthat NeedsCompilation yes Repository CRAN Date/Publication :11:01 R topics documented: move-package UD-class unUsedRecords angle as.data.frame brownian.bridge.dyn brownian.motion.variance.dyn burst

2 2 R topics documented: burstid citations contour coordinates corridor DBBMM-class DBBMMStack-class dbgbvariance-class dbmvariancetmp distance dynbgb dynbgb-class dynbgbvariance equalproj getmotionvariance getmovebank getmovebankanimals getmovebankdata getmovebankid getmovebanksensors getmovebanksensorsattributes getmovebankstudies getmovebankstudy getvolumeud hrbootstrap iddata interpolatetime leroy lines move Move-class move2ade movebanklogin MovebankLogin-class MoveBurst movestack MoveStack-class n.indiv n.locs outerprobability plot plotbursts points raster raster2contour ricky searchmovebankstudies seglength

3 move-package 3 sensor show speed split sptransform subset-method summary time.lag timelag timestamps timesummary trackid turnanglegc unusedrecords< Index 67 move-package An overview of the functions in this package Details move is a package that contains functions to access movement data stored at as well as tools to visualize and statistically analyse animal movement data. Move addresses movement ecological questions. The package implements classes for movement data and supports Creation of Move objects (see Move-class) representing animals and their track Calculation of utilization distributions using the dynamic Brownian bridge Movement Model Plotting tracks, utilization distributions and contours Access to raster, n.col, projection and coordinates Different CRS projection methods such as longlat or aeqd I. Creating Move objects Move objects can be created from files with the function: move To create an object containing one animal track movestack To create an object containing multiple move objects getmovebankdata To create a Move or a MoveStack object with data from Movebank II. Calculation of the utilization distribution With the function below the dynamic Brownian Bridge Movement Model calculates the utilization density from a Move object:

4 4.UD-class brownian.bridge.dyn To calculate the utilization density III. Accessing values coordinates as.data.frame n.locs timelag projection Track-coordinates of the Move Object A data.frame with the important data of the Move Object The number of locations The time lags between the locations The projection method of the track/raster IV. Plotting data The track or the utilization distribution can be plotted with the following functions: plot or the track (see Move-class) image contour plots the utilization distribution with fixed width and height ratio (see DBBMM-class) plots the utilization distribution fitted to the window adds the contours of utilization distribution to a plot Bart Kranstauber, Maintainer: Bart Kranstauber <bart.kranstauber@uni-konstanz.de>, < marco.smolla@postgrad.manch References Move package vignette move on CRAN.UD-class The UD class This Class represents a simple abstraction of the utilization distribution, UD, where all probabilities necessarily sum to one. It is exported for experienced user to program against.

5 .unusedrecords 5 Slots crs part of the Raster-class data part of the Raster-class extent part of the Raster-class file part of the Raster-class history part of the Raster-class names part of the Raster-class legend part of the Raster-class method stores the method that was used to calculate the utilization distribution (UD), e.g. dynamic Brwonian Bridge ncols part of the Raster-class nrows part of the Raster-class rotated part of the Raster-class rotation part of the Raster-class title part of the Raster-class z part of the Raster-class Bart Kranstauber.unUsedRecords.unUsedRecords and.unusedrecordsstack class The class.unusedrecords and.unusedrecordsstack is mostly an internal class that is made public to make inheritance easier. It is a basal class that stores unused records. Slots timestampsunusedrecords unused timestamps sensorunusedrecords unused sensor information dataunusedrecords further unused data

6 6 angle angle angle information from a track or track stack This function returns a summary about angle related measurements of a track or track stack. These are: average azimuth, variance of azimuth, standard error of azimuth. ## S4 method for signature.movetracksingle angle(x) ## S4 method for signature.movetrackstack angle(x) ## S4 method for signature.movetracksingle anglesummary(x) ## S4 method for signature.movetrackstack anglesummary(x) x Move or MoveStack object Value Angles in degrees load(system.file("extdata", "move.rdata", package="move"),.globalenv) ## Not run: stack <- movestack(list(leroy,leroy)) angle(leroy) #angles from a Move object angle(stack) #angles from a MoveStack object anglesummary(leroy) # summary of angle measures of a Move object anglesummary(stack) # summary of angle measures of a MoveStack object ## End(Not run)# failed on cran build

7 as.data.frame 7 as.data.frame Return a Data Frame Function to create a data.frame with the information of a spatial data frame contained in the Move object. ## S4 method for signature Move as.data.frame(x,...) x an object of the Move-class... additional arguments to be passed to or from methods Details as.data.frame extracts the sdf argument from a Move object (see Move-class) ## create a move object data <- move(system.file("extdata","leroy.csv.gz",package="move"))[99:150,] ## returns a data.frame with all information stored in the spatial data frame of the move object head(df <- as.data.frame(data)) brownian.bridge.dyn Creates a DBBMM object The brownian.bridge.dyn function uses a Move object (see Move-class) to calculate the utilization distribution, UD, of the given track. It uses the dynamic Brownian Bridge Movement Model (dbbmm) to do so. The dbbmm has the advantage over the other Brownian Bridge Movement Model that changes in behavior are accounted for. It does so by using the behavioral change point analysis in a sliding window. For details see references.

8 8 brownian.bridge.dyn brownian.bridge.dyn(object, raster, dimsize, location.error, margin=11, window.size=31, ext=.3, bbox=na,...) object an object of the Move-class raster a RasterLayer object or numeric value. A numeric value for raster is interpreted as the resolution of the square raster cells (in map units); the according raster will be calculated internally. If a RasterLayer is provided the brownian.bridge.dyn starts to calculate the UD based on that raster. dimsize numeric. dimsize is only used if raster is not set. dimsize is interpreted as the number of cells along the largest dimension of the track. The according raster will be calculated internally. Default is 10 location.error single numeric value or vector of the length of coordinates that describes the error of the location (sender/receiver) system in map units, or a character string with the name of the column containing the location error. margin window.size ext bbox Details The margin used for the behavioral change point analysis. The size of the moving window along the track. Larger windows provide more stable/accurate estimates of the brownian motion variance but are less well able to capture more frequent changes in behavior. Describes the amount of extension of the bounding box around the animal track. It can be numeric (same extension into all four directions), vector of two (first x, then y directional extension) or vector of four (xmin, xmax, ymin, ymax extension). Default is.25 (extends the bounding box by 25%). Only considered in combination with a numeric raster argument or the dimsize argument. vector with 4 numbers defining a bounding box for the raster... for additional arguments, for example bursttype which is a character vector with the name of burst type for which the UD needs to be calculates in case a bursted brownian bridge is calculated There are four ways to launch the brownian.bridge.dyn function which are as follows: 1. Use a raster A RasterLayer object is set for the raster argument which is then used to calculate the UD. 2. Set the cell size To set the cell size, set a numeric value for the raster argument without providing dimsize. The numeric raster argument is used as the cell sizes of the raster. 3. Set the number of cells (col/row) To set the number of cells along the largest dimension a numeric dimsize argument can be set. 4. Using default raster

9 brownian.bridge.dyn 9 When there are no values set, the default raster value is used to calculate and create a RasterLayer object, which is returned to the same function. Note: depending on the size of the area of interest, the default cell size value can result in a large number of cells which may take a very long time to calculate! The function prints an estimate of the size of the computational task ahead. This can give an indication of how long the computation is going to take. It should scale roughly linearly with the duration of the computations. In our experience 10e9 takes about a minute with an average laptop. There is one further argument that can be given: time.step. It correspond to the size of the timer intervals taken for every integration step (in minutes). If left NULL 15 steps are taken in the shortest time interval. Note Note that the first few and last few segments of the trajectory are omitted in the calculation of the UD since a lower number of estimates for the Brownian motion variance are obtained for those segments. Thanks to Ryan Nielson for making the BBMM package that served as an example for early versions of this code. Bart Kranstauber, References Kranstauber, B., Kays, R., LaPoint, S. D., Wikelski, M. and Safi, K. (2012), A dynamic Brownian bridge movement model to estimate utilization distributions for heterogeneous animal movement. Journal of Animal Ecology. doi: /j x ## create a move object data <- move(system.file("extdata","leroy.csv.gz",package="move"))[1:90,] ## change projection method to aeqd and center the coordinate system to the track data2 <- sptransform(data, CRSobj="+proj=aeqd +ellps=wgs84", center=true) ## create a DBBMM object dbbmm <- brownian.bridge.dyn(object=data2, location.error=12, dimsize=45, ext=.3, time.step=600, margin=15)

10 10 brownian.motion.variance.dyn brownian.motion.variance.dyn Calculates the dynamic brownian motion variance A function to calculate the dynamic brownian motion variance for a movement track. It can be used by advanced programmers to program against. ## S4 method for signature.movetracksingle,numeric,numeric,numeric brownian.motion.variance.dyn(object, location.error, window.size, margin) Value object An object of the Move-class, that can be used for variance calculation. It needs to be in a flat coordinate system. location.error A numeric vector with the location error. window.size margin The window size used for the variance calculation. The margin size used for variance calculation. An object of the type dbmvariance is returned Bart Kranstauber References Kranstauber, B., Kays, R., LaPoint, S. D., Wikelski, M. and Safi, K. (2012), A dynamic Brownian bridge movement model to estimate utilization distributions for heterogeneous animal movement. Journal of Animal Ecology. doi: /j x See Also brownian.bridge.dyn data <- move(system.file("extdata","leroy.csv.gz",package="move"))[1:80,] data2 <- sptransform(data, CRSobj="+proj=aeqd +ellps=wgs84", center=true) dbmvar <- brownian.motion.variance.dyn(object=data2, location.error=rep(23.5,n.locs(data2)), margin=13, window.size=31) dbmvar

11 burst 11 burst Bursting a track Bursting a track by specified variable ## S4 method for signature Move,character burst(x, f,...) x f a Move object a character, factor, or numeric that indicates how to burst the coordinates of a Move object. It must be one shorter than the number of locations, because there are always one less segments of a track than coordinates... not used Details The burst function bursts (divides) a track in segments that are specified by the burstids (e.g. behavioral annotations). It allows to investigate different parts of a track according to supplied variables like day and night, movement and rest, and so on. test <- move(system.file("extdata","leroy.csv.gz", package="move")) behav <- c(rep(1:4,each=200), rep(5, 118)) testb <- burst(x=test, f=behav) head(testb)

12 12 citations burstid Returns burstid Obtain a factor returning the ids of behavioral categorization per segment ## S4 method for signature MoveBurst burstid(x) x a MoveStack object Value Returns a factor indicating the categorization Bart Kranstauber load(system.file("extdata", "move.rdata", package="move"),.globalenv) bursttrack <- burst(leroy,months(timestamps(leroy))[-1]) burstid(bursttrack) citations Extract the citation of a Move or MoveStack object The citations method returns or sets the citation of a track from a Move or MovesStack object. ## S4 method for signature.movegeneral citations(obj) ## S4 replacement method for signature.movegeneral citations(obj) <- value

13 contour 13 obj value Move or MoveStack object citation from class character load(system.file("extdata", "move.rdata", package="move"),.globalenv) stack <- movestack(list(leroy,leroy)) citations(leroy) #get the citation from a Move object citations(stack) #get the citation from a MoveStack object citations(leroy) <- "No paper available" #change the citation and set it for a Move object citations(stack) <- "Nothing to cite" #change the citation and set it for a MoveStack object contour Contour plot Contour plot of a RasterLayer from a DBBMM object. ## S4 method for signature.ud contour(x,...) ## S4 method for signature.udstack contour(x,...) x Details an object of the DBBMM-class or DBBMMStack-class... additional arguments like levels and nlevels, see details The contour function creates a shape of the area in which the animal can be found by a certain probability (i.e. the 90% contour describes the area in which the animal can be found with the 90% probability). One or several probabilities can be set with levels (numeric or vector of values between 0 and 1). If no value is set all contour lines are returned. You can also use nlevel to set a number of fixed distance levels. To change parameters of the contour or line plotting use the usual parameters of the plot function (like lwd, lty, and so on). You can also add the contour lines to a plot by adding add = TRUE.

14 14 coordinates load(system.file("extdata", "move.rdata", package="move"),.globalenv) ## to add a 50% and 95% contour to a plot from DBBMM object dbbmm plot(leroydbbmm) contour(leroydbbmm, levels=c(.5,.95), add=true) coordinates Extract the track coordinates from a Move/MoveStack object The coordinates method extracts the coordinates of a track. ## S4 method for signature Move coordinates(obj,...) obj A valid Move or MoveStack object... Additional arguments, see Details Details Returns a matrix with the coordinates of the track in a Move or MoveStack object. ## create a move object data <- move(system.file("extdata","leroy.csv.gz",package="move")) ## extract the coordinates coords <- coordinates(data)

15 corridor 15 corridor Corridor Corridor identifies movement track segments whose attributes suggest corridor use behavior ## S4 method for signature.movetracksingle corridor(x,speedprop=.75, circprop=.25, plot=false,...) ## S4 method for signature.movetrackstack corridor(x,speedprop=.75, circprop=.25, plot=false,...) x speedprop circprop plot Details Value Move or MoveStack numeric between 0 and 1, defines the proportion of speeds which are high enough to be a valid corridor point numeric between 0 and 1, defines the proportion of trajectories that are low enough to be a valid corridor point logical, if TRUE the track is plotted together with dots that indicate corridor points (color scale indicates how many corridor points are near by, less: blue, many: pink)... additional arguments like levels and nlevels, see details The corridor function uses the attributes of a movement step to identify movement steps that exhibit corridor use behavior. For each segment, the speed and the azimuth are calculated and assigned to the segment midpoint. A circular buffer is created around the midpoint of each segment whose radius is equal to half the segment length. The segment azimuth (180 >= azimuth > -180) is then converted into a new unit (the pseudo-azimuth 0 <= 360). Subsequent, the circular variance of the pseudo-azimuths of all segment midpoints that fall within the circular buffer are calculated. This identifies segments that are near parallel segments. Next, it is determined whether a segment s speed is higher than speedprop (by default the upper 25% speeds) and its circular variance is lower than circprop (by default the lower 25% of all variances). Segment midpoints that meet both of these requirements are considered as a corridor point, all others are considered non-corridor points. Finally, a corridor point is determined to be within a true corridor if within its buffer there are more corridor points than non-corridor points. The function returns a MoveBurst object or a list of MoveBurst objects (if a MoveStack is supplied). The MoveBurst dateframe stores the following information: - segment midpoint

16 16 DBBMM-class Note - speed - azimuth - pseudo-azimuth - circular variance The object is bursted by the factor that indicates whether a coordinate belongs to a corridor segment or not. The default values for the speedprop and circprop can be changed as per the users discretion using the according argument. If the result of the function is assigned to a variable a MoveBurst object is returned (see Value). References LaPoint, S., Gallery, P., Wikelski, M. and Kays, R. (2013), Animal Behavior, Cost-based Corridor Models, and Real Corridors. Landscape Ecology. doi: /s load(system.file("extdata", "move.rdata", package="move"),.globalenv) tmp <- corridor(leroy, plot=true) head(tmp) #if assigned to a variable, the coordinates are exported stack <- movestack(list(leroy[1:400,], ricky[1:500,])) stacktmp <- corridor(stack) #working with a stack DBBMM-class The DBBMM class Slots The DBBMM object is created within the brownian.bridge.dyn function from a Move object. It includes among others a raster object and probabilities. DBMvar Object of class "dbmvariancetmp": includes the window.size, margin, means, in.windows, break.list, and points of interest crs part of the Raster-class ext the extension factor set by the user data part of the Raster-class

17 DBBMMStack-class 17 extent part of the Raster-class file part of the Raster-class history part of the Raster-class legend part of the Raster-class method stores the method that was used to calculate the utilization distribution (UD), e.g. dynamic Brwonian Bridge ncols part of the Raster-class nrows part of the Raster-class rotated part of the Raster-class rotation part of the Raster-class title part of the Raster-class z part of the Raster-class Methods contour signature(object = "DBBMM"): adds a contour line to a plot image signature(object = "DBBMM"): plots the raster from a DBBMM object with fixed cell size ratio plot signature(object = "DBBMM"): plots the raster from a DBBMM object with re-size insensitive proportions proj4string signature(object = "DBBMM"): extracts the projection method of the raster stored within the DBBMM object raster signature(object = "DBBMM"): extracts the raster from the DBBMM object outerprobability signature(object = "DBBMM"): calculates the animal occurrence probabilities at the border of the raster DBBMMStack-class The DBBMMStack class The DBBMMStack object is created within the brownian.bridge.dyn function from a Move object. It includes among others a raster object and probabilities.

18 18 dbgbvariance-class Slots DBMvar Object of class "dbmvariance": includes the break.list and points of interest crs part of the Raster-class ext the extension factor set by the user extent part of the Raster-class filename part of the Raster-class layers part of the Raster-class method the method that was used to calculate the utilization distribution, e.g. dynamic Brwonian Bridge ncols part of the Raster-class nrows part of the Raster-class rotated part of the Raster-class rotation part of the Raster-class title part of the Raster-class z part of the Raster-class Methods contour signature(object = "DBBMMStack"): adds a contour line to a plot image signature(object = "DBBMMStack"): plots the raster from a DBBMMStack object with fixed cell size ratio plot signature(object = "DBBMMStack"): plots the raster from a DBBMMStack object with re-size insensitive proportions proj4string signature(object = "DBBMMStack"): extracts the projection method of the raster stored within the DBBMMStack object raster signature(object = "DBBMMStack"): extracts the raster from the DBBMMStack object outerprobability signature(object = "DBBMMStack"): calculates the animal occurrence probabilities at the border of the raster dbgbvariance-class Class to store the orthogonal and parallel variance This class stores the orthogonal and parellel variances calculated with the dynbgbvariance function.

19 dbmvariancetmp 19 dbmvariancetmp dbmvariancetmp class Slots The class dbmvariancetmp is mostly an internal class that is made public to make inheritance easier. It is a basal class that stores results of the dbbmm window.size The window size used for dbbmm calculation margin The margin used for dbbmm calculation means... in.windows... interest... break.list... distance distance information from a track or track stack DistanceSummary returns a summary of distance related measurements of a track or track stack, or for the distance function the distance between locations. ## S4 method for signature.movetracksingle distance(x) ## S4 method for signature.movetrackstack distance(x) ## S4 method for signature.movetracksingle distancesummary(x) ## S4 method for signature.movetrackstack distancesummary(x) x Move or MoveStack object

20 20 dynbgb Value All values are returned in meters if the projection of the coordinates is longlat, otherwise their in map units mostly meters as well. For longlat distance on a sphere is calculated using the ellipsoid else on a plane using Pythagoras. Check and set the projection of your Move or MoveStack object using the proj4string() function. load(system.file("extdata", "move.rdata", package="move"),.globalenv) stack <- movestack(list(leroy,leroy)) distance(leroy) #distances from a Move object distance(stack) #distances from a MoveStack object distancesummary(leroy) # summary of distance measures of a Move object distancesummary(stack) # summary of distance measures of a MoveStack object dynbgb Calculation of the dynamic Bivariate Gausian Bridge This function creates a utilization distribution according to the Bivariate Gaussian Bridge model. It returns an object of the class dynbgb-class. move raster locerr the move object or variance object used for calculating the ud if a.movetracksingle object is supplied this is converted into a dbgbvariance object using the dynbgbvariance function either the raster used for UD calculation or the resolution of the raster used for UD calculation the location errors used for the calculation Bart Kranstauber References Kranstauber, B., Safi, K., Bartumeus, F.. (2014), Bivariate Gaussian bridges: directional factorization of diffusion in Brownian bridge models. Movement Ecology 2:5. doi: /

21 dynbgb-class 21 data <- move(system.file("extdata","leroy.csv.gz",package="move")) [230:265,] ## change projection method to aeqd and center the coordinate system to the track dataaeqd <- sptransform(data, CRSobj="+proj=aeqd +ellps=wgs84", center=true) dbgb <- dynbgb(dataaeqd, locerr=9, raster=10, ext=2.15, windowsize=31, timestep=6, margin=15) plot(dbgb, col=hsv(sqrt(1:700/1000))) lines(dataaeqd) dynbgb-class dynbgb class This class stores the utilization density calculated using dynamic Bivariate Gausian Briges. It is an extention of the.ud class. Bart Kranstauber See Also.UD dynbgbvariance calculate variance for a track using a running window the function uses windowapply with the BGBvarbreak function in order to implement a dynaminc calculation of the variance

22 22 getmotionvariance equalproj Checks projections for being equal Checks whether all objects of a list are in the same projection ## S4 method for signature list equalproj(x) x a list of projected objects, like DBBMM or Raster objects, returning the projection string with with the function proj4string Details equalproj checks for equal projections using the function of identicalcrs from the package sp. It returns true if none of the objects have a proj4 string. Bart Kranstauber load(system.file("extdata", "move.rdata", package="move"),.globalenv) equalproj(list(leroydbbmm,leroydbbmm)) equalproj(list(leroy,leroydbbmm)) equalproj(list(leroy,ricky)) getmotionvariance Returns the estimated motion variance This function returns from an object where it has been calculated before getmotionvariance(x,...)

23 getmovebank 23 x... Currently un used A variance object or an UD object calculated using the dynamic Bivariate Gaussian Bridges or dynamic Brownian Bridges Bart Kranstauber See Also brownian.bridge.dyn, dynbgb load(system.file("extdata", "move.rdata", package="move"),.globalenv) getmotionvariance(leroydbbmm) getmotionvariance(dbbmmstack) getmovebank Creates an URL to download Data from Movebank An enhanced function to download data from Movebank by manually building an URL. This function should only be used by advanced programmers. getmovebank(entity_type, login,...) entity_type the entity_type of the data source login a MovebankLogin, if empty you ll be asked to enter your username or password... passing on additional arguments

24 24 getmovebankanimals getmovebankanimals Animals, tags and IDs in a Movebank study Returns the animals, their tags and IDs from a Movebank study getmovebankanimals(study, login) study login a character string (study name) or the numeric study ID as it is stored on Movebank an object of the MovebankLogin-class, if empty you ll be asked to enter your username or password Details getmovebankanimals belongs to the Movebank browsing functions and returns a data.frame that includes the animalid, animalname, id, sensor_type_id and tag_id from the requested study. Note See the browsemovebank vignette (move website download section) for more information about security and how to use Movebank from within R. ## Not run: getmovebankanimals(study=82207, login=login) ## End(Not run)