% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/IsoriX-package.R
\docType{package}
\name{IsoriX-package}
\alias{IsoriX-package}
\alias{IsoriX}
\title{Isoscape Computation and Inference of Spatial Origins using Mixed Models}
\description{
\pkg{IsoriX} can be used for building isoscapes using mixed models and
inferring the geographic origin of organisms based on their isotopic
signature. This package is essentially a simplified interface combining
several other packages which implements the statistical framework proposed by
Courtiol & Rousset 2017. It uses the package \pkg{spaMM} for fitting and
predicting isoscapes, and for performing the assignment. \pkg{IsoriX} also
heavily relies on the package \pkg{rasterVis} for plotting the maps produced
with the package \pkg{raster} using the powerful package \pkg{lattice}
visualization system.
}
\details{
Below, we describe briefly the main steps of the workflow that aims at
performing the construction of an isoscape and the assignment of organisms of
unknown geographic origin(s) based on their isotopic signature. We advise you
to also read the detailed book chapter we wrote (in press), as well as our
\href{https://bookdown.org/content/782/}{online documentation}, which essentially
cover the same material in a more detailed manner. You should also read the
dedicated help pages of the functions you are using.

The statistical methods will not be detailed in this document but information
on the computation of isoscapes is available in Courtiol & Rousset 2017, and
information on the calibration and assignment in the appendix of Courtiol et
al. 2019.

\enumerate{ \item Fitting the isoscape model with \link{isofit}:

The function \link{isofit} fits a geostatistical model, which
approximates the relationship between the topographic features of a location
and its isotopic signature (see \link{isofit} for details). The model
fits observations of isotopic delta values at several geographic locations
(hereafter, called \emph{sources}). One common type of sources used in
ecology is the delta values for hydrogen in precipitation water collected at
weather stations, but one may also use measurements performed on sedentary
organisms. In either case, the accuracy of the isoscape (and thereby the
accuracy of assignments) increases with the number and spatial coverage of
the sources. The function \link{isofit} is designed to fit the model
on data aggregated per location across all measurements. If instead you want
to fit the model on measurements split per time intervals (e.g. per month),
within each location, you should use the alternative function
\link{isomultifit}. Either way the data must be prepared using the
function \link{prepsources}.

\item Preparing the structural raster with \link{prepraster}:

Building isoscapes and assigning organisms to their origin requires an
adequate structural raster, i.e. a matrix representing a spatial grid. The
function \link{prepraster} allows restricting the extent of the raster
to the area covered by isoscape data (in order to avoid extrapolation) and to
reduce the resolution of the original structural raster (in order to speed up
computation in all following steps). Note that aggregating the raster may
lead to different results for the assignment, if the structural raster is
used to define a covariate. This is because the values of raster cells
changes depending on the aggregation function, which in turn will affect
model predictions.

We provide the function \link{getelev} to download an elevation raster
for the entire world at a resolution of one altitude per square-km, and other
rasters may be used. Such an elevation raster can be used as a structural
raster. We have also stored a low resolution raster for Germany in our
package (see \link{ElevRasterDE}) for users to try things out, but we
do not encourage its use for real application.

\item Predicting the isoscape across the area covered by the elevation raster
with \link{isoscape}:

The function \link{isoscape} generates the isoscapes: it uses the
fitted geostatistical models to predict the isotopic values (and several
variances associated to those) for each raster cell defined by the structural
raster. If the model has been fitted with \link{isomultifit}, you
should use the alternative function \link{isomultiscape} to generate
the isoscape.

Our package allows the production of fine-tuned isoscape figures (using the
function \link{plot.ISOSCAPE}). Alternatively, the isoscape rasters
can be exported as ascii raster and edited in any Geographic Information
System (GIS) software (see \link{isoscape} and the online
documentation for details).

\item Fitting the calibration model with \link{calibfit}:

In most cases, organisms are of another kind than the sources used to build
the isoscape (i.e. the isoscape is built on precipitation isotopic values and
organisms are not water drops, but e.g. the fur of some bats). In such a
case, the hydrogen delta values of the sampled organisms were modulated by
their distinct physiology and do not directly correspond to the isotopic
signature of the sources. In this situation, one must use sedentary organisms
to study the relationship between the isotopic values in organisms and that
of their environment. The function \link{calibfit} fits a statistical
model on such a calibration dataset.

If the isoscape is directly built from isotopic values of organisms, there is
no need to fit a calibration model.

\item Inferring spatial origins of samples with \link{isofind}:

The function \link{isofind} tests for each location across the
isoscape if it presents a similar isotopic signature than the unknown origin
of a given individual(s). This assignment procedure considered the some (but
not all, see Courtiol et al. 2019) uncertainty stemming from the model fits
(geostatistical models and calibration model). The function
\link{plot.ISOFIND} then draws such assignment by plotting the most
likely origin with the prediction region around it. When several organisms
are being assigned, both assignments at the level of each sample and a single
assignment for the whole group can be performed. }
}
\note{
Please note that the geographic coordinates (latitude,
longitude) of any spatial data (locations, rasters) must be given in decimal
degrees following the WGS84 spheroid standard.
}
\references{
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.

Courtiol A, Rousset F (2017). "Modelling isoscapes using mixed models." bioRxiv.
doi: 10.1101/207662, \href{https://www.biorxiv.org/content/10.1101/207662v1}{link}.
}
\author{
Alexandre Courtiol \email{alexandre.courtiol@gmail.com},

François Rousset,

Marie-Sophie Rohwaeder,

Stephanie Kramer-Schadt \email{kramer@izw-berlin.de}
}
\keyword{package}
