% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Domain.R, R/ParamDbl.R, R/ParamFct.R,
%   R/ParamInt.R, R/ParamLgl.R, R/ParamUty.R
\name{Domain}
\alias{Domain}
\alias{p_dbl}
\alias{p_fct}
\alias{p_int}
\alias{p_lgl}
\alias{p_uty}
\title{Domain: Parameter Range without an Id}
\usage{
p_dbl(
  lower = -Inf,
  upper = Inf,
  special_vals = list(),
  default = NO_DEF,
  tags = character(),
  tolerance = sqrt(.Machine$double.eps),
  depends = NULL,
  trafo = NULL,
  logscale = FALSE,
  init,
  aggr = NULL,
  in_tune_fn = NULL,
  disable_in_tune = NULL
)

p_fct(
  levels,
  special_vals = list(),
  default = NO_DEF,
  tags = character(),
  depends = NULL,
  trafo = NULL,
  init,
  aggr = NULL,
  in_tune_fn = NULL,
  disable_in_tune = NULL
)

p_int(
  lower = -Inf,
  upper = Inf,
  special_vals = list(),
  default = NO_DEF,
  tags = character(),
  tolerance = sqrt(.Machine$double.eps),
  depends = NULL,
  trafo = NULL,
  logscale = FALSE,
  init,
  aggr = NULL,
  in_tune_fn = NULL,
  disable_in_tune = NULL
)

p_lgl(
  special_vals = list(),
  default = NO_DEF,
  tags = character(),
  depends = NULL,
  trafo = NULL,
  init,
  aggr = NULL,
  in_tune_fn = NULL,
  disable_in_tune = NULL
)

p_uty(
  custom_check = NULL,
  special_vals = list(),
  default = NO_DEF,
  tags = character(),
  depends = NULL,
  trafo = NULL,
  repr = substitute(default),
  init,
  aggr = NULL,
  in_tune_fn = NULL,
  disable_in_tune = NULL
)
}
\arguments{
\item{lower}{(\code{numeric(1)})\cr
Lower bound, can be \code{-Inf}.}

\item{upper}{(\code{numeric(1)})\cr
Upper bound can be \code{+Inf}.}

\item{special_vals}{(\code{list()})\cr
Arbitrary special values this parameter is allowed to take, to make it
feasible. This allows extending the domain of the parameter. Note that
these values are only used in feasibility checks, neither in generating
designs nor sampling.}

\item{default}{(\code{any})\cr
Default value. Can be from the domain of the parameter or an element of
\code{special_vals}. Has value \link{NO_DEF} if no default exists. \code{NULL} can be a
valid default.
The value has no effect on \code{ParamSet$values} or the behavior of
\code{ParamSet$check()}, \verb{$test()} or \verb{$assert()}.
The \code{default} is intended to be used for documentation purposes.
`}

\item{tags}{(\code{character()})\cr
Arbitrary tags to group and subset parameters. Some tags serve a special
purpose:\cr
\itemize{
\item \code{"required"} implies that the parameters has to be given when setting
\code{values} in \link{ParamSet}.
}}

\item{tolerance}{(\code{numeric(1)})\cr
Initializes the \verb{$tolerance} field that determines the}

\item{depends}{(\code{call} | \code{expression})\cr
An expression indicating a requirement for the parameter that will be constructed from this. Can be given as an
expression (using \code{quote()}), or the expression can be entered directly and will be parsed using NSE (see
examples). The expression may be of the form \verb{<Param> == <value>} or \verb{<Param> \%in\% <values>}, which will result in
dependencies according to \verb{ParamSet$add_dep(on = "<Param>", cond = CondEqual(<value>))} or
\verb{ParamSet$add_dep(on = "<Param>", cond = CondAnyOf(<values>))}, respectively (see \code{\link{CondEqual}},
\code{\link{CondAnyOf}}). The expression may also contain multiple conditions separated by \code{&&}.}

\item{trafo}{(\code{function})\cr
Single argument function performing the transformation of a parameter. When the \code{Domain} is used to construct a
\code{\link{ParamSet}}, this transformation will be applied to the corresponding parameter as part of the \verb{$trafo} function.\cr
Note that the trafo is \emph{not} inherited by \code{\link{TuneToken}}s! Defining a parameter
with e.g. \code{p_dbl(..., trafo = ...)} will \emph{not} automatically give the \code{to_tune()} assigned to it a transformation.
\code{trafo} only makes sense for \code{\link{ParamSet}}s that get used as search spaces for optimization or tuning, it is not useful when
defining domains or hyperparameter ranges of learning algorithms, because these do not use trafos.}

\item{logscale}{(\code{logical(1)})\cr
Put numeric domains on a log scale. Default \code{FALSE}. Log-scale \code{Domain}s represent parameter ranges where lower and upper bounds
are logarithmized, and where a \code{trafo} is added that exponentiates sampled values to the original scale. This is
\emph{not} the same as setting \code{trafo = exp}, because \code{logscale = TRUE} will handle parameter bounds internally:
a \code{p_dbl(1, 10, logscale = TRUE)} results in a parameter that has lower bound \code{0}, upper bound \code{log(10)},
and uses \code{exp} transformation on these. Therefore, the given bounds represent the bounds \emph{after} the transformation.
(see examples).\cr
\code{p_int()} with \code{logscale = TRUE} results in a continuous parameter similar to \code{p_dbl()}, not an integer-valued parameter, with bounds \code{log(max(lower, 0.5))} ...
\code{log(upper + 1)} and a trafo similar to "\code{as.integer(exp(x))}" (with additional bounds correction). The lower bound
is lifted to \code{0.5} if \code{lower} 0 to handle the \code{lower == 0} case. The upper bound is increased to \code{log(upper + 1)}
because the trafo would otherwise almost never generate a value of \code{upper}.\cr
When \code{logscale} is \code{TRUE}, then upper bounds may be infinite, but lower bounds should be greater than 0 for \code{p_dbl()}
or greater or equal 0 for \code{p_int()}.\cr
Note that "logscale" is \emph{not} inherited by \code{\link{TuneToken}}s! Defining a parameter
with \verb{p_dbl(... logscale = TRUE)} will \emph{not} automatically give the \code{to_tune()} assigned to it log-scale. \code{logscale}
only makes sense for \code{\link{ParamSet}}s that get used as search spaces for optimization or tuning, it is not useful when
defining domains or hyperparameter ranges of learning algorithms, because these do not use trafos.\cr
\code{logscale} happens on a natural (\verb{e == 2.718282...}) basis. Be aware that using a different base (\code{log10()}/\verb{10^},
\code{log2()}/\verb{2^}) is completely equivalent and does not change the values being sampled after transformation.}

\item{init}{(\code{any})\cr
Initial value. When this is given, then the corresponding entry in \code{ParamSet$values} is initialized with this
value upon construction.}

\item{aggr}{(\code{function})\cr
Default aggregation function for a parameter. Can only be given for parameters tagged with \code{"internal_tuning"}.
Function with one argument, which is a list of parameter values and that returns the aggregated parameter value.}

\item{in_tune_fn}{(\verb{function(domain, param_vals)})\cr
Function that converters a \code{Domain} object into a parameter value.
Can only be given for parameters tagged with \code{"internal_tuning"}.
This function should also assert that the parameters required to enable internal tuning for the given \code{domain} are
set in \code{param_vals} (such as \code{early_stopping_rounds} for \code{XGBoost}).}

\item{disable_in_tune}{(named \code{list()})\cr
The parameter values that need to be set in the \code{ParamSet} to disable the internal tuning for the parameter.
For \code{XGBoost} this would e.g. be \code{list(early_stopping_rounds = NULL)}.}

\item{levels}{(\code{character} | \code{atomic} | \code{list})\cr
Allowed categorical values of the parameter. If this is not a \code{character}, then a \code{trafo} is generated that
converts the names (if not given: \code{as.character()} of the values) of the \code{levels} argument to the values.
This trafo is then performed \emph{before} the function given as the \code{trafo} argument.}

\item{custom_check}{(\verb{function()})\cr
Custom function to check the feasibility.
Function which checks the input.
Must return 'TRUE' if the input is valid and a \code{character(1)} with the error message otherwise.
This function should \emph{not} throw an error.
Defaults to \code{NULL}, which means that no check is performed.}

\item{repr}{(\code{language})\cr
Symbol to use to represent the value given in \code{default}.
The \code{deparse()} of this object is used when printing the domain, in some cases.}
}
\value{
A \code{Domain} object.
}
\description{
A \code{Domain} object is a representation of a single dimension of a \code{\link{ParamSet}}. \code{Domain} objects are used to construct
\code{\link{ParamSet}}s, either through the \code{\link[=ps]{ps()}} short form, through the \code{\link{ParamSet}} constructor itself,
or through the \code{\link{ParamSet}}\verb{$search_space()} mechanism (see
\code{\link[=to_tune]{to_tune()}}).
For each of the basic parameter classes (\code{"ParamInt"}, \code{"ParamDbl"}, \code{"ParamLgl"}, \code{"ParamFct"}, and \code{"ParamUty"}) there is a function constructing a \code{Domain} object
(\code{p_int()}, \code{p_dbl()}, \code{p_lgl()}, \code{p_fct()}, \code{p_uty()}). They each have fitting construction arguments that control their
bounds and behavior.

\code{Domain} objects are representations of parameter ranges and are intermediate objects to be used in short form
constructions in \code{\link[=to_tune]{to_tune()}} and \code{\link[=ps]{ps()}}. Because of their nature, they should not be modified by the user, once constructed.
The \code{Domain} object's internals are subject to change and should not be relied upon.
}
\details{
Although the \code{levels} values of a constructed \code{p_fct()} will always be \code{character}-valued, the \code{p_fct} function admits
a \code{levels} argument that goes beyond this:
Besides a \code{character} vector, any atomic vector or list (optionally named) may be given. (If the value is a list
that is not named, the names are inferred using \code{as.character()} on the values.) The resulting \code{Domain} will
correspond to a range of values given by the names of the \code{levels} argument with a \code{trafo} that maps the \code{character}
names to the arbitrary values of the \code{levels} argument.
}
\examples{
params = ps(
  unbounded_integer = p_int(),
  bounded_double = p_dbl(0, 10),
  half_bounded_integer = p_dbl(1),
  half_bounded_double = p_dbl(upper = 1),
  double_with_trafo = p_dbl(-1, 1, trafo = exp),
  extra_double = p_dbl(0, 1, special_vals = list("xxx"), tags = "tagged"),
  factor_param = p_fct(c("a", "b", "c")),
  factor_param_with_implicit_trafo = p_fct(list(a = 1, b = 2, c = list()))
)
print(params)

params$trafo(list(
  bounded_double = 1,
  double_with_trafo = 1,
  factor_param = "c",
  factor_param_with_implicit_trafo = "c"
))

# logscale:
params = ps(x = p_dbl(1, 100, logscale = TRUE))

# The ParamSet has bounds log(1) .. log(100):
print(params)

# When generating a equidistant grid, it is equidistant within log values
grid = generate_design_grid(params, 3)
print(grid)

# But the values are on a log scale with desired bounds after trafo
print(grid$transpose())

# Integer parameters with logscale are `p_dbl()`s pre-trafo
params = ps(x = p_int(0, 10, logscale = TRUE))
print(params)

grid = generate_design_grid(params, 4)
print(grid)

# ... but get transformed to integers.
print(grid$transpose())


# internal tuning

param_set = ps(
  iters = p_int(0, Inf, tags = "internal_tuning", aggr = function(x) round(mean(unlist(x))),
    in_tune_fn = function(domain, param_vals) {
      stopifnot(domain$lower <= 1)
      stopifnot(param_vals$early_stopping == TRUE)
      domain$upper
    },
    disable_in_tune = list(early_stopping = FALSE)),
  early_stopping = p_lgl()
)
param_set$set_values(
  iters = to_tune(upper = 100, internal = TRUE),
  early_stopping = TRUE
)
param_set$convert_internal_search_space(param_set$search_space())
param_set$aggr_internal_tuned_values(
  list(iters = list(1, 2, 3))
)

param_set$disable_internal_tuning("iters")
param_set$values$early_stopping
}
\seealso{
Other ParamSet construction helpers: 
\code{\link{ps}()},
\code{\link{to_tune}()}
}
\concept{ParamSet construction helpers}
