% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/modelDiagnostics.R
\name{MESS3D}
\alias{MESS3D}
\title{Calculate MESS}
\usage{
MESS3D(calibration, projection)
}
\arguments{
\item{calibration}{A \code{data.frame} of environmental variables
used to calibrate an ecological niche model, one row for
measurements from each voxel included in the data used to
calibrate the model. Columns with names not corresponding to
\code{projection} \code{list} items are ignored.}

\item{projection}{A named \code{list} of \code{SpatRaster} objects for
projection; names correspond to \code{calibration} column names.
Each \code{SpatRaster} should have the same number of layers,
corresponding to vertical depth slices.}
}
\value{
A \code{SpatRaster} vector with MESS scores for each
voxel; layer names correspond to layer names of first
\code{SpatRaster} vector in \code{projection} \code{list}.
}
\description{
Calculates multivariate environmental similarity
surface based on model calibration and projection data
}
\details{
\code{MESS3D} is a wrapper around \code{MESS} from the \code{modEvA}
package. It calculates MESS for each depth layer. Negative values
indicate areas of extrapolation which should be interpreted with
caution (see Elith \emph{et al}, 2010 in \emph{MEE}).
}
\note{
The calibration dataset should include both presences
and background/pseudoabsence points used to calibrate an
ecological niche model.
}
\examples{
library(terra)
library(dplyr)

# Create sample rasterBricks
r1 <- rast(ncol=10, nrow=10)
values(r1) <- 1:100
r2 <- rast(ncol=10, nrow=10)
values(r2) <- c(rep(20, times = 50), rep(60, times = 50))
r3 <- rast(ncol=10, nrow=10)
values(r3) <- 8
envBrick1 <- c(r1, r2, r3)
names(envBrick1) <- c(0, 10, 30)

r1 <- rast(ncol=10, nrow=10)
values(r1) <- 100:1
r2 <- rast(ncol=10, nrow=10)
values(r2) <- c(rep(10, times = 50), rep(20, times = 50))
r3 <- rast(ncol=10, nrow=10)
values(r3) <- c(rep(c(10,20,30,25), times = 25))
envBrick2 <- c(r1, r2, r3)
names(envBrick2) <- c(0, 10, 30)

rastList <- list("temperature" = envBrick1, "salinity" = envBrick2)

# Create test reference set
set.seed(0)
longitude <- sample(ext(envBrick1)[1]:ext(envBrick1)[2],
                    size = 10, replace = FALSE)
set.seed(0)
latitude <- sample(ext(envBrick1)[3]:ext(envBrick1)[4],
                   size = 10, replace = FALSE)
set.seed(0)
depth <- sample(0:35, size = 10, replace = TRUE)
occurrences <- as.data.frame(cbind(longitude,latitude,depth))

# Sample data at occurrences to characterize calibration region
cal_temp <- xyzSample(occurrences, rastList$temperature)
cal_sal  <- xyzSample(occurrences, rastList$salinity)

calibration <- data.frame(
  temperature = cal_temp,
  salinity    = cal_sal)

# Run the function
messStack <- MESS3D(calibration = calibration, projection = rastList)
plot(messStack)

}
\references{
Elith J, Kearney M, and Phillips S. 2010.
The art of modelling range-shifting species.
\emph{Methods in Ecology and Evolution}, 1, 330-342.
}
\seealso{
\code{\link[predicts]{mess}}
}
\keyword{modelDiagnostics}
