move (version 4.2.5)

getMovebankLocationData: Download location data from Movebank as a table

Description

This function downloads the location data for one or several sensors of a study stored in Movebank.

Usage

# S4 method for numeric,numeric,character,MovebankLogin
getMovebankLocationData(study, sensorID, animalName, login, ...)
# S4 method for numeric,numeric,numeric,MovebankLogin
getMovebankLocationData(study, sensorID, animalName, login,
                        includeOutliers=FALSE, underscoreToDots=TRUE, ...)

Value

'data.frame'

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

sensorID

character or numeric. Name or ID number of sensor(s) recording location data. A single sensor or a vector of sensors can be specified. If the argument is left empty data of all location sensors will be downloaded. Optional. See 'Details'.

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. If the argument is left empty data of all individuals will be downloaded. Optional.

includeOutliers

logical. If TRUE locations marked as outliers in Movebank will be included. Default is FALSE.

underscoreToDots

logical. Many of the functions in the Move package rely on the column names containing dots and not underscores. Default is TRUE. 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.

Author

Anne Scharf

Details

getMovebankLocationData belongs to the Movebank browsing functions and returns a data.frame with data from one or multiple location sensors from studies with one animal or multiple animals.
Remember that you need an account on Movebank, see movebankLogin.
Note that getMovebankData has also the option to download location data directly into a move/moveStack object.

Attribute names:
The definitions of the content of the columns of the returned data.frame is detailed in the Attribute Dictionary on Movebank. The attributes deployment_id, individual_id, tag_id, study_id correspond to the internal ids of Movebank.

sensorID:
See getMovebankSensors to obtain all available sensors of the study of interest. The valid names for this argument are those of the the columns "name" or "id" of the table returned by getMovebankSensors(login). The valid numeric Ids are also in the column "sensor_type_id" in the table returned for a specific study with getMovebankSensors(study,login). This function only accepts location sensors which are marked as "true"" in the "is_location_sensor" column of the table returned by getMovebankSensors(login).

underscoreToDots:
.csv files downloaded from the Movebank webpage contain dots in their column names, and .csv files downloaded via the API (like in the case of this function) contain instead underscores in their column names. Many of the functions in the Move package were created based on the webpage csv downloaded data and rely on the column names with dots. If you would like to use function like e.g. getDuplicatedTimestamps or read in the csv file with move by stating the path to file, among others, than the column names have to be with dots.

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.

See Also

movebankLogin, getMovebankData, getMovebankNonLocationData

Examples

if (FALSE) {
## first create the login object 
login <- movebankLogin()

## get GPS data for one individual
str(getMovebankLocationData(study=74496970, sensorID="GPS",
                               animalName="DER AR439", login=login))

## get GPS data for one individual after the "2013-07-12 06:50:07.000"
str(getMovebankLocationData(study=74496970, sensorID="GPS", animalName="DER AR439", 
                               login=login, timestamp_start="20130712065007000"))

# get GPS data for all individuals of the study between 
# the "2013-08-15 15:00:00.000" and "2013-08-15 15:01:00.000"
str(getMovebankLocationData(study=74496970, sensorID=653, 
                               login=login, timestamp_start="20130815150000000", 
                               timestamp_end="20130815150100000"))
}