--- title: "m2b tutorial" author: "Laurent Dubroca, Andréa Thiebault" date: "`r Sys.Date()`" output: rmarkdown::html_vignette bibliography: bibliography.bib vignette: > %\VignetteIndexEntry{m2b tutorial} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r,echo=F} knitr::opts_chunk$set(dev='png') ``` #Introduction Animal behaviour, including social interactions, are fundamental to the field of ecology. Whereas the direct observation of animal behaviour is often limited due to logistical constraints, collection of movement data have been greatly facilitated through the development of bio-logging. Animal movement data obtained through tracking instrumentation may potentially constitute a relevant proxy to infer animal behaviour. This is, however, based on the premise that a range of movement patterns can be linked to specific behaviours. Statistical learning constitutes a number of methods that can be used to assess the link between given variables from a fully informed training dataset and then predict the values on a non-informed variable. We chose the random forest algorithm for its capacity to deal with imbalanced data (particularly relevant for behavioural data), its high prediction accuracy and its ease of implementation (@breiman2001b, @chen2004). The strength of random forest partly relies in its ability to handle a very large number of variables. Hence, our methodology is based on the derivation of multiple predictor variables from the movement data over various temporal scales, in order to capture as much information as possible on the changes and variations of movement. In this package we developed a method to link the movement patterns of animals with their behaviour, using the random forest algorithm. The specificity of this method relies on the derivation of multiple predictor variables from the movement data over a range of temporal windows. This procedure allows to capture as much information as possible on the changes and variations of movement and ensures the use of the random forest algorithm to its best capacity. The method is very generic, applicable to any dataset providing movement data together with observation of behaviour. This tutorial presents a new class named `xytb`, the functions that were implemented for the use of this package, and an example of application. The package can be installed using the CRAN system (`install.package("m2b")`), but the development version can be found on github (https://github.com/ldbk/m2b). #A new class `xytb` is a S4 class built to provide in a single object all the information associated to a track. This includes the tracking data (two dimension space coordinates, time and observed behaviours), the predictor variables derived from the movement data, the resulting model (to be used on other datasets) and the prediction (predicted behaviours on the given dataset). `xyt` relates to information about the movement data, and `b` to the behaviour. These information are contained into 8 slots, each of them deriving from different methods and functions (see Figure 1 for details). This object was created for the user to keep everything (data, model and prediction) in a single container,but also, by extension, for the user to (1) keep track of the precision of the model predictions and (2) exchange the analyses and results with different users easily. ![Schematic of the work flow from the raw data to the results. The `legend` box provides the symbolic representation (shape and color) of the different objects. The arrows between boxes represent the use of the package functions and methods: in blue the computation of the data, in red the modeling, in green the outputs and in pink the export to the ltraj format (adehabitat package). The diamond boxes inside the `xytb object` box represent the slots of the class (dotted lines link the xytb class and the slots). Diagram generated using Graphviz. ](diagramme.png) ```{r diag,warn=FALSE,cache=TRUE,echo=FALSE,eval=F,fig.cap="Schematic of the work flow from the raw data to the results. The `legend` box provides the symbolic representation (shape and color) of the different objects. The arrows between boxes represent the use of the package functions and methods: in blue the computation of the data, in red the modeling, in green the outputs and in pink the export to the ltraj format (adehabitat package). The diamond boxes inside the `xytb object` box represent the slots of the classi (dotted lines link the xytb class and the slots). Diagram generated using Graphviz."} DiagrammeR::grViz(width=800,height=800,diagram=" digraph rmarkdown { graph[center=true,ratio=auto,rankdir=TD,compound=true]; fieldwork[label='Fieldwork',color=white]; fieldwork->behaviour[lhead=cluster0]; fieldwork->descdata[lhead=cluster0]; fieldwork->track[lhead=cluster0]; subgraph cluster0{ track[label='track data']; behaviour[label='behavioural data']; descdata[label='meta data']; label = 'data'; } descdata->desc[fontcolor=blue,color=blue]; behaviour->b[fontcolor=blue,color=blue]; track->xyt[fontcolor=blue,color=blue]; subgraph cluster1 { xytb[label='class xytb',shape=diamond]; xytb-> desc[type=tee,style=dotted,dir=none]; xytb-> xyt[type=tee,style=dotted,dir=none]; xytb-> b[type=tee,style=dotted,dir=none]; xytb-> dxyt[type=tee,style=dotted,dir=none]; xytb-> befdxyt[type=tee,style=dotted,dir=none]; xytb-> model[type=tee,style=dotted,dir=none]; xytb-> rfcv[type=tee,style=dotted,dir=none]; xytb-> predb[type=tee,style=dotted,dir=none]; xyt->dxyt->befdxyt[color=blue,style=dashed]; b->model[color=red,style=dashed]; dxyt->model[color=red,style=dashed]; befdxyt->model[color=red,style=dashed]; model->predb[color=red,style=dashed]; rfcv->model[dir=both,color=red]; desc[shape=diamond,label='@desc:\nshort\ndescription'] xyt[shape=diamond,label='@xyt:\ntrack'] b[shape=diamond,label='@b:\nbehaviour'] dxyt[shape=diamond,label='@dxyt:\ntrack\nderivative'] befdxyt[shape=diamond,label='@befdxyt:\n@dxyt\nshifted'] model[shape=diamond,label='@model:\nrandom forest\nmodel'] rfcv[shape=diamond,label='@rfcv:\ncross validation\nof @model'] predb[shape=diamond,label='@predb:\nprediction of \n@b using @model'] label = 'xytb object'; } subgraph cluster3 { label='Results'; Plots[shape=box]; Tables[shape=box]; } xytb->Plots[color=green]; xytb->Tables[color=green]; ltraj[label='ltraj object',shape=diamond]; xytb->ltraj[color=pink,dir=both]; hmm[label='moveHMM object',shape=diamond]; xytb->hmm[color=pink,dir=both]; subgraph cluster100 { label='Legend' out[label='Output',shape=box]; R[label='R object',shape=diamond]; slot[label='slot',shape=diamond]; fun[label='Functions\n& Methods',color=white]; leg1[label='xytb()',color=blue,fontcolor=blue]; leg2[label='modelRF()',color=red,fontcolor=red]; leg3[label='resRF()\n resB()',color=green,fontcolor=green]; leg4[label='xytb2ltraj()\n ltraj2xytb()\n xytb2hmm()',color=pink,fontcolor=pink]; fun->leg1[color=blue]; fun->leg2[color=red]; fun->leg3[color=green]; fun->leg4[color=pink]; R->slot[style=dotted,dir=none]; file[label='Data']; } }") ``` #Methods and function overview The analytical procedure is summarized in 4 main functions and methods. For a full description of the use of the functions, please refer to the help provided for each function. ##`xytb` `xytb` is a class, but also a method. Used as a function `xytb` will calculte the predictor variables and store all the data in a newly created `xytb` object. 4 distinct signatures help the user to load trackings and behavioural data in the object. The data must be presented in a dataframe with locations in lines, and 5 variables in column: `x` the longitude, `y` the latitude, `t` the time in POSIXct format, `b` the observed behaviour and `id` the individual identification for the track. The function `xytb` can then be used with this dataframe as an input, so the predictor variables are calculated and stored in the slots `dxyt` and `befdxyt` of the `xytb` created object. For the calculation of predictor variables, three parameters can be set: - `winsize` specifies the sizes of sliding windows on which to compute the statistical operators, - `idquant` specifies the quantiles to be computed, - `move` (optional) specifies the number of points for the calculated variables to be shifted backward ( variables to be added to the ones calculated at the time). If included, the latter parameter will account for a delay between the reaction of the animal captured in the movement data, and its behaviour as recorded by the observer. In all cases, the original data are not modified, but derivated data are saved in the corresponding slots. ##`modelRF` This function computes a random forest model to predict the behavioural observations (response) from the movement data (predictors). This is a simple wrapper calling the randomForest function from the randomForest package (https://CRAN.R-project.org/package=randomForest). This function will update the `xytb` object and store the outputs in the slots `rfcv` (cross-validation for the choice of the parameter `mtry`), `model` (model itself) and `predb` (predictions). Cross-validation has to be done independently to set up the `mtry` parameters for the model. ##`resRF` and `resB` These two functions compute and plot the diagnostics and results of the model. The function `resRF` provides the error rate, the convergence of the model, a confusion matrix and the importance of variables. The function `resB` plots the predictions vs observations, over time or space. ##`xytb2ltraj` and `ltraj2xytb` These functions import or export a `xytb` object to an object of class `ltraj`. The latter is used in the `adehabitatLT` package where numerous function are dedicated to the analysis of trajectories (see @calenge2008). ##`xytb2hmm` This function import a `xytb` object to an object of class `moveHMM`. The latter is used in the `moveHMM` package which provides functions dedicated to the analysis of trajectories using hidden Markov models (see @michelot2016). #An example ##Data The data frame `track_CAGA_005` contains the tracking and behavioural data collected from a Cape gannet (\emph{Morus capensis}, Lichtenstein 1823). Tracking data include latitude, longitude and time (class POSIXct). Behavioural data include three states coded as '1' (bird diving), '2' (bird sitting on the water), '3' (bird flying), and a state `-1` for data points where the behaviour could not be observed. A state with no observation can be declared in some functions (`resB` for example) using the parameter `nob`, equal to '-1' in our case (see functions' help). ```{r data1,warn=FALSE,cache=TRUE,echo=TRUE} library(m2b) str(track_CAGA_005) ``` Different methods are available to build a `xytb` object. Here, the tracking and behavioural data are directly taken from the dataframe, and the predictor variables deriving from the tracking data are computed at the same time using the function `xytb`. The variables are computed over sliding windows of sizes 3, 5, 7, 9, 11, 13 and 15 locations (the `winsize` parameter). In addition to the standard statistical operators (mean, standard deviation and median absolute deviation), the quantiles at 0, 25, 50, 75 and 100\% are computed (the `idquant` parameter). All those values calculated can be then shifted in time to 5, 10 and 15 points backwards (the `move` parameter), if the user is interested to investigate the effect of the delay between the reaction of the animal captured in the movement data, and its behaviour as recorded by the observer. The rationale behind this operation is based on the fact that some change in movement can be triggered by behavioural observation made afterward by the scientist but sooner by the animal. ```{r data2,warning=FALSE,cache=TRUE,echo=TRUE} library(m2b) #convert to xybt object with computation of windows operators and some quantiles xytb<-xytb(track_CAGA_005,desc="example track", winsize=seq(3,15,2),idquant=seq(0,1,.25),move=c(5,10,15)) #a simple plot method plot(xytb) ``` #Modeling ##Model To build a random forest predicting the behavioural states based on the movement information, the function `modelRF` is used. It's a simple wrapper calling the `randomForest` function of the `randomForest` package, using the behavioural observation as response, and movement information as predictors. ```{r model1,warn=FALSE,cache=TRUE,echo=TRUE} #a model (the function modelRF updates the model inside the xytb object) xytb<-modelRF(xytb,type="actual",ntree=501,mtry=15) ``` ##Results Some diagnostic plots are available using the `resRF` function to check the fit of the model. In addition, the function `extractRF` can be used to export the resulting model to the `randomForest` format, so that other function from the `randomForest` package can be used to perform a deep analysis of the model. ```{r model2,warn=FALSE,cache=TRUE,echo=TRUE} resRF(xytb) resRF(xytb,"importance") resRF(xytb,"confusion") ``` The results regarding the behavioural states predicted vs the one observed are illustrated thanks to the `resB` functions. ```{r res1,warn=FALSE,cache=TRUE,echo=TRUE} resB(xytb,"time",nob="-1") resB(xytb,"space",nob="-1") resB(xytb,"density",nob="-1") ``` #Bibliography