% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ncl_impl.R
\name{ncl}
\alias{ncl}
\title{Neighborhood Cleaning Rule}
\usage{
ncl(df, var, neighbors = 3, distance = "euclidean", threshold_clean = 0.5)
}
\arguments{
\item{df}{data.frame or tibble. Must have 1 factor variable and remaining
numeric variables.}

\item{var}{Character, name of variable containing factor variable.}

\item{neighbors}{An integer. Number of nearest neighbor that are used to
decide whether an observation is removed. Defaults to \code{3}, unlike the
over-sampling steps which default to \code{5}.}

\item{distance}{A character string specifying the distance metric used for
nearest neighbor calculations, defaulting to \code{"euclidean"}. The available
metrics fall into three groups.

\code{"euclidean"}, \code{"cosine"}, and \code{"mahalanobis"} use approximate nearest
neighbors via the RANN package and scale well to large datasets.

\code{"squared_chord"}, \code{"matusita"}, \code{"hellinger"}, and \code{"bhattacharyya"} are
probability-divergence measures that treat each row as a distribution over
the predictors, so they require non-negative values. \code{"hellinger"} and
\code{"bhattacharyya"} further require each row to sum to 1. All four also use
the RANN package and scale well to large datasets.

\code{"manhattan"}, \code{"chebyshev"}, \code{"canberra"}, \code{"soergel"}, \code{"lorentzian"},
\code{"jeffreys"}, \code{"topsoe"}, \code{"jensen-shannon"}, \code{"jensen_difference"},
\code{"taneja"}, and \code{"kumar-johnson"} compute an exact all-pairs distance
matrix. This takes time and memory proportional to the square of the number
of observations in a class, so these are best suited to smaller datasets.
Everything from \code{"canberra"} onwards is a probability divergence requiring
non-negative values, is provided by the philentropy package (which must be
installed separately), and in the case of \code{"jeffreys"}, \code{"taneja"}, and
\code{"kumar-johnson"} requires strictly positive values, since those divide by
individual predictor values.

The probability divergences are meaningful for compositional predictors such
as proportions or counts normalized per observation, and are generally not
appropriate for standardized predictors.}

\item{threshold_clean}{A numeric. Majority classes are only cleaned around
minority class observations when their size is greater than
\code{threshold_clean} times the size of the minority class. Defaults to \code{0.5}.}
}
\value{
A data.frame or tibble, depending on type of \code{df}.
}
\description{
Under-samples the majority classes by cleaning noisy observations and
observations that pollute the neighborhood of minority class observations.
}
\details{
The Neighborhood Cleaning Rule (NCL) is a cleaning method that combines two
passes over the data. First, it applies the Edited Nearest Neighbors rule,
removing majority class observations whose class differs from the majority of
their \code{neighbors} nearest neighbors. Second, for each minority class
observation that is itself misclassified by its neighbors, the majority class
observations among those neighbors are removed. Compared to Edited Nearest
Neighbors, this focuses the cleaning on the neighborhoods of minority class
observations.

The smallest class is treated as the minority class. Only majority classes
larger than \code{threshold_clean} times the size of the minority class are
cleaned in the second pass.

All columns used in this function must be numeric with no missing data.
}
\examples{
circle_numeric <- circle_example[, c("x", "y", "class")]

res <- ncl(circle_numeric, var = "class")

res <- ncl(circle_numeric, var = "class", neighbors = 5)

res <- ncl(circle_numeric, var = "class", distance = "manhattan")
}
\references{
Laurikkala, J. (2001). Improving identification of difficult
small classes by balancing class distribution. In Conference on Artificial
Intelligence in Medicine in Europe (pp. 63-66). Springer.
}
\seealso{
\code{\link[=step_ncl]{step_ncl()}} for step function of this method

Other Direct Implementations:
\code{\link[=adasyn]{adasyn()}},
\code{\link[=bsmote]{bsmote()}},
\code{\link[=cluster_centroids]{cluster_centroids()}},
\code{\link[=cnn]{cnn()}},
\code{\link[=enn]{enn()}},
\code{\link[=instance_hardness]{instance_hardness()}},
\code{\link[=kmeans_smote]{kmeans_smote()}},
\code{\link[=nearmiss]{nearmiss()}},
\code{\link[=oss]{oss()}},
\code{\link[=rose]{rose()}},
\code{\link[=smogn]{smogn()}},
\code{\link[=smote]{smote()}},
\code{\link[=smoten]{smoten()}},
\code{\link[=smotenc]{smotenc()}},
\code{\link[=svmsmote]{svmsmote()}},
\code{\link[=tomek]{tomek()}}
}
\concept{Direct Implementations}
