Create a Move object — move • move

This function creates Move or MoveStack object from a .csv file with location data downloaded from a Movebank study, from a zip file downloaded from the EnvData (environmental annotation tool) of a Movebank study, from a ltraj, telemetry, track_xyt, track or binClstPath object or from own data. If you use your own data you need to set the projection method with the 'proj' argument and specify which columns of your data contain the coordinates and timestamps.

Usage

# S4 method for connection,missing,missing,missing,missing
move(x, removeDuplicatedTimestamps=F, ...)

# S4 method for ltraj,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for telemetry,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for track_xyt,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for list,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for track,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for binClstPath,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for binClstStck,missing,missing,missing,missing
move(x, y, time, data, proj,...)
# S4 method for data.frame,missing,missing,missing,missing
move(x, y, time, data, proj,...)

# S4 method for numeric,numeric,POSIXct,data.frame,CRS
move(x, y, time, data, proj, sensor='unknown',animal='unnamed',...)

Arguments

x: full path to the csv (or compressed) file location downloaded from a Movebank study, OR to the zip file location downloaded from the EnvData tool in Movebank.
a ltraj object from the package adehabitatLT.
a telemetry object or list of telemetry objects from the package ctmm.
a track_xyt object from the package amt.
a track object from the package bcpa.
a binClstPath or a binClstStck object from the package EMbC.
a data.frame object downloaded from Movebank webpage or with getMovebankLocationData.
numeric vector with x coordinates if non-Movebank data are provided (e.g. data$x).
y: numeric vector with y coordinates if non-Movebank data are provided (e.g. data$y).
time: vector of time stamps with POSIXct conversion if non-Movebank data are provided, i.e. as.POSIXct(data$timestamp, format="%Y-%m-%d %H:%M:%S", tz="UTC")
data: extra data associated with the relocations, if empty it is filled with the coordinates and timestamps. Optional.
proj: projection method for non-Movebank data; requires a valid CRS (see CRS-class) object, e.g. CRS("+proj=longlat +ellps=WGS84"); default is NA. Optional.
sensor: Sensor name(s), either single character or a vector with length of the number of coordinates. If multiple sensors are provided this has to be done as a vector with the same length as the number of coordinates. Optional.
animal: animal ID(s) or name(s), either single character or a vector with length of the number of coordinates. If multiple individuals are provided this has to be done as a vector with the same length as the number of coordinates. Optional.
removeDuplicatedTimestamps: logical; if TRUE duplicated timestamps values will be removed. Only available when reading in data from movebank via path to a .csv file. Using this argument will retain the first of multiple records with the same animal ID and timestamp, and remove any subsequent duplicates. See 'Note'.
...: Additional arguments

Details

The easiest way to import data is to download the study you are interested in from https://www.movebank.org and set the file path as the x argument of the move function. The function detects whether there are single or multiple individuals in this file and automatically creates either a Move, MoveStack object. See the 'browseMovebank' vignette for more information on how to directly download data from Movebank from within R.

Another way is to read in your data using read.csv. Then specify the arguments "x" and "y" the columns of your data containing the x and y coordinates, in the argument "time" the column containing the timestamp, optionally the columns containing the information of the sensor(s) used, the animal name(s) and the projection, as well as the whole data.frame of the imported data. If the argument "animal" is left empty or contains only the name of one animal the function will return a Move object. If the data contains multiple animal names the function will return a MoveStack object.

Note

It is checked whether the imported data set (via file path) is in a Movebank format. If your data isn't in a Movebank format, you have to use the alternative import for non-Movebank data reading in your data using read.csv and specifying which columns contain the needed information (see 'Details').

Locations with "NA":
Because the SpatialPointsDataFrame function that creates the spatial data frame of the Move object can not process NA location values, all rows with NA locations are stored as unused records in the Move object.

Duplicated timestamps:
When you are importing data from movebank (via path to .csv or .zip file) you can also set the argument "removeDuplicatedTimestamps=TRUE", which allows you delete the duplicated timestamps in case your data set contains them. Using this argument will retain the first of multiple records with the same animal ID and timestamp, and remove any subsequent duplicates. In case you want to control which of the duplicate timestamps are kept and which are deleted, we recommend to download the data as a .csv file from Movebank or to use the function getMovebankLocationData, find the duplicates using e.g. getDuplicatedTimestamps, decide which of the duplicated timestamp to retain, and than create a move/moveStack object with the function move. Another option is to edit the records in movebank and mark the appropriate records as outliers.

Naming:
Due to convention all names are turned into 'good names' which means, without spaces ('Ricky T' becomes 'Ricky.T'), if names are numbers a "X" will be prepended ('12345' becomes 'X12345') and most symbols will be replaced by "." ('Ricky-T' becomes 'Ricky.T').

Outliers:
In Movebank outliers can be marked manually or using filters, including a duplicate filter that flags duplicate records based on user-selected attributes, retaining the first record of each duplicate set that was imported to the study. These outliers will be marked with 'false' in the column 'visible', if data were downloaded including outliers.
When the move object is created by providing the path to the file downloaded from Movebank, the records marked as outliers are automatically placed in the UnusedRecords slots.
If these marked outliers want to be included in the move object, read in the data from the downloaded csv file from movebank with read.csv, set the marked outliers to 'true' in the column 'visible', or remove the column 'visible' from the data frame, save the table as a csv file and create the move object.

