getMovebankData: Download data from Movebank as a Move object
In move: Visualizing and Analyzing Animal Track Data

getMovebankData

R Documentation

Download data from Movebank as a Move object

Description

This function downloads the location data and timestamp of a study stored in Movebank as a move/moveStack object

Usage

## S4 method for signature 'numeric,character,MovebankLogin'
getMovebankData(study, animalName, login, ...)

## S4 method for signature 'numeric,numeric,MovebankLogin'
getMovebankData(study, animalName, login, 
                removeDuplicatedTimestamps=FALSE,
                includeExtraSensors=FALSE, deploymentAsIndividuals=FALSE,
                includeOutliers=FALSE,...)

Arguments

`study`	character or numeric. Character: full name of the study, as stored on Movebank. Numeric: Movebank ID of the study which can be obtained on the Study Details page on Movebank or with `getMovebankID`.
`login`	a `MovebankLogin` object, if empty you'll be asked to enter your username and password
`animalName`	character. Name of the individuals as stored on Movebank. A single individual or a vector of several individuals from the same study can be specified. Optional.
`includeExtraSensors`	logical; if TRUE data from non location sensors included in the study will be also downloaded, the data will automatically be stored in the unUsedRecords slot as they cannot produce locations. See 'Details'.
`removeDuplicatedTimestamps`	logical; if TRUE duplicated timestamps values will be removed. See 'Note'.
`deploymentAsIndividuals`	logical; if TRUE the deployments will be downloaded separately. See 'Details'.
`includeOutliers`	logical; if TRUE locations marked as outliers in Movebank will be included in the regular trajectory otherwise as unUsedRecords. See 'Details'
`...`	Additional arguments passed on to the movebank API through `getMovebank` function: `timestamp_start, timestamp_end` character or POSIXct. Starting and/or ending timestamp to download the data for a specific time period. Timestamps have to be provided in format 'yyyyMMddHHmmssSSS'. If POSIXct then it is converted to character using UTC as a time zone, note that this can change the time. Optional.

Details

getMovebankData belongs to the Movebank browsing functions and returns a Move object from studies with only one animal or a MoveStack object for studies with multiple animals.
Remember that you need an account on Movebank, see movebankLogin.

Attribute names:
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

includeExtraSensors:
If this includeExtraSensors=TRUE the data of all non location sensors (e.g. acceleration, magnetometer, etc) available in the study will be downloaded and stored in the unUsedRecords slot. Data from a single or a set of non location sensors can be also downloaded as a data.frame with the function getMovebankNonLocationData

deploymentAsIndividuals:
If single individuals have several deployments, and these are wished to be downloaded separately, this can be done by setting deploymentAsIndividuals=TRUE. In this case the "@trackId" will contain the names of the deployments.

idData:
The idData slot contains only the information of the animals. To obtain information on tags, deployments and sensors of the study use the function getMovebankReferenceTable.
When deploymentAsIndividuals=TRUE than the idData slot contains the information of the deployments.

Value

Object of class 'Move' or 'MoveStack'

Note

See the 'browseMovebank' vignette for more information about security and how to use Movebank from within R.

removeDuplicatedTimestamps:
It is possible to set 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.

includeOutliers:
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. When includeOutliers=FALSE (default) these records are automatically placed in the UnusedRecords slots. If includeOutliers=TRUE these records are included along all other locations. This option can be useful if the user wants to e.g. implement their own filter/algorithm to identify outliers. Entries that contain NAs in the coordinate columns will always be included in the UnusedRecords slots.

Multiple sensors:
The getMovebankData function downloads the data of all location sensors available in the study. If the study contains several location sensors, the resulting move/moveStack 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.

Downloading a study with many locations:
If the study to be downloaded has many locations (probably in the order of 10s of millions), the download may take so long that the connection breaks, and the study cannot be downloaded. We recommend to download each individual separately to ensure a successfully download. See more details and examples in the 'browseMovebank' vignette.

Author(s)

Marco Smolla & Anne Scharf

Examples

## Not run: 
# obtain a login
login<-movebankLogin()

# returns a MoveStack object from the specified study
getMovebankData(study="Ocelots on Barro Colorado Island, Panama", login=login) 

# returns a Move object (there is only one individual in this study)
getMovebankData(study="Coatis on BCI Panama (data from Powell et al. 2017)", login=login) 

# returns a MoveStack with two individuals
getMovebankData(study=123413, animalName=c("Mancha","Yara"), login=login) 

# Get a specific timerange, eg: all positions untill "2003-05-06 19:45:10.000"
(ocelots <- getMovebankData(study=123413, animalName=c("Mancha","Yara"), 
                            login=login, timestamp_end="20030506194510000"))

timestamps(ocelots)
## End(Not run)

move documentation built on Sept. 29, 2024, 9:06 a.m.