% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nondominated.R
\name{is_nondominated}
\alias{is_nondominated}
\alias{filter_dominated}
\alias{any_dominated}
\title{Identify and remove dominated points according to Pareto optimality}
\usage{
is_nondominated(x, maximise = FALSE, keep_weakly = FALSE)

filter_dominated(x, maximise = FALSE, keep_weakly = FALSE)

any_dominated(x, maximise = FALSE, keep_weakly = FALSE)
}
\arguments{
\item{x}{\code{matrix()}|\code{data.frame()}\cr Matrix or data frame of numerical
values, where each row gives the coordinates of a point.}

\item{maximise}{\code{logical()}\cr Whether the objectives must be maximised
instead of minimised. Either a single logical value that applies to all
objectives or a vector of logical values, with one value per objective.}

\item{keep_weakly}{\code{logical(1)}\cr If \code{FALSE}, return \code{FALSE} for any
duplicates of nondominated points, except the last one.}
}
\value{
\code{\link[=is_nondominated]{is_nondominated()}} returns a logical vector of the same length
as the number of rows of \code{data}, where \code{TRUE} means that the
point is not dominated by any other point.

\code{\link[=filter_dominated]{filter_dominated()}} returns a matrix or data.frame with only mutually nondominated points.

\code{\link[=any_dominated]{any_dominated()}} returns \code{TRUE} if \code{x} contains any (weakly-)dominated points, \code{FALSE} otherwise.
}
\description{
Identify nondominated points with \code{\link[=is_nondominated]{is_nondominated()}} and remove dominated
ones with \code{\link[=filter_dominated]{filter_dominated()}}.

\code{\link[=any_dominated]{any_dominated()}} quickly detects if a set contains any dominated point.
}
\details{
Given \eqn{n} points of dimension \eqn{m}, the current implementation always
uses the best-known \eqn{O(n \log n)} dimension-sweep algorithm
\citep{KunLucPre1975jacm} for \eqn{m \leq 3}. For \eqn{m \geq 4}, functions
\code{is_nondominated()} and \code{filter_dominated()} use the best-known \eqn{O(n
\log^{m-2} n)} algorithm \citep{KunLucPre1975jacm} when \eqn{n > 16}, and
the naive \eqn{O(m n^2)} algorithm otherwise.  Function \code{any_dominated()}
always uses the naive algorithm for \eqn{m \geq 4}.
}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=pareto_rank]{pareto_rank()}}
}
\author{
Manuel \enc{López-Ibáñez}{Lopez-Ibanez}
}
\concept{dominance}
\examples{
S = matrix(c(1,1,0,1,1,0,1,0), ncol = 2, byrow = TRUE)
is_nondominated(S)
is_nondominated(S, maximise = TRUE)
filter_dominated(S)
filter_dominated(S, keep_weakly = TRUE)
any_dominated(S)
any_dominated(S, keep_weakly = TRUE)
any_dominated(filter_dominated(S))
path_A1 <- file.path(system.file(package="moocore"),"extdata","ALG_1_dat.xz")
set <- read_datasets(path_A1)[,1:2]
is_nondom <- is_nondominated(set)
cat("There are ", sum(is_nondom), " nondominated points\n")

if (requireNamespace("graphics", quietly = TRUE)) {
   plot(set, col = "blue", type = "p", pch = 20)
   ndset <- filter_dominated(set)
   points(ndset[order(ndset[,1]),], col = "red", pch = 21)
}
}
