\documentclass[a4paper,12pt]{article}
\usepackage{graphicx}
\usepackage{Sweave}
\usepackage{subfigure}
\usepackage{float}
\usepackage{hyperref}
\usepackage[round]{natbib}
\hypersetup{
    unicode=false,
    pdftitle={ENiRG},
    pdfauthor={F. Canovas, C. Magliozzi, F. Mestre, J.A. Palazon \& M. Gonzalez-Wanguemert},
    pdfsubject={ENiRG},
    pdfcreator={},
    pdfproducer={},
    colorlinks=true,
    linkcolor=blue,
    citecolor=green,
    filecolor=magenta,
    urlcolor=blue}

\title{Ecological Niche in R-GRASS (ENiRG)}
\author{F. Canovas, C. Magliozzi, F. Mestre, \\ J.A. Palazon \& M. Gonzalez-Wanguemert}

%\VignetteIndexEntry{Ecological Niche Factor Analysis (ENFA) using ENiRG}

\begin{document}

\maketitle

\section{ENFA analysis using the command line}

\subsection{Data preparation}

Reading the package.
% Chunk 0
\begin{Schunk}
\begin{Sinput}
> library(ENiRG)
\end{Sinput}
\end{Schunk}

Importing species occurrence data from a data R file. Usually you will have a file with point locality data representing the known distribution of the studied species. Below is an example of the \textit{Apis mellifera} records stored in the list of class \textit{enirg} \citep{Canovas2002,Canovas2008,Canovas2014}.
%Chunk 1
\begin{Schunk}
\begin{Sinput}
> data(apis.enirg)
> lina <- apis.enirg$presences
> head(lina)
\end{Sinput}
\begin{Soutput}
        Long      Lat Lina
SXL -8.08555 41.90560    1
DJ  -3.31659 38.71414    2
BUR -8.55524 42.18557    2
AYO -1.05745 39.06090    2
MOn -0.61467 39.33986    2
XAB  0.10622 38.76471    3
\end{Soutput}
\end{Schunk}

 Maps are automatically uploaded to a GRASS session, which should be initiated previously (see function \textit{initGRASS} from \textit{rgrass7})
\begin{Schunk}
\begin{Sinput}
> initGRASS("/usr/bin/grass-7.0.0", home=tempdir())
> initGRASS("C:/GRASS", home=tempdir()) 
\end{Sinput}
\end{Schunk}

