% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diss_evaluate.R
\name{diss_evaluate}
\alias{diss_evaluate}
\alias{sim_eval}
\title{Evaluate dissimilarity matrices}
\usage{
diss_evaluate(diss, side_info)

sim_eval(d, side_info)
}
\arguments{
\item{diss}{A symmetric dissimilarity matrix. Alternatively, a vector
containing the lower triangle values (as returned by \code{\link[stats]{dist}}).}

\item{side_info}{A matrix of side information corresponding to the
observations. Can be numeric (one or more columns) or character (single
column for categorical data).}

\item{d}{Deprecated. Use \code{diss} in \code{diss_evaluate()} instead.}
}
\value{
A list with the following components:
\describe{
\item{eval}{For numeric side information: a matrix with columns
\code{rmsd} and \code{r} (correlation). For categorical: a matrix
with column \code{kappa}.}
\item{global_eval}{If multiple numeric side information variables are
provided, summary statistics across variables.}
\item{first_nn}{A matrix with the original side information and the
side information of each observation's nearest neighbor.}
}
}
\description{
\loadmathjax
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Evaluates a dissimilarity matrix by comparing each observation to its
nearest neighbor based on side information. For continuous variables,
RMSD and correlation are computed; for categorical variables, the kappa
index is used.
}
\details{
This function assesses whether a dissimilarity matrix captures meaningful
structure by examining the side information of nearest neighbor pairs
(Ramirez-Lopez et al., 2013). If observations that are similar in the
dissimilarity space also have similar side information values, the
dissimilarity is considered effective.

For numeric \code{side_info}, the root mean square of differences (RMSD)
between each observation and its nearest neighbor is computed:

\mjdeqn{j(i) = NN(x_i, X^{\{-i\}})}{j(i) = NN(x_i, X^{-i})}
\mjdeqn{RMSD = \sqrt{\frac{1}{m} \sum_{i=1}^{m} (y_i - y_{j(i)})^2}}{RMSD = sqrt(1/m sum (y_i - y_j(i))^2)}

where \mjeqn{NN(x_i, X^{-i})}{NN(x_i, X^{-i})} returns the index of the
nearest neighbor of observation \mjeqn{i}{i} (excluding itself),
\mjeqn{y_i}{y_i} is the side information value for observation \mjeqn{i}{i},
and \mjeqn{m}{m} is the number of observations.

For categorical \code{side_info}, the kappa index is computed:

\mjdeqn{\kappa = \frac{p_o - p_e}{1 - p_e}}{kappa = (p_o - p_e) / (1 - p_e)}

where \mjeqn{p_o}{p_o} is the observed agreement and \mjeqn{p_e}{p_e} is the
agreement expected by chance.
}
\examples{
\donttest{
library(prospectr)
data(NIRsoil)

sg <- savitzkyGolay(NIRsoil$spc, p = 3, w = 11, m = 0)
NIRsoil$spc <- sg

Yr <- NIRsoil$Nt[as.logical(NIRsoil$train)]
Xr <- NIRsoil$spc[as.logical(NIRsoil$train), ]

# Compute PCA-based dissimilarity
d <- dissimilarity(Xr, diss_method = diss_pca(ncomp = 8))

# Evaluate using side information
ev <- diss_evaluate(d$dissimilarity, side_info = as.matrix(Yr))
ev$eval

# Evaluate with multiple side information variables
Yr_2 <- NIRsoil$CEC[as.logical(NIRsoil$train)]
ev_2 <- diss_evaluate(d$dissimilarity, side_info = cbind(Yr, Yr_2))
ev_2$eval
ev_2$global_eval
}

}
\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 datasets. 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{dissimilarity}}, \code{\link{ncomp_by_opc}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
}