Multiple sensors:
If a move/moveStack object contains multiple sensors, this object can be separated into a move/moveStack object per sensor type:
x[x@sensor=="z"] where "x" is a Move or a MoveStack object, and "z" is the name of the sensor e.g. "GPS", "Radio Transmitter", etc.

Telemetry object with error calibration:
If the telemetry object (from ctmm) contains calibrated data, i.e. the GPS error has been calculated using the available tools in the ctmm package, the move object will contain an extra column in the data slot called error.loc.mts that will contain the error in meters for each location. This information can be used e.g. in the location.error argumet of the dynamic Brownian Bridge functions or the locErr argument of the Bivariate Gaussian Bridge functions.

Providing a data.frame object:
To read in a data.frame as a move/movestack object without specifying which arguments correspond to each argument, the data.frame is assumed to be downloaded from Movebank via the webpage or the getMovebankLocationData function. The function assumes a movebank format with the coordinates under the columns "location long" and "location lat" and projection lat/long; the timestamp under the column "timestamps" in the movebank format "%Y-%m-%d %H:%M:%S" and in timezone UTC; individual Id under the column "individual local identifier" and the sensor type under the column "sensor type".

Value

returns an object of class 'move' or 'moveStack'.

If data of Movebank are used, the definitions of the content of the columns within the @idData, @sensor, @data slots of the move or moveStack object is detailed in the Attribute Dictionary on Movebank

When the move or moveStack is created providing a path to a .csv or .zip file downloaded from Movebank the coordinates in the @coords slot are named "location.long" and "location.lat". When the move or moveStack is created by providing a data.frame, the coordinates in the @coords slot are named "coords.x1" and "coords.x2".

Author

Marco Smolla, Bart Kranstauber & Anne Scharf

Examples

## create a move object from a Movebank csv file
filePath<-system.file("extdata","leroy.csv.gz",package="move")
data <- move(filePath)

## create a move object from non-Movebank data
file <- read.table(filePath, header=TRUE, sep=",", dec=".")
data <- move(x=file$location.long, y=file$location.lat, 
       time=as.POSIXct(file$timestamp, format="%Y-%m-%d %H:%M:%S", tz="UTC"), 
       data=file, proj=CRS("+proj=longlat +ellps=WGS84"), 
       animal="Leroy", sensor="GPS")
#> Warning: There were NA locations detected and omitted. Currently they are not stored in unusedrecords
plot(data, type="b", pch=20)


## if the data contain multiple individuals a moveStack will be created
fishersPath<-system.file("extdata","fishersSubset.csv.gz",package="move")
fishersSubset <- read.table(fishersPath, header=TRUE, sep=",", dec=".")
data2 <- move(x=fishersSubset$location.long, y=fishersSubset$location.lat, 
             time=as.POSIXct(fishersSubset$timestamp,format="%Y-%m-%d %H:%M:%S", tz="UTC"), 
             data=fishersSubset, proj=CRS("+proj=longlat +ellps=WGS84"),
             animal=fishersSubset$individual.local.identifier,
             sensor=fishersSubset$sensor)
plot(data2, type="b", pch=20, col=c("green","blue")[data2@idData$individual.local.identifier])

plot(data2[[2]], type="l")


# \dontshow{
move(x=1:10,y=1:10,time=as.POSIXct(1:10, origin='1970-1-1'),proj=CRS('+proj=longlat +ellps=WGS84'))
#>    coordinates  x  y                time
#> 1       (1, 1)  1  1 1970-01-01 00:00:01
#> 2       (2, 2)  2  2 1970-01-01 00:00:02
#> 3       (3, 3)  3  3 1970-01-01 00:00:03
#> 4       (4, 4)  4  4 1970-01-01 00:00:04
#> 5       (5, 5)  5  5 1970-01-01 00:00:05
#> 6       (6, 6)  6  6 1970-01-01 00:00:06
#> 7       (7, 7)  7  7 1970-01-01 00:00:07
#> 8       (8, 8)  8  8 1970-01-01 00:00:08
#> 9       (9, 9)  9  9 1970-01-01 00:00:09
#> 10    (10, 10) 10 10 1970-01-01 00:00:10
move(x=1:10,y=1:10,time=as.POSIXct(c(1:5,1:5), origin='1970-1-1'),proj=CRS('+proj=longlat +ellps=WGS84'), animal=c(rep('a',5),rep('b',5)))# }
#>    coordinates  x  y                time
#> 1       (1, 1)  1  1 1970-01-01 00:00:01
#> 2       (2, 2)  2  2 1970-01-01 00:00:02
#> 3       (3, 3)  3  3 1970-01-01 00:00:03
#> 4       (4, 4)  4  4 1970-01-01 00:00:04
#> 5       (5, 5)  5  5 1970-01-01 00:00:05
#> 6       (6, 6)  6  6 1970-01-01 00:00:01
#> 7       (7, 7)  7  7 1970-01-01 00:00:02
#> 8       (8, 8)  8  8 1970-01-01 00:00:03
#> 9       (9, 9)  9  9 1970-01-01 00:00:04
#> 10    (10, 10) 10 10 1970-01-01 00:00:05