The ecogeographical variables should be stored in raster format. Almost all relevant formats can be used (check  \href{http://www.gdal.org/formats_list.html}{GDAL library} for compatibility). Qualitative and quantitative predictors should represent variables of interest for the species. Below an example of importing a set of raster maps in batch mode. If not specified, the output name of the uploaded file is set to the original one as default.
%Chunk 2
\begin{Schunk}
\begin{Sinput}
> predictor.names <- c("tann", "mxtwm", "mntcm",
>                      "rfann", "rfdm", "rfwm", "rfseas")
> predictor.maps <- paste("std_", predictor.names, sep="")
> file.names <- paste(system.file(package = "ENiRG"),
>                     "/ext/", predictor.names,
>                     ".asc", sep="")
> import.egvs(file.names, predictor.names)
\end{Sinput}
\end{Schunk}

Users can check metadata regarding the predictors and summarize the current settings of GRASS environment. The user can select the preferred format between the tabular of GRASS or the more terse R output.
%Chunk 3
\begin{Schunk}
\begin{Sinput}
> map.info(map.name="tann", format="r")
\end{Sinput}
\begin{Soutput}
$GISDBASE
[1] "/home/fcgarcia/grass"

$LOCATION_NAME
[1] "Apis"

$MAPSET
[1] "ENiRG"

$proj4
[1] "+proj=longlat +no_defs +a=6378137 +rf=298.257223563 +towgs84=0,0,0,0,0,0,0"

$extension
         value
north 44.27508
south 35.54605
east    3.5996
west  -9.98889
nsres  0.08999
ewres  0.08999
rows        97
cols       151
cells    14647

$statistics
                        value
n                      328382
null_cells             341394
cells                  669776
min         -1.10000002384186
max          18.6000003814697
range        19.7000004053116
mean         13.3138670858112
mean_of_abs  13.3141953620332
stddev       2.75747947653911
variance      7.6036930635344
coeff_var    20.7113339705622
sum          4372034.30137284

$class
[1] "metadata"
\end{Soutput}
\end{Schunk}

When making predictions, standardization of egv can be advantageous, finding the maximum likelihood estimates. If not specified, the output name of the standardized file will contain the prefix "std\_" plus the original name. More than one map can be standardized at the time.   
% Chunk 5
\begin{Schunk}
\begin{Sinput}
> stdz.maps(predictor.names, predictor.maps)
\end{Sinput}
\end{Schunk}

A list of available maps can be imported, also searching for a particular pattern.
% Chunk 4
\begin{Schunk}
\begin{Sinput}
> list.maps()
\end{Sinput}
\begin{Soutput}
$raster
 [1] "mntcm"      "mxtwm"      "rfann"      "rfdm"       "rfseas"    
 [6] "rfwm"       "std_mntcm"  "std_mxtwm"  "std_rfann"  "std_rfdm"  
[11] "std_rfseas" "std_rfwm"   "std_tann"   "tann"      

$vector
character(0)
\end{Soutput}
\end{Schunk}

\subsection{Configuring and running ENFA analysis}
The names for the ecogeographical variables should be parsed throughout the main function \textit{enirg} in a vector of names. In the following example the stanzardized map are used to perform the analysis.\footnote{NOTE: The names of the raster type files must correspond to the names of the ecogeographical variables already loaded into GRASS.}
% Chunk 6
\begin{Schunk}
\begin{Sinput}
> enirg(presences.table = lina, qtegv.maps = predictor.maps,
>       species.name = "African", nf = 1, scannf = FALSE,
>       method = "normal") -> apis.enfa
\end{Sinput}
\end{Schunk}

After setting predictor variables and occurrence points, the analysis can be run. You can use {\scriptsize scannf=TRUE} directly on R console to interactively choose the number of factors. NOTE: set load.map=FALSE and method="large" to perform the calculations over large data sets.
%Chunk 8

Results are returned into a list object.
%Chunk 9
\begin{Schunk}
\begin{Sinput}
> str(apis.enfa)
\end{Sinput}
\begin{Soutput}
List of 17
 $ call                : language enirg(presences.table = lina, qtegv.maps = predictor.maps, scannf = FALSE,      nf = 1, method = "normal", species.name = "African")
 $ nf                  : num 1
 $ cw                  : num [1:7] 1 1 1 1 1 1 1
 $ species             : chr "African"
 $ egvs                : chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
 $ qt.egvs             : chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
 $ ql.egvs             : NULL
 $ presences           :'data.frame':	135 obs. of  3 variables:
  ..$ Long: num [1:135] -8.086 -3.317 -8.555 -1.057 -0.615 ...
  ..$ Lat : num [1:135] 41.9 38.7 42.2 39.1 39.3 ...
  ..$ Lina: int [1:135] 1 2 2 2 2 3 3 3 3 3 ...
 $ total.marginality   : num 0.51
 $ marginalities       : num [1:7, 1] 0.4868 0.3239 0.3793 -0.2065 -0.0847 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
  .. ..$ : chr "Marginality"
 $ total.specialization: num 0.479
 $ specializations     : num [1:7, 1] -0.5291 -0.0127 0.0432 -0.4297 0.6483 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
  .. ..$ : chr "Spec1"
 $ co                  : num [1:7, 1:2] 0.4868 0.3239 0.3793 -0.2065 -0.0847 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
  .. ..$ : chr [1:2] "Mar" "Spec1"
 $ mar                 : Named num [1:7] 0.842 0.56 0.656 -0.357 -0.146 ...
  ..- attr(*, "names")= chr [1:7] "std_tann" "std_mxtwm" "std_mntcm" "std_rfann" ...
 $ m                   : num 2.99
 $ s                   : num [1:6] 6.022 2.355 1.157 1.053 0.673 ...
 $ obs.li              :'data.frame':	130 obs. of  4 variables:
  ..$ cat      : int [1:130] 1 2 3 4 5 6 7 8 9 10 ...
  ..$ presences: int [1:130] 1 2 2 2 2 3 3 3 3 3 ...
  ..$ li_Mar   : num [1:130] -0.318 1.32 0.429 1.221 2.013 ...
  ..$ li_Spec1 : num [1:130] 0.479 0.212 0.101 0.282 0.154 ...
  ..- attr(*, "na.action")=Class 'exclude'  Named int [1:5] 28 50 73 77 89
  .. .. ..- attr(*, "names")= chr [1:5] "28" "50" "73" "77" ...
 - attr(*, "class")= chr "enirg"
\end{Soutput}
\end{Schunk}

The user is able to plot the results of the factor analysis throughout the function \textit{enirg.plot}. (Figure \ref{Figure:Ordination}). NOTE: for large data set, method should be set to "simplified" (Figure \ref{Figure:Ordination}).
%Chunk 10
\begin{figure}[H]
\begin{center}
\begin{Schunk}
\begin{Sinput}
> enirg.plot(apis.enfa)
\end{Sinput}
\end{Schunk}
\includegraphics{figures/vignette-010}
\end{center}
\caption{ENFA ordination as obtained by setting method="extended".}
\label{Figure:Ordination}
\end{figure}

"li" maps for marginality and specialization/s can be plotted into R using \textit{raster} package (Figure \ref{Figure:li_Mar}). NOTE: not recommended for large data sets. Maps can be then viewed and managed through GRASS and QGIS.
\begin{figure}[H]
\begin{center}
%Chunk 12
\begin{Schunk}
\begin{Sinput}
> require(raster)
> plot(raster(readRAST("African_li_Mar")))
\end{Sinput}
\end{Schunk}
\includegraphics{figures/vignette-011}
\end{center}
\caption{Marginality factor.}
\label{Figure:li_Mar}
\end{figure}

Habitat suitability map can be calculated using \textit{enirg.predict}. If the user does not provide a new set of maps, the calculations will be done over the same ecogeographical variables, which were used to run \textit{enirg} function.
%Chunk 14
\begin{Schunk}
\begin{Sinput}
> enirg.predict(apis.enfa, load.map = TRUE,
>               method = "normal") -> apis.hsm
\end{Sinput}
\end{Schunk}

\begin{figure}[H]
\begin{center}
%Chunk 15
\begin{Schunk}
\begin{Sinput}
> plot(apis.hsm$African_predicted_hsm)
> contour(apis.hsm$African_predicted_hsm, add = TRUE)
\end{Sinput}
\end{Schunk}
\includegraphics{figures/vignette-015}
\end{center}
\caption{Non classified Habitat Suitability Map (HSM).}
\label{Figure:li_Mar}
\end{figure}

To perform Boyce continuous classification index, two vector objects are needed. First, a vector containing the predictions for our observations. It can be extracted from the list generated using \textit{predict.enirg()}
%Chunk 16
\begin{Schunk}
\begin{Sinput}
> data.pred.obs <- apis.hsm$predictions$predicted
\end{Sinput}
\end{Schunk}

Second, a vector containing all the prediction values for the entire area of study. It can be generated as follow:
%Chunk 17
\begin{Schunk}
\begin{Sinput}
> data.pred.map <- apis.hsm$African_predicted_hsm@data@values
\end{Sinput}
\end{Schunk}

, without non data values:
%Chunk 18
\begin{Schunk}
\begin{Sinput}
> data.pred.map <- data.pred.map[which(data.pred.map > 0)]
\end{Sinput}
\end{Schunk}

Finally, running the manual classification. NOTE: Try with the following intervals for the best classification fit:
\begin{itemize}
 \item unsuitable = 0.65
 \item marginal = 0.84
 \item suitable = 0.96
\end{itemize}
%Chunck 19
\begin{Schunk}
\begin{Sinput}
> boyce(data.pred.obs, data.pred.map)
\end{Sinput}
\end{Schunk}
\begin{figure}[H]
\begin{center}
\includegraphics[keepaspectratio=true, width=5cm]{figures/classification1.png}
\includegraphics[keepaspectratio=true, width=8cm]{figures/classification2.png} \\
\includegraphics[keepaspectratio=true, width=12cm]{figures/classification3.png}
\end{center}
\caption{Classification process.}
\label{Figure:Classification}
\end{figure}

Now, the user is able to reclassify the HSM map into the four suitability classes according to \citep{Boyce2002} (unsuitable, marginal, suitable, optimal).
\begin{Schunk}
\begin{Sinput}
> data(cbi.results)
> classify.map(map = "African_predicted_hsm", suit.classes = cbi.results,
+              output.name = "African_predicted_hsm_class",
+              load.map = TRUE) -> apis.hsm.class
\end{Sinput}
\begin{Soutput}
unsuitable   marginal   suitable 
      0.65       0.84       0.96 
1.280000 rounded up to 1
1.280000 rounded up to 1
1.350000 rounded up to 1
1.350000 rounded up to 1
1.440000 rounded up to 1
1.440000 rounded up to 1
African_hsm_class raster map was sucessfully classify!
Creating BIL support files...
Exporting raster as integer values (bytes=4)
 100%
\end{Soutput}
\end{Schunk}

The HSM can be plotted into R using \textit{raster} package (Figure \ref{Figure:HSM}). NOTE: maps can be also viewed and managed through GRASS and QGIS.
\begin{figure}[H]
\begin{center}
%Chunk 15
\begin{Schunk}
\begin{Sinput}
> plot(apis.hsm.class[[1]], legend = FALSE,
+      col = c("red", "yellow", "blue", "green"))
> contour(apis.hsm.class[[1]], add=T)
> legend("bottomright",
+        legend = c("unsuitable", "marginal", "suitable", "optimal"),
+        fill = c("red", "yellow", "blue", "green"))
\end{Sinput}
\end{Schunk}
\includegraphics{figures/vignette-018}
\end{center}
\caption{Habitat suitability map.}
\label{Figure:HSM}
\end{figure}

\section{Important note}
For Unix-based systems, \textit{method=''large''} option is also available, when using ENiRG for very large data sets. To use that functionality, the user should start GRASS in a appropriate mapset and then start R. Methods are the same as the ones used in this vignette.


\section{References}
\begin{thebibliography}{5}
 \bibitem[{Boyce \textit{et al}.(2002)}]{Boyce2002}
 Boyce, M.S.,Vernier, P.R.,Nielsen,S.E.,Schmiegelow, F.K.A. (2002). Evaluating resource selection functions. Ecological Modelling 157, 281-300.
 
 \bibitem[{Canovas \textit{et al}.(2002)}]{Canovas2002}
  Canovas, F., De la Rua, P. Serrano, J. and Galian, J. (2002). Mitochondrial DNA variability in Apis mellifera iberica populations from Galicia. Archivos de Zootecnia, 51: 441-448

 \bibitem[{Canovas \textit{et al}.(2008)}]{Canovas2008}
 Canovas, F., De la Rua, P. Serrano, J. and Galian, J. (2008). Geographical patterns of mitochondrial DNA variation in Apis mellifera iberiensis (Hymenoptera: Apidae). Journal of Zoological Systematics and Evolutionary Research, 46(1): 23-30

 \bibitem[{Canovas \textit{et al}.(2014)}]{Canovas2014}
 Canovas, F., De la Rua, P., Serrano, J. and Galian, J. (2014). Analysing and describing a contact area of two distinct evolutionary units. An ecological perspective. Journal of Insect Conservation, 18(5): 927-937

 \bibitem[{Canovas \textit{et al}.(2015)}]{Canovas2015}
 Canovas, F., Magliozzi, C., Mestre, F., Palazon-Ferrando, J.A. and Gonzalez-Wanguemert, M. (2015). ENiRG: R-GRASS interface for efficiently characterizing the ecological niche of species and predicting habitat suitability. Ecography. DOI: 10.1111/ecog.01426
\end{thebibliography}


\end{document}
