% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/whv.R
\name{whv_hype}
\alias{whv_hype}
\title{Approximation of the (weighted) hypervolume by Monte-Carlo sampling (2D only)}
\usage{
whv_hype(
  x,
  reference,
  ideal,
  maximise = FALSE,
  nsamples = 100000L,
  seed = NULL,
  dist = "uniform",
  mu = NULL
)
}
\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{reference}{\code{numeric()}\cr Reference point as a vector of numerical
values.}

\item{ideal}{\code{numeric()}\cr Ideal point as a vector of numerical values.}

\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{nsamples}{\code{integer(1)}\cr Number of samples for Monte-Carlo
sampling. Higher values typically produce more accurate approximations of
the true hypervolume, but require more time.}

\item{seed}{\code{integer(1)}\cr Random seed.}

\item{dist}{\code{character(1)}\cr Weight distribution type. See Details.}

\item{mu}{\code{numeric()}\cr Parameter of the weight distribution. See Details.}
}
\value{
A single numerical value.
}
\description{
Return an estimation of the hypervolume of the space dominated by the input
data following the procedure described by \citet{AugBadBroZit2009gecco}. A
weight distribution describing user preferences may be specified.
}
\details{
The current implementation only supports 2 objectives.

A weight distribution  \citep{AugBadBroZit2009gecco} can be provided via the \code{dist} argument. The ones currently supported are:
\itemize{
\item \code{"uniform"} corresponds to the default hypervolume (unweighted).
\item \code{"point"} describes a goal in the objective space, where the parameter \code{mu} gives the coordinates of the goal. The resulting weight distribution is a multivariate normal distribution centred at the goal.
\item \code{"exponential"} describes an exponential distribution with rate parameter \code{1/mu}, i.e., \eqn{\lambda = \frac{1}{\mu}}.
}
}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=read_datasets]{read_datasets()}}, \code{\link[=eafdiff]{eafdiff()}}, \code{\link[=whv_rect]{whv_rect()}}
}
\concept{metrics}
\examples{
whv_hype(matrix(2, ncol=2), reference = 4, ideal = 1, seed = 42)
whv_hype(matrix(c(3,1), ncol=2), reference = 4, ideal = 1, seed = 42)
whv_hype(matrix(2, ncol=2), reference = 4, ideal = 1, seed = 42,
         dist = "exponential", mu=0.2)
whv_hype(matrix(c(3,1), ncol=2), reference = 4, ideal = 1, seed = 42,
         dist = "exponential", mu=0.2)
whv_hype(matrix(2, ncol=2), reference = 4, ideal = 1, seed = 42,
         dist = "point", mu=c(2.9,0.9))
whv_hype(matrix(c(3,1), ncol=2), reference = 4, ideal = 1, seed = 42,
         dist = "point", mu=c(2.9,0.9))
}
