EVOLUTION-MANAGER

Edit File: case_when.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: A general vectorised if</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for case_when {dplyr}"><tr><td>case_when {dplyr}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>A general vectorised if</h2>

<h3>Description</h3>

<p>This function allows you to vectorise multiple <code><a href="if_else.html">if_else()</a></code>
statements. It is an R equivalent of the SQL <code style="white-space: pre;">CASE WHEN</code> statement.
If no cases match, <code>NA</code> is returned.
</p>

<h3>Usage</h3>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
<p>&lt;<code><a href="../../rlang/html/dyn-dots.html">dynamic-dots</a></code>&gt; A sequence of two-sided formulas. The left hand side (LHS)
determines which values match this case. The right hand side (RHS)
provides the replacement value.
</p>
<p>The LHS must evaluate to a logical vector. The RHS does not need to be
logical, but all RHSs must evaluate to the same type of vector.
</p>
<p>Both LHS and RHS may have the same length of either 1 or <code>n</code>. The
value of <code>n</code> must be consistent across all cases. The case of
<code>n == 0</code> is treated as a variant of <code>n != 1</code>.
</p>
<p><code>NULL</code> inputs are ignored.</p>
</td></tr>
</table>

<h3>Value</h3>

<p>A vector of length 1 or <code>n</code>, matching the length of the logical
input or output vectors, with the type (and attributes) of the first
RHS. Inconsistent lengths or types will generate an error.
</p>

<h3>Examples</h3>

<pre>
x &lt;- 1:50
case_when(
  x %% 35 == 0 ~ "fizz buzz",
  x %% 5 == 0 ~ "fizz",
  x %% 7 == 0 ~ "buzz",
  TRUE ~ as.character(x)
)

# Like an if statement, the arguments are evaluated in order, so you must
# proceed from the most specific to the most general. This won't work:
case_when(
  TRUE ~ as.character(x),
  x %%  5 == 0 ~ "fizz",
  x %%  7 == 0 ~ "buzz",
  x %% 35 == 0 ~ "fizz buzz"
)

# If none of the cases match, NA is used:
case_when(
  x %%  5 == 0 ~ "fizz",
  x %%  7 == 0 ~ "buzz",
  x %% 35 == 0 ~ "fizz buzz"
)

# Note that NA values in the vector x do not get special treatment. If you want
# to explicitly handle NA values you can use the `is.na` function:
x[2:4] &lt;- NA_real_
case_when(
  x %% 35 == 0 ~ "fizz buzz",
  x %% 5 == 0 ~ "fizz",
  x %% 7 == 0 ~ "buzz",
  is.na(x) ~ "nope",
  TRUE ~ as.character(x)
)

# All RHS values need to be of the same type. Inconsistent types will throw an error.
# This applies also to NA values used in RHS: NA is logical, use
# typed values like NA_real_, NA_complex, NA_character_, NA_integer_ as appropriate.
case_when(
  x %% 35 == 0 ~ NA_character_,
  x %% 5 == 0 ~ "fizz",
  x %% 7 == 0 ~ "buzz",
  TRUE ~ as.character(x)
)
case_when(
  x %% 35 == 0 ~ 35,
  x %% 5 == 0 ~ 5,
  x %% 7 == 0 ~ 7,
  TRUE ~ NA_real_
)

# case_when() evaluates all RHS expressions, and then constructs its
# result by extracting the selected (via the LHS expressions) parts.
# In particular NaN are produced in this case:
y &lt;- seq(-2, 2, by = .5)
case_when(
  y &gt;= 0 ~ sqrt(y),
  TRUE   ~ y
)

# This throws an error as NA is logical not numeric
## Not run: 
case_when(
  x %% 35 == 0 ~ 35,
  x %% 5 == 0 ~ 5,
  x %% 7 == 0 ~ 7,
  TRUE ~ NA
)

## End(Not run)

# case_when is particularly useful inside mutate when you want to
# create a new variable that relies on a complex combination of existing
# variables
starwars %&gt;%
  select(name:mass, gender, species) %&gt;%
  mutate(
    type = case_when(
      height &gt; 200 | mass &gt; 200 ~ "large",
      species == "Droid"        ~ "robot",
      TRUE                      ~ "other"
    )
  )

# `case_when()` is not a tidy eval function. If you'd like to reuse
# the same patterns, extract the `case_when()` call in a normal
# function:
case_character_type &lt;- function(height, mass, species) {
  case_when(
    height &gt; 200 | mass &gt; 200 ~ "large",
    species == "Droid"        ~ "robot",
    TRUE                      ~ "other"
  )
}

case_character_type(150, 250, "Droid")
case_character_type(150, 150, "Droid")

# Such functions can be used inside `mutate()` as well:
starwars %&gt;%
  mutate(type = case_character_type(height, mass, species)) %&gt;%
  pull(type)

# `case_when()` ignores `NULL` inputs. This is useful when you'd
# like to use a pattern only under certain conditions. Here we'll
# take advantage of the fact that `if` returns `NULL` when there is
# no `else` clause:
case_character_type &lt;- function(height, mass, species, robots = TRUE) {
  case_when(
    height &gt; 200 | mass &gt; 200      ~ "large",
    if (robots) species == "Droid" ~ "robot",
    TRUE                           ~ "other"
  )
}

starwars %&gt;%
  mutate(type = case_character_type(height, mass, species, robots = FALSE)) %&gt;%
  pull(type)
</pre>

<hr /><div style="text-align: center;">[Package <em>dplyr</em> version 1.0.2 <a href="00Index.html">Index</a>]</div>
</body></html>