% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nondominated.R
\name{pareto_rank}
\alias{pareto_rank}
\title{Rank points according to Pareto-optimality (nondominated sorting).}
\usage{
pareto_rank(x, maximise = 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.}
}
\value{
An integer vector of the same length as the number of rows of the
input \code{x}, where each value gives the rank of each point (lower is
better).
}
\description{
\code{\link[=pareto_rank]{pareto_rank()}} is meant to be used like \code{rank()}, but it assigns ranks
according to Pareto dominance, where rank 1 indicates those solutions not
dominated by any other solution in the input set.  Duplicated points are
assigned the same rank.  The resulting ranking can be used to partition
points into a list of matrices, each matrix representing a nondominated
front \citep{Deb02nsga2} (see examples below).
}
\details{
Given a finite set of points \eqn{X \subset \mathbb{R}^m},
the rank of a point \eqn{x \in X} is defined as:

\deqn{\operatorname{rank}(x) = r \iff x \in F^c_{r} \land \nexists y \in F^c_{r}, y \prec x}

where \eqn{y \prec x} means that \eqn{y} dominates \eqn{x} according to
Pareto optimality, \eqn{F^c_r = X \setminus \bigcup_{i=1}^{r-1} F_i} and
\eqn{F_r = \{x \in X \land \operatorname{rank}(x) = r\}}.  The sets
\eqn{F_c}, with \eqn{c=1,\dots,k}, partition \eqn{X} into \eqn{k}
\emph{fronts}, that is, mutually nondominated subsets of \eqn{X}.

With \eqn{m=2}, i.e., \code{ncol(data)=2}, the code uses the best-known
\eqn{O(n \log n)} algorithm by \citet{Jen03}.  When \eqn{m \geq 3}, it
uses the naive algorithm that identifies one \emph{front} at a time, which
requires \eqn{O(n^2\log n)} for \eqn{m=3}, and \eqn{O(n^2 \log^{m-2} n)}
for \eqn{m \geq 4}.
}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=is_nondominated]{is_nondominated()}}
}
\concept{dominance}
\examples{
three_fronts = matrix(c(1, 2, 3,
                        3, 1, 2,
                        2, 3, 1,
                        10, 20, 30,
                        30, 10, 20,
                        20, 30, 10,
                        100, 200, 300,
                        300, 100, 200,
                        200, 300, 100), ncol=3, byrow=TRUE)
pareto_rank(three_fronts)

split.data.frame(three_fronts, pareto_rank(three_fronts))
path_A1 <- file.path(system.file(package="moocore"),"extdata","ALG_1_dat.xz")
set <- read_datasets(path_A1)[,1:2]
ranks <- pareto_rank(set)
str(ranks)
if (requireNamespace("graphics", quietly = TRUE)) {
   colors <- colorRampPalette(c("red","yellow","springgreen","royalblue"))(max(ranks))
   plot(set, col = colors[ranks], type = "p", pch = 20)
}
}
