% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mbl.R
\name{mbl}
\alias{mbl}
\alias{plot.mbl}
\alias{get_predictions}
\title{Memory-based learning (mbl)}
\usage{
mbl(Xr, Yr, Xu, Yu = NULL,
    neighbors,
    diss_method = diss_pca(ncomp = ncomp_by_opc()),
    diss_usage = c("none", "predictors", "weights"),
    fit_method = fit_wapls(min_ncomp = 3, max_ncomp = 15),
    spike = NULL, group = NULL,
    gh = FALSE,
    control = mbl_control(),
    verbose = TRUE, seed = NULL, ...)

\method{plot}{mbl}(x, what = c("validation", "gh"), metric = "rmse", ncomp = c(1, 2), ...)

get_predictions(x)

\method{plot}{mbl}(x, what = c("validation", "gh"), metric = "rmse", ncomp = c(1, 2), ...)
}
\arguments{
\item{Xr}{A matrix of predictor variables for the reference data
(observations in rows, variables in columns). Column names are required.}

\item{Yr}{A numeric vector or single-column matrix of response values
corresponding to \code{Xr}. NA values are not permitted.}

\item{Xu}{A matrix of predictor variables for the data to be predicted
(observations in rows, variables in columns). Must have the same column
names as \code{Xr}.}

\item{Yu}{An optional numeric vector or single-column matrix of response
values corresponding to \code{Xu}. Used for computing prediction
statistics. Default is \code{NULL}.}

\item{neighbors}{A neighbor selection object specifying how to select
neighbors. Use \code{\link{neighbors_k}()} for fixed k-nearest neighbors
or \code{\link{neighbors_diss}()} for dissimilarity threshold-based
selection.}

\item{diss_method}{A dissimilarity method object or a precomputed
dissimilarity matrix. Available constructors:
\itemize{
\item \code{\link{diss_pca}()}: Mahalanobis distance in PCA score space.
This is the default where the number of components is optimized using
side information (see \code{ncomp_by_opc}()).
\item \code{\link{diss_pls}()}: Mahalanobis distance in PLS score space
\item \code{\link{diss_euclidean}()}: Euclidean distance
\item \code{\link{diss_mahalanobis}()}: Mahalanobis distance
\item \code{\link{diss_cosine}()}: Cosine dissimilarity
\item \code{\link{diss_correlation}()}: Correlation-based dissimilarity
}
A precomputed matrix can also be passed. When \code{diss_usage =
  "predictors"}, it must be square with dimensions
\code{(nrow(Xr) + nrow(Xu))} and zeros on the diagonal. Otherwise, it must
have \code{nrow(Xr)} rows and \code{nrow(Xu)} columns.}

\item{diss_usage}{How dissimilarity information is used in local models:
\itemize{
\item \code{"none"} (default): dissimilarities used only for neighbor
selection
\item \code{"predictors"}: local dissimilarity matrix columns added as
predictors
\item \code{"weights"}: neighbors weighted by dissimilarity using a
tricubic function
}}

\item{fit_method}{A local fitting method object. Available constructors:
\itemize{
\item \code{\link{fit_pls}()}: Partial least squares regression
\item \code{\link{fit_wapls}()}: Weighted average PLS (default)
\item \code{\link{fit_gpr}()}: Gaussian process regression
}}

\item{spike}{An integer vector indicating indices of observations in
\code{Xr} to force into (positive values) or exclude from (negative values)
all neighborhoods. Default is \code{NULL}. Spiking does not change
neighborhood size; forced observations displace the most distant neighbors.}

\item{group}{An optional factor assigning group labels to \code{Xr}
observations (e.g., measurement batches). Used to avoid pseudo-replication
in cross-validation: when one observation is held out, all observations
from its group are also removed.}

\item{gh}{Logical indicating whether to compute global Mahalanobis (GH)
distances. Default is \code{FALSE}. GH distances measure how far each
observation lies from the center of the reference set in PLS score space.
The computation uses a fixed methodology: PLS projection with the number
of components selected via \code{\link{ncomp_by_opc}()} (capped at 40).
This is independent of the \code{diss_method} argument.}

\item{control}{A list from \code{\link{mbl_control}()} specifying validation
type, tuning options, and other settings.}

\item{verbose}{Logical indicating whether to display a progress bar.
Default is \code{TRUE}. Not shown during parallel execution.}

\item{seed}{An integer for random number generation, enabling reproducible
cross-validation results. Default is \code{NULL}.}

\item{...}{Additional arguments (currently unused).}

\item{x}{An object of class \code{mbl} (as returned by \code{\link{mbl}}).}

\item{what}{Character vector specifying what to plot. Options are
\code{"validation"} (validation statistics) and/or \code{"gh"} (PLS scores
used for GH distance computation). Default is both.}

\item{metric}{Character string specifying which validation statistic to plot.
Options are \code{"rmse"}, \code{"st_rmse"}, or \code{"r2"}. Only used when
\code{"validation"} is in \code{what}.}

\item{ncomp}{Integer vector of length 1 or 2 specifying which PLS components
to plot. Default is \code{c(1, 2)}. Only used when \code{"gh"} is in
\code{what}.}
}
\value{
\subsection{mbl}{

For \code{mbl()}, a list of class \code{mbl} containing:
\itemize{
\item \code{control}: control parameters from \code{control}
\item \code{fit_method}: fit constructor from \code{fit_method}
\item \code{Xu_neighbors}: list with neighbor indices and dissimilarities
\item \code{dissimilarities}: dissimilarity method and matrix (if
\code{return_dissimilarity = TRUE} in \code{control})
\item \code{n_predictions}: number of predictions made
\item \code{gh}: GH distances for \code{Xr} and \code{Xu} (if
\code{gh = TRUE})
\item \code{validation_results}: validation statistics by method
\item \code{results}: list of data.frame objects with predictions, one per
neighborhood size
\item \code{seed}: the seed value used
}

Each results table contains:
\itemize{
\item \code{o_index}: observation index
\item \code{k}: number of neighbors used
\item \code{k_diss}, \code{k_original}: (\code{neighbors_diss} only)
threshold and original count
\item \code{ncomp}: (\code{fit_pls} only) number of PLS components
\item \code{min_ncomp}, \code{max_ncomp}: (\code{fit_wapls} only)
component range
\item \code{yu_obs}, \code{pred}: observed and predicted values
\item \code{yr_min_obs}, \code{yr_max_obs}: response range in neighborhood
\item \code{index_nearest_in_Xr}, \code{index_farthest_in_Xr}: neighbor
indices
\item \code{y_nearest}, \code{y_farthest}: neighbor response values
\item \code{diss_nearest}, \code{diss_farthest}: neighbor dissimilarities
\item \code{y_nearest_pred}: (NNv validation) leave-one-out prediction
\item \code{loc_rmse_cv}, \code{loc_st_rmse_cv}: (local_cv validation) CV
statistics
\item \code{loc_ncomp}: (local dissimilarity only) components used locally
}
}

\subsection{Get predictions}{

The \code{get_predictions()} function extracts predicted values from an
object of class \code{mbl}. It returns a \code{data.frame} containing the
predictions.
}
}
\description{
\loadmathjax
Memory-based learning (a.k.a. instance-based learning or local regression)
is a non-linear lazy learning approach for predicting a response variable
from predictor variables. For each observation in a prediction set, a local
regression is fitted using a subset of similar observations (nearest
neighbors) from a reference set. This function does not produce a global
model.
}
\details{
\subsection{Spiking}{

The \code{spike} argument forces specific reference observations into or out
of neighborhoods. Positive indices are always included; negative indices are
always excluded. When observations are forced in, the most distant neighbors
are displaced to maintain neighborhood size. See Guerrero et al. (2010).
}

\subsection{Dissimilarity usage}{

When \code{diss_usage = "predictors"}, the local dissimilarity matrix columns
are appended as additional predictor variables, which can improve predictions
(Ramirez-Lopez et al., 2013a).

When \code{diss_usage = "weights"}, neighbors are weighted using a tricubic
function (Cleveland and Devlin, 1988; Naes et al., 1990):

\mjdeqn{W_{j} = (1 - v^{3})^{3}}{W_j = (1 - v^3)^3}

where \mjeqn{v = d(xr_i, xu_j) / \max(d)}{v = d(xr_i, xu_j) / max(d)}.
}

\subsection{GH distance}{

The global Mahalanobis distance (GH) measures how far each observation lies
from the center of the reference set. It is always computed using a PLS
projection with the number of components optimized via
\code{\link{ncomp_by_opc}()} (maximum 40 components or \code{nrow(Xr)},
whichever is smaller). This methodology is fixed and independent of the
\code{diss_method} specified for neighbor selection.

GH distances are useful for identifying extrapolation: observations with
high GH values lie far from the calibration space and may yield unreliable
predictions.
}

\subsection{Grouping}{

The \code{group} argument enables leave-group-out cross-validation. When
\code{validation_type = "local_cv"} in \code{\link{mbl_control}()}, the
\code{p} parameter refers to the proportion of groups (not observations)
retained per iteration.
}

\subsection{Deprecated arguments}{

The following arguments from previous versions of \code{resemble} are no
longer supported and will throw an error if used: \code{k}, \code{k_diss},
\code{k_range}, \code{method}, \code{pc_selection}, \code{center},
\code{scale}, and \code{documentation}. See the current argument list for
their replacements.
}
}
\examples{
\dontrun{
library(prospectr)
data(NIRsoil)

# Preprocess: detrend + first derivative with Savitzky-Golay
sg_det <- savitzkyGolay(
  detrend(NIRsoil$spc, wav = as.numeric(colnames(NIRsoil$spc))),
  m = 1, p = 1, w = 7
)
NIRsoil$spc_pr <- sg_det

# Split data
test_x <- NIRsoil$spc_pr[NIRsoil$train == 0 & !is.na(NIRsoil$CEC), ]
test_y <- NIRsoil$CEC[NIRsoil$train == 0 & !is.na(NIRsoil$CEC)]
train_x <- NIRsoil$spc_pr[NIRsoil$train == 1 & !is.na(NIRsoil$CEC), ]
train_y <- NIRsoil$CEC[NIRsoil$train == 1 & !is.na(NIRsoil$CEC)]

# Example 1: Spectrum-based learner (Ramirez-Lopez et al., 2013)
ctrl <- mbl_control(validation_type = "NNv")

sbl <- mbl(
  Xr = train_x,
  Yr = train_y,
  Xu = test_x,
  neighbors = neighbors_k(seq(40, 140, by = 20)),
  diss_method = diss_pca(ncomp = ncomp_by_opc(40)),
  fit_method = fit_gpr(),
  control = ctrl
)
sbl
plot(sbl)
get_predictions(sbl)

# Example 2: With known Yu
sbl_2 <- mbl(
  Xr = train_x,
  Yr = train_y,
  Xu = test_x,
  Yu = test_y,
  neighbors = neighbors_k(seq(40, 140, by = 20)),
  fit_method = fit_gpr(),
  control = ctrl
)
plot(sbl_2)

# Example 3: LOCAL algorithm (Shenk et al., 1997)
local_algo <- mbl(
  Xr = train_x,
  Yr = train_y,
  Xu = test_x,
  Yu = test_y,
  neighbors = neighbors_k(seq(40, 140, by = 20)),
  diss_method = diss_correlation(),
  diss_usage = "none",
  fit_method = fit_wapls(min_ncomp = 3, max_ncomp = 15),
  control = ctrl
)
plot(local_algo)

# Example 4: Using dissimilarity as predictors
local_algo_2 <- mbl(
  Xr = train_x,
  Yr = train_y,
  Xu = test_x,
  Yu = test_y,
  neighbors = neighbors_k(seq(40, 140, by = 20)),
  diss_method = diss_pca(ncomp = ncomp_by_opc(40)),
  diss_usage = "predictors",
  fit_method = fit_wapls(min_ncomp = 3, max_ncomp = 15),
  control = ctrl
)
plot(local_algo_2)

# Example 5: Parallel execution
library(doParallel)
n_cores <- min(2, parallel::detectCores() - 1)
clust <- makeCluster(n_cores)
registerDoParallel(clust)

local_algo_par <- mbl(
  Xr = train_x,
  Yr = train_y,
  Xu = test_x,
  Yu = test_y,
  neighbors = neighbors_k(seq(40, 140, by = 20)),
  diss_method = diss_correlation(),
  fit_method = fit_wapls(min_ncomp = 3, max_ncomp = 15),
  control = ctrl
)

registerDoSEQ()
try(stopCluster(clust))
}

}
\references{
Cleveland, W. S., and Devlin, S. J. 1988. Locally weighted regression: an
approach to regression analysis by local fitting. Journal of the American
Statistical Association 83:596-610.

Guerrero, C., Zornoza, R., Gomez, I., Mataix-Beneyto, J. 2010. Spiking of
NIR regional models using observations from target sites: Effect of model
size on prediction accuracy. Geoderma 158:66-77.

Naes, T., Isaksson, T., Kowalski, B. 1990. Locally weighted regression and
scatter correction for near-infrared reflectance data. Analytical Chemistry
62:664-673.

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.

Rasmussen, C.E., Williams, C.K. 2006. Gaussian Processes for Machine
Learning. MIT Press.

Shenk, J., Westerhaus, M., Berzaghi, P. 1997. Investigation of a LOCAL
calibration procedure for near infrared instruments. Journal of Near
Infrared Spectroscopy 5:223-232.
}
\seealso{
\code{\link{mbl_control}}, \code{\link{neighbors_k}},
\code{\link{neighbors_diss}}, \code{\link{diss_pca}}, \code{\link{diss_pls}},
\code{\link{fit_pls}}, \code{\link{fit_wapls}}, \code{\link{fit_gpr}},
\code{\link{search_neighbors}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez} and
Antoine Stevens
}
