getMovebank: Download Data from Movebank

Description

An enhanced function to download information of studies, animals, deployments and tags, and sensor measurements from Movebank. Many of the options of this function have been included as separate more user friendly functions listed in the See Also section below.

Usage

# S4 method for character,MovebankLogin
getMovebank(entity_type , login, ...)

Arguments

entity_type

character. The entity type to download from movebank, possible options are: "tag_type", "study", "tag", "individual", "deployment" or "event". See 'Details' for more information.

a MovebankLogin object, if empty you'll be asked to enter your username and password.

...

Arguments passed on to the Movebank API:

i_am_owner: logical. If TRUE all studies the user is a data manager for will be returned. Optional.
study_id: numeric. It is the Movebank ID of the study. It can be obtained on the Study Details page on Movebank or with getMovebankID.
individual_id: numeric. It is the internal individual Movebank identifier. A single individual or a vector of several individuals from the same study can be specified. It corresponds to the id values of getMovebank("individual", login, study_id). Optional.
deployment_id: numeric. It is the deployment Movebank identifier. A single deployment or a vector of several deployments from the same study can be specified. It corresponds to the id values of getMovebank("deployment", login, study_id). Optional.
sensor_type_id: numeric. It is the numeric id of the sensor type. A single sensor type or a vector of several sensor types can be specified. The corresponding numeric id for each sensor type can be found through getMovebank("tag_type", login). To obtain the sensor types available in the study use getMovebankSensors. Optional.
attributes: character. A single attribute or a vector of attributes can be specified. Optional. See 'Details' for more information.
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.

Value

'data.frame'

Details

getMovebank("tag_type", login): returns all sensor types in Movebank and their corresponding sensor id. See also getMovebankSensors.
getMovebank("study", login): returns all studies where the user has permission to see the data. You may have permission to see only the study details, view some or all tracks but not download data, or view and download some or all data. Also, there are studies that you do not have permission to see at all, these studies will not be included in this list. See also getMovebankStudies.
getMovebank("study", login, i_am_owner=T): returns all studies where the user is a data manager.
getMovebank("study", login, study_id): returns a summary of information about one or more studies. See also getMovebankStudy.
getMovebank("tag", login, study_id): returns tag reference information from a study.
getMovebank("individual", login, study_id)): returns animal reference information from a study. See also getMovebankAnimals.
getMovebank("deployment", login, study_id): returns deployment reference information from a study.
getMovebank("event", login, study_id,...): returns the sensor measurements from a study. See also getMovebankData, getMovebankNonLocationData.

The default columns of getMovebank("event", login,study_id,...) are timestamp, location_lat, location_long, individual_id, tag_id. If the downloaded study only contains GPS data, these default columns are suitable, but for all other sensors, additional columns are required. The columns available vary among sensor type and tag manufacturer, the complete list of available attributes for a specific study can be obtained with: unique(c(as.character(getMovebankSensorsAttributes(study, login=login)$short_name), 'sensor_type_id', 'deployment_id', 'event_id', 'individual_id', 'tag_id'))

The definitions of the content of the columns is detailed in the Attribute Dictionary on Movebank

Examples

Run this code

# NOT RUN {
## first create the login object 
login <- movebankLogin()

## get Movebank ID from study
studyID <- getMovebankID(study="MPIO white stork lifetime tracking data (2013-2014)", 
			 login=login)
studyID2 <- getMovebankID(study="BCI Ocelot", login=login)

## get a summary of information about the two studies
getMovebank("study", login=login, study_id=c(studyID,studyID2)) 

## get tag reference information from the study
head(getMovebank("tag", login=login, study_id=studyID))

## get animal reference information from the study
head(getMovebank("individual", login=login, study_id=studyID))

## get deployments reference information from the study
head(getMovebank("deployment", login=login, study_id=studyID))

## get the sensor measurements from the study
## find out which sensors were used in this study
unique(getMovebankSensors(study=studyID,login=login)$sensor_type_id)
## get movebank ID of one individual of this study
indID <- getMovebank("individual", login=login, study_id=studyID)$id[50]
## the correspondence table between the individual ID and the 
## animal names can be obtained like this
head(getMovebank("individual", login=login, 
		 study_id=studyID)[, c("id", "local_identifier")])

## get GPS and accelerometer data within a time period
## create a vector with attributes for all sensors included in the study
attrib <- unique(c(as.character(getMovebankSensorsAttributes(studyID, 
							     login=login)$short_name), 
		   'sensor_type_id', 'deployment_id', 'event_id', 
		   'individual_id', 'tag_id'))
## get measurments for a given time period, in this case for GPS and 
## accelerometer, and between "2013-06-25 03:55:00.000" and "2013-06-26 10:25:00.000"
getMovebank("event", login=login, study_id=studyID, sensor_type_id=c(653,2365683), 
	    individual_id=indID, attributes=attrib, timestamp_start="20130625035500000", 
	    timestamp_end="20130626102500000 ")

## get all GPS data for 2 individuals
## create a vector with attributes only for GPS data
attribs<-getMovebankSensorsAttributes(studyID, login)
attribGPS <- unique(c(as.character(attribs$short_name[attribs$sensor_type_id==653]), 
		      'sensor_type_id', 'deployment_id', 'event_id', '
		      individual_id', 'tag_id'))
indID2 <- getMovebank("individual", login=login, study_id=studyID)$id[35]
## get GPS measurements for these two individuals
head(storks <- getMovebank("event", login=login, study_id=studyID, 
			   sensor_type_id=653, individual_id=c(indID,indID2), 
			   attributes=attribGPS))

## create moveStack
## get the names of the individuals as they appear on Movebank
(individualNames <- getMovebank("individual", login=login, 
				study_id=studyID)[c(35,50), c("id", "local_identifier")])
head(storks2 <- merge(storks,individualNames,by.x="individual_id", by.y="id"))

myMoveStack <- move(x=storks2$location_long, y=storks2$location_lat,
		    time=as.POSIXct(storks2$timestamp, format="%Y-%m-%d %H:%M:%S", tz="UTC"),
		    data=storks2, 
		    proj=CRS("+proj=longlat +ellps=WGS84"), 
		    animal=storks2$local_identifier)

plot(myMoveStack, type="l")
# }

Run the code above in your browser using DataLab