\documentclass[article,nojss]{jss}
\DeclareGraphicsExtensions{.pdf,.eps}
\newcommand{\fct}[1]{{\code{#1()}}}
\newcommand{\class}[1]{{`\code{#1}'}}
\SweaveOpts{engine = R, strip.white = true, keep.source = true, eps = false}

%\VignetteIndexEntry{Browsing Movebank using the move package}

\author{ Marco Smolla}
\Plainauthor{Marco Smolla}

\title{Browsing Movebank within R}
\Plaintitle{Functions to download data and information from Movebank}

\Keywords{movebank, move, R}

\Abstract{
  This vignette gives examples of how to browse the Movebank database within R and how to import data for the \pkg{move} package. It explains how to login, search for studies, get sensor types, animal and study IDs. Finally, it shows how to create a \texttt{move} object from a study to use it with the \pkg{move} package. \\
}

\Address{
  Marco Smolla\\
  Max-Planck-Institute for Ornithology, Radolfzell, Germany\\
  E-mail: \email{marco.smolla@postgrad.manchester.ac.uk}\\
}

\begin{document}
\SweaveOpts{concordance=TRUE}

\SweaveOpts{engine=R,eps=FALSE}

%\VignetteIndexEntry{How to use the move pacakge}
%\VignetteDepends{sp, raster, rgdal, methods, geosphere}
%\VignetteKeywords{GPS, time series, track}
%\VignettePackage{move}

<<preliminaries, echo=FALSE, results=hide>>=
library("move")
@

\section*{Introduction}
The provided functions allow you to search for studies stored in Movebank, browse them and download\footnote{If you have the rights to do so.} them. A possible workflow could look like this: \\ \\
1. Login to Movebank \\
2. Search for a study name and ID \\
3. Get information about the used tags and animals\\
4. Download the study data or create a \texttt{move} object\\



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Login to Movebank}
There are two ways to login. Either you login every time you use the functions that presented in this vignette. Or you use the \fct{movebankLogin} function to login to Movebank and create an object (a CURLHandle) that stores your login information. You can pass this object on to every function you use to skip the login process. Use your username and password which you use to login to web based Movebank. 

<<createCURLHandle, results=hide>>=
#curl <- movebankLogin(username="user", password="password")
@

\textbf{NOTE:} You can name the CURLHandle any way you want. It does not have to be \texttt{curl}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Search for a study name and ID}
You can use the \fct{searchMovebankStudies} function to search within the study names for a specific study. For example, if you want to find all studies that worked with goose try the following:

<<seatchMovebankStudies, results=hide>>=
#searchMovebankStudies(x="oose", login=curl)
@
You may rather use the search term without the first letter 'oose' instead of 'Goose' or 'goose', to find studies with both ways of writing. \\
All of the here presented studies can work with the study ID or the study name to find information within the database. If you rather want to work with the short study ID instead of the longer study name use \fct{getMovebankID}.

<<getMovebankID, results=hide>>=
#getMovebankID("BCI Ocelot",login=curl)
#> 123413
@

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Get information about the used tags and animals}
You found a study you are interested in, let's say 'BCI Ocelot'. To get more information about this study use:

<<getMovebankStudy, results=hide>>=
#getMovebankStudy(study="BCI Ocelot",login=curl)
@
If you want to know, which sensor types were used in this study you can use:

<<getMovebankSensors, results=hide>>=
#getMovebankSensors("BCI Ocelot",login=curl)
@

To see all available sensor types on Movebank use the same function without specifying x (\texttt{getMovebankSensors(,login=curl)}). Which attributes are available for the particular sensor you get listed if you use:

<<getMovebankSensorsAttributes, results=hide>>=
#getMovebankSensorsAttributes("BCI Ocelot",login=curl)
@

A list of the animals, their tags and IDs within this study is returned with this command:

<<getMovebankAnimals, results=hide>>=
#getMovebankAnimals(study="BCI Ocelot",login=curl)
@


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Download the study data or create a \texttt{move} object}
If you know which coordinates of which animal you want to download you can either download the timestamp and coordinates, or directly create a move object. 

<<getMovebankData, results=hide>>=
###Download timestamp and coordinates
#bobby <- getMovebankData(study="BCI Ocelot", animalName="Bobby", login=curl)

###Create a move object
#bobby <- getMovebankData(study="BCI Ocelot", animalName="Bobby", 
#                                               login=curl, moveObject=TRUE)
@

\end{document}
