% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dissimilarity.R
\name{dissimilarity}
\alias{dissimilarity}
\title{Compute dissimilarity matrices}
\usage{
dissimilarity(Xr, Xu = NULL, diss_method = diss_pca(), Yr = NULL)
}
\arguments{
\item{Xr}{A numeric matrix of reference observations (rows) and variables
(columns).}

\item{Xu}{Optional matrix of additional observations with the same variables.}

\item{diss_method}{A dissimilarity method object created by one of:
\itemize{
\item \code{\link{diss_pca}()}: Mahalanobis distance in PCA space
\item \code{\link{diss_pls}()}: Mahalanobis distance in PLS space
\item \code{\link{diss_correlation}()}: Correlation-based dissimilarity
\item \code{\link{diss_euclidean}()}: Euclidean distance
\item \code{\link{diss_mahalanobis}()}: Mahalanobis distance
\item \code{\link{diss_cosine}()}: Cosine dissimilarity
}
Default is \code{diss_pca()}.}

\item{Yr}{Optional response matrix. Required for PLS methods and when using
\code{ncomp_by_opc()}.}
}
\value{
A list of class \code{"dissimilarity"} containing:
\describe{
\item{dissimilarity}{The computed dissimilarity matrix. Dimensions are
\code{nrow(Xr)} \mjeqn{\times}{x} \code{nrow(Xr)} when \code{Xu = NULL},
or \code{nrow(Xr)} \mjeqn{\times}{x} \code{nrow(Xu)} otherwise.}
\item{diss_method}{The \code{diss_*} constructor object used for computation.}
\item{center}{Vector used to center the data.}
\item{scale}{Vector used to scale the data.}
\item{ncomp}{Number of components used (for projection methods).}
\item{projection}{If \code{return_projection = TRUE} in the method
constructor, the \code{ortho_projection} object.}
}
}
\description{
\loadmathjax
Computes dissimilarity matrices between observations using various methods.
This is the main interface for dissimilarity computation in the resemble
package.
}
\details{
The function dispatches to the appropriate internal computation based on the
class of \code{diss_method}. Each method constructor (e.g., \code{diss_pca()})
encapsulates all method-specific parameters including component selection,
centering, scaling, and whether to return projections.

\subsection{Output dimensions}{
When only \code{Xr} is provided, the function computes pairwise dissimilarities
among all observations in \code{Xr}, returning a symmetric
\code{nrow(Xr)} \mjeqn{\times}{x} \code{nrow(Xr)} matrix.

When both \code{Xr} and \code{Xu} are provided, the function computes
dissimilarities between each observation in \code{Xr} and each observation
in \code{Xu}, returning a \code{nrow(Xr)} \mjeqn{\times}{x} \code{nrow(Xu)}
matrix where element \mjeqn{(i, j)}{(i, j)} is the dissimilarity between the
\mjeqn{i}{i}-th observation in \code{Xr} and the \mjeqn{j}{j}-th observation
in \code{Xu}.
}

\subsection{Mahalanobis distance}{
Note that \code{diss_mahalanobis()} computes Mahalanobis distance directly on
the input variables. This requires the covariance matrix to be invertible,
which fails when the number of variables exceeds the number of observations
or when variables are highly correlated (common in spectral data). For such
cases, use \code{diss_pca()} or \code{diss_pls()} instead.
}
}
\examples{
\donttest{
library(prospectr)
data(NIRsoil)

# Preprocess
sg <- savitzkyGolay(NIRsoil$spc, m = 1, p = 4, w = 15)

Xr <- sg[as.logical(NIRsoil$train), ]
Xu <- sg[!as.logical(NIRsoil$train), ]
Yr <- NIRsoil$CEC[as.logical(NIRsoil$train)]
Yu <- NIRsoil$CEC[!as.logical(NIRsoil$train)]

Xu <- Xu[!is.na(Yu), ]
Xr <- Xr[!is.na(Yr), ]
Yr <- Yr[!is.na(Yr)]

# PCA-based dissimilarity with variance-based selection
d1 <- dissimilarity(Xr, Xu, diss_method = diss_pca())

# PCA with OPC selection (requires Yr)
d2 <- dissimilarity(Xr, Xu,
  Yr = Yr,
  diss_method = diss_pca(
    ncomp = ncomp_by_opc(30),
    return_projection = TRUE
  )
)

# PLS-based dissimilarity 
d3 <- dissimilarity(
  Xr, Xu,
  Yr = Yr,
  diss_method = diss_pls(
    ncomp = ncomp_by_opc(30)
  )
)

# Euclidean distance
d4 <- dissimilarity(Xr, Xu, diss_method = diss_euclidean())

# Correlation dissimilarity with moving window
d5 <- dissimilarity(Xr, Xu, diss_method = diss_correlation(ws = 41))

# Mahalanobis distance (use only when n > p and low collinearity)
# d6 <- dissimilarity(Xr[, 1:20], Xu[, 1:20],
#                     diss_method = diss_mahalanobis())
}

}
\references{
Ramirez-Lopez, L., Behrens, T., Schmidt, K., Stevens, A., Dematte, J.A.M.,
Scholten, T. 2013a. The spectrum-based learner: A new local approach for
modeling soil vis-NIR spectra of complex data sets. Geoderma 195-196,
268-279.

Ramirez-Lopez, L., Behrens, T., Schmidt, K., Viscarra Rossel, R., Dematte,
J.A.M., Scholten, T. 2013b. Distance and similarity-search metrics for use
with soil vis-NIR spectra. Geoderma 199, 43-53.
}
\seealso{
\code{\link{diss_pca}}, \code{\link{diss_pls}},
\code{\link{diss_correlation}}, \code{\link{diss_euclidean}},
\code{\link{diss_mahalanobis}}, \code{\link{diss_cosine}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
}
