% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/loi.R
\name{loi}
\alias{loi}
\title{Loss of Interpretability (LoI) Index}
\usage{
loi(O, O_hat, normalize = TRUE)
}
\arguments{
\item{O}{Proximity matrix from the ensemble model (n x n), values in the interval 0 to 1}

\item{O_hat}{Proximity matrix estimated by E2Tree (n x n), values in the interval 0 to 1}

\item{normalize}{Logical. If TRUE (default), returns nLoI (divided by M).
If FALSE, returns raw LoI.}
}
\value{
An object of class \code{"loi"} containing:
\item{loi}{Raw LoI value (unnormalized)}
\item{nloi}{Normalized LoI (LoI / M)}
\item{loi_in}{Within-node component (total)}
\item{loi_out}{Between-node component (total)}
\item{mean_in}{Per-pair average within-node loss (comparable with mean_out)}
\item{mean_out}{Per-pair average between-node loss (comparable with mean_in)}
\item{n}{Matrix dimension}
\item{m}{Number of unique pairs}
\item{n_within}{Number of within-node pairs}
\item{n_between}{Number of between-node pairs}
}
\description{
Computes the LoI index and its decomposition, measuring how well
the E2Tree-estimated proximity matrix reconstructs the original
ensemble proximity matrix.
}
\details{
The statistic is defined as:

\deqn{\mathrm{LoI}(O, \hat{O}) = \sum_{i < j}
  \frac{(o_{ij} - \hat{o}_{ij})^2}{\max(o_{ij}, \hat{o}_{ij})}}

The Normalized LoI divides by the number of pairs \eqn{M = n(n-1)/2}:

\deqn{\mathrm{nLoI}(O, \hat{O}) = \frac{1}{M} \mathrm{LoI}(O, \hat{O})}

The LoI decomposes into two components:
\itemize{
\item \strong{LoI_in}: within-node loss (pairs grouped together by E2Tree)
\item \strong{LoI_out}: between-node loss (pairs separated by E2Tree)
}
The per-pair averages \code{mean_in} and \code{mean_out} enable direct
comparison between the two components despite their different pair counts.

The statistic uses a normalized squared difference, where each cell's
contribution is weighted by the maximum of the two proximity values.
This gives more weight to discrepancies in high-proximity regions.

\strong{Decomposition interpretation (per-pair averages):}
\itemize{
\item \code{mean_out}: average ensemble proximity lost by the partition.
Low values (< 0.1) indicate the tree correctly separates low-proximity
pairs. High values (> 0.3) suggest the tree splits apart pairs that
the ensemble considers similar --more terminal nodes may help.
\item \code{mean_in}: average calibration error within nodes. Low values
(< 0.01) indicate excellent within-node reconstruction. Higher values
reflect the inherent fuzzy-to-crisp transition.
}
}
\examples{
\donttest{
data(iris)
smp_size <- floor(0.75 * nrow(iris))
set.seed(42)
train_ind <- sample(seq_len(nrow(iris)), size = smp_size)
training <- iris[train_ind, ]

ensemble <- randomForest::randomForest(Species ~ ., data = training,
  importance = TRUE, proximity = TRUE)

D <- createDisMatrix(ensemble, data = training, label = "Species",
  parallel = list(active = FALSE, no_cores = 1))

setting <- list(impTotal = 0.1, maxDec = 0.01, n = 2, level = 5)
tree <- e2tree(Species ~ ., training, D, ensemble, setting)

vs <- eValidation(training, tree, D)
prox <- proximity(vs)
O <- prox$ensemble
O_hat <- prox$e2tree

# Compute LoI with decomposition
result <- loi(O, O_hat)
print(result)
summary(result)
plot(result)

# Permutation test
perm <- loi_perm(O, O_hat, n_perm = 999, seed = 42)
print(perm)
plot(perm)
}

}
