% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/constructors.R
\name{new-param}
\alias{new-param}
\alias{new_quant_param}
\alias{new_qual_param}
\title{Tools for creating new parameter objects}
\usage{
new_quant_param(
  type = c("double", "integer"),
  range = NULL,
  inclusive = NULL,
  default = deprecated(),
  trans = NULL,
  values = NULL,
  label = NULL,
  finalize = NULL,
  ...,
  call = caller_env()
)

new_qual_param(
  type = c("character", "logical"),
  values,
  default = deprecated(),
  label = NULL,
  finalize = NULL,
  ...,
  call = caller_env()
)
}
\arguments{
\item{type}{A single character value. For quantitative parameters, valid
choices are \code{"double"} and \code{"integer"} while for qualitative factors they are
\code{"character"} and \code{"logical"}.}

\item{range}{A two-element vector with the smallest or largest possible
values, respectively. If these cannot be set when the parameter is defined,
the \code{unknown()} function can be used. If a transformation is specified,
these values should be in the \emph{transformed units}. If \code{values} is supplied,
and \code{range} is \code{NULL}, \code{range} will be set to \code{range(values)}.}

\item{inclusive}{A two-element logical vector for whether the range
values should be inclusive or exclusive. If \code{values} is supplied,
and \code{inclusive} is \code{NULL}, \code{inclusive} will be set to \code{c(TRUE, TRUE)}.}

\item{default}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
No longer used. If a value is supplied, it will be ignored and
a warning will be thrown.}

\item{trans}{A \code{trans} object from the \pkg{scales} package, such as
\code{\link[scales:transform_log]{scales::transform_log()}} or \code{\link[scales:transform_reciprocal]{scales::transform_reciprocal()}}. Create custom
transforms with \code{\link[scales:new_transform]{scales::new_transform()}}.}

\item{values}{A vector of possible values that is required when \code{type} is
\code{"character"} or \code{"logical"} but optional otherwise. For quantitative
parameters, this can be used as an alternative to \code{range} and \code{inclusive}.
If set, these will be used by \code{\link[=value_seq]{value_seq()}} and \code{\link[=value_sample]{value_sample()}}.}

\item{label}{An optional named character string that can be used for
printing and plotting. The name should match the object name (e.g.
\code{"mtry"}, \code{"neighbors"}, etc.)}

\item{finalize}{A function that can be used to set the data-specific
values of a parameter (such as the \code{range}).}

\item{...}{These dots are for future extensions and must be empty.}

\item{call}{The call passed on to \code{\link[rlang:abort]{rlang::abort()}}.}
}
\value{
An object of class \code{"param"} with the primary class being either
\code{"quant_param"} or \code{"qual_param"}. The \code{range} element of the object
is always converted to a list with elements \code{"lower"} and \code{"upper"}.
}
\description{
These functions are used to construct new parameter objects. Generally,
these functions are called from higher level parameter generating functions
like \code{\link[=mtry]{mtry()}}.
}
\examples{
# Create a function that generates a quantitative parameter
# corresponding to the number of subgroups.
num_subgroups <- function(range = c(1L, 20L), trans = NULL) {
  new_quant_param(
    type = "integer",
    range = range,
    inclusive = c(TRUE, TRUE),
    trans = trans,
    label = c(num_subgroups = "# Subgroups"),
    finalize = NULL
  )
}

num_subgroups()

num_subgroups(range = c(3L, 5L))

# Custom parameters instantly have access
# to sequence generating functions
value_seq(num_subgroups(), 5)

}
