Chapter 1 Introduction

This document is the official documentation for the R package IsoriX. It explains how to use IsoriX and provide information about the underlying methods. This document will keep evolving so to become progressively more complete and accurate. In early versions of IsoriX, the documentation was included as vignettes attached to the package, but we have decided to move the content here. That way we can put more things, better pictures and update the documentation independently from the package.

1.1 What is IsoriX?

IsoriX is an R package that can be used for building isoscapes and inferring the geographic origin of organisms based on their isotopic signature (Courtiol et al. 2019). This package employs a new statistical framework for doing all of this which is based on mixed models (GLMM). As most other packages dedicated to specific applications, IsoriX is essentially a simple interface to several other packages more general in scope. Specifically, it uses the package spaMM for fitting and predicting isoscapes, and for performing the assignment. IsoriX also heavily relies on the package rasterVis for plotting the maps using the powerful lattice visualization system. Knowing these packages is not necessary to handle IsoriX but it certainly helps for advance applications.

1.2 Who are we?

The IsoriX core Team is so far constituted by:

  • Alexandre Courtiol
  • François Rousset
  • Marie-Sophie Rohwaeder
  • Stephanie Kramer-Schadt

Alex does the programming for IsoriX. François does the programming for spaMM so to make IsoriX working always better. Alex and François are also the ones that have cooked up together the statistical framework behind IsoriX. Marie is a skilled master student who helped with Alex’s programming during an internship. Stephi is the person who initiated this project and who is spending a fair amount of time guiding IsoriX users. Alex, Marie and Stephi are all based in the Leibniz Institute for Zoo and Wildlife Research in Berlin (Germany). François is based at the Institut des Sciences de l’Evolution in Montpellier (France). We are indebted to other scientists who have helped us one way or another and the extended IsoriX family consists of all the authors of the main (upcoming) IsoriX publication (Courtiol et al. 2019):

print(citation(package = "IsoriX")[[1]], bibtex = FALSE)
## 
## Courtiol A, Rousset F, Rohwäder M, Soto DX, Lehnert L, Voigt CC, Hobson
## KA, Wassenaar LI, Kramer-Schadt S (2019). "Isoscape computation and
## inference of spatial origins with mixed models using the R package
## IsoriX." In Hobson KA, Wassenaar LI (eds.), _Tracking Animal Migration
## with Stable Isotopes_, second edition. Academic Press, London.

1.3 Who are you?

We don’t know all IsoriX users but we would love to! For us it is important to know who uses IsoriX in order to allocate best our efforts to make IsoriX better for those who use it. So please let us know about you by sending us a short email to alexandre.courtiol@gmail.com. If the population of users grow, we will create a special email address for IsoriX.

In this documentation we will try to please from the very newbie to the experienced users. We will however assume that you already know R a little bit. If it is not the case, you should read An Introduction to R or any other introduction to R before continuing. We will also assume that you all know a little bit about stable isotopes and isoscapes. For the stats bits, we will also assume that you now Generalized Linear Models and hopefully a little bit about mixed models too.

1.4 Wanna help?

If you want to help us to make IsoriX great, there are plenty things you could do! You could help us completing this documentation and you can also help us producing R code or revising existing code for IsoriX. You can also tell us what new features you would like, what you hate, what you think is buggy and so forth. To do all this, please use the GitHub interface https://github.com/courtiol/IsoriX. On these GitHub pages you will be able to access all the code and to leave feedbacks in the page called “Issues”. According to GitHub, new features are also considered as “issues” (for programmers it really makes sense actually).

1.5 Acknowledgements

Three mature and wise men have been instrumental in the conception of this project: Christian Voigt, Keith Hobson and Leonar Wassenaar. We thank them very much for their moral support and for never having given up on us.

1.6 About this book

We wrote this book in R Markdown and build it using the R package bookdown. All the R code used in this book ran within the following R session:

sessionInfo()
## R version 3.5.1 (2018-07-02)
## Platform: x86_64-apple-darwin15.6.0 (64-bit)
## Running under: macOS High Sierra 10.13.6
## 
## Matrix products: default
## BLAS: /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] Cairo_1.5-9      miniCRAN_0.2.11  kableExtra_0.9.0 knitr_1.20      
## [5] IsoriX_0.8.1    
## 
## loaded via a namespace (and not attached):
##  [1] zoo_1.8-3           xfun_0.3            pbapply_1.3-4      
##  [4] splines_3.5.1       lattice_0.20-35     colorspace_1.3-2   
##  [7] htmltools_0.3.6     viridisLite_0.3.0   yaml_2.2.0         
## [10] XML_3.98-1.16       rlang_0.2.2         hexbin_1.27.2      
## [13] pillar_1.3.0        sp_1.3-1            RColorBrewer_1.1-2 
## [16] stringr_1.3.1       munsell_0.5.0       rvest_0.3.2        
## [19] raster_2.6-7        codetools_0.2-15    evaluate_0.11      
## [22] latticeExtra_0.6-28 parallel_3.5.1      highr_0.7          
## [25] Rcpp_0.12.18        readr_1.1.1         backports_1.1.2    
## [28] scales_1.0.0        spaMM_2.4.35        hms_0.4.2          
## [31] digest_0.6.16       stringi_1.2.4       bookdown_0.7       
## [34] rasterVis_0.45      grid_3.5.1          rprojroot_1.3-2    
## [37] rgdal_1.3-4         tools_3.5.1         magrittr_1.5       
## [40] proxy_0.4-22        tibble_1.4.2        crayon_1.3.4       
## [43] pkgconfig_2.0.2     fda_2.4.8           MASS_7.3-50        
## [46] Matrix_1.2-14       xml2_1.2.0          rmarkdown_1.10     
## [49] httr_1.3.1          rstudioapi_0.7      R6_2.2.2           
## [52] igraph_1.2.2        nlme_3.1-137        compiler_3.5.1