% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/derivedFactor.R
\name{derivedVariable}
\alias{derivedVariable}
\alias{derivedFactor}
\title{Create new variables from logicals}
\usage{
derivedVariable(
  ...,
  .ordered = FALSE,
  .method = c("unique", "first", "last"),
  .debug = c("default", "always", "never"),
  .sort = c("given", "alpha"),
  .default = NULL,
  .asFactor = FALSE
)

derivedFactor(..., .asFactor = TRUE)
}
\arguments{
\item{\dots}{named logical "rules" defining the levels.}

\item{.ordered}{a logical indicating whether the resulting factored should be ordered
Ignored if \code{.asFactor} is \code{FALSE}.}

\item{.method}{one of \code{"unique"}, \code{"first"}, and \code{"last"}.
If \code{"unique"}, exactly one rule must be \code{TRUE} for each position.
If \code{"first"}, the first \code{TRUE} rule defines the level.
If \code{"last"}, the last \code{TRUE} rule defines the level.}

\item{.debug}{one of \code{"default"}, \code{"always"}, and \code{"never"}, indicating
whether debugging information should be printed.  If \code{"default"}, debugging
information is printed only when multiple rules give conflicting definitions
for some positions.}

\item{.sort}{One of \code{"given"} (the default) or \code{"alpha"} or
a vector of integers the same length as the number of levels indicating the
order in which the levels should appear in the resulting factor.
Ignored if \code{.asFactor} is \code{FALSE}.}

\item{.default}{character vector of length 1 giving name of default level or
\code{NULL} for no default.}

\item{.asFactor}{A logical indicating whether the returned value should be a factor.}
}
\description{
Utility functions for creating new variables from logicals describing the levels
}
\details{
Each logical "rule" corresponds to a level in the resulting variable.
If \code{.default} is defined, an implicit rule is added that is \code{TRUE}
whenever all other rules are \code{FALSE}.
When there are multiple \code{TRUE} rules for a slot, the first or last such is used
or an error is generated, depending on the value of \code{method}.

\code{derivedVariable} is designed to be used with \code{\link[=transform]{transform()}} or
\code{\link[dplyr:mutate]{dplyr::mutate()}} to add new
variables to a data frame.  \code{derivedFactor}() is the same but that the
default value for \code{.asFactor} is \code{TRUE}.  See the examples.
}
\examples{
Kf <- mutate(KidsFeet, biggerfoot2 = derivedFactor(
                   dom = biggerfoot == domhand,
                   nondom = biggerfoot != domhand)
                   )
tally( ~ biggerfoot + biggerfoot2, data = Kf)
tally( ~ biggerfoot + domhand, data = Kf)

# Three equivalent ways to define a new variable
# Method 1: explicitly define all levels
modHELP <- mutate(HELPrct, drink_status = derivedFactor( 
  abstinent = i1 == 0,
  moderate = (i1>0 & i1<=1 & i2<=3 & sex=='female') |
     (i1>0 & i1<=2 & i2<=4 & sex=='male'),
  highrisk = ((i1>1 | i2>3) & sex=='female') | 
      ((i1>2 | i2>4) & sex=='male'),
  .ordered = TRUE)
)
tally( ~ drink_status, data = modHELP)

# Method 2: Use .default for last level
modHELP <- mutate(HELPrct, drink_status = derivedFactor( 
  abstinent = i1 == 0,
  moderate = (i1<=1 & i2<=3 & sex=='female') |
     (i1<=2 & i2<=4 & sex=='male'),
  .ordered = TRUE,
  .method = "first",
  .default = "highrisk")
)
tally( ~ drink_status, data = modHELP)

# Method 3: use TRUE to catch any fall through slots
modHELP <- mutate(HELPrct, drink_status = derivedFactor( 
  abstinent = i1 == 0,
  moderate = (i1<=1 & i2<=3 & sex=='female') |
     (i1<=2 & i2<=4 & sex=='male'),
  highrisk=TRUE,
  .ordered = TRUE,
  .method = "first"
  )
)
tally( ~ drink_status, data = modHELP)
is.factor(modHELP$drink_status)

modHELP <- mutate(HELPrct, drink_status = derivedVariable( 
  abstinent = i1 == 0,
  moderate = (i1<=1 & i2<=3 & sex=='female') |
     (i1<=2 & i2<=4 & sex=='male'),
  highrisk=TRUE,
  .ordered = TRUE,
  .method = "first"
  )
)
is.factor(modHELP$drink_status)
}
