% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/UserFacingCoreFunctions.R
\name{scale_focus_plus}
\alias{scale_focus_plus}
\title{Turn on a "focus mode" to highlight specific groups via color or fill}
\usage{
scale_focus_plus(
  aes,
  group_var,
  focal_groups,
  diff_nonfocal = FALSE,
  diff_focal = TRUE,
  gray_start = 0.35,
  gray_end = 0.65,
  focal_start = 0.75,
  focal_end = 0.25,
  custom_focal = NULL,
  custom_nonfocal = NULL,
  ...
)
}
\arguments{
\item{aes}{A character string indicating which aesthetic should receive the
focus scale. Must be one of \code{"color"}, \code{"colour"}, or \code{"fill"}.}

\item{group_var}{A character vector or factor containing the grouping variable
mapped to \code{aes}. This should generally be the same vector mapped to \code{colour},
\code{color}, or \code{fill} in the plot.}

\item{focal_groups}{A character vector giving the group value(s) in the
\code{group_var} to be emphasized. All values must be present in \code{group_var}.}

\item{diff_nonfocal}{Logical. If \code{TRUE}, non-focal groups are assigned
different (gray/custom) color values. If \code{FALSE}, all non-focal groups
receive the same (gray/custom) value. Defaults to \code{FALSE}.}

\item{diff_focal}{Logical. If \code{TRUE}, focal groups are assigned different
(viridis/custom) colors. If \code{FALSE}, all focal groups receive the same
(viridis/custom) color. Defaults to \code{TRUE}.}

\item{gray_start, gray_end}{Numeric values between 0 and 1 controlling the
range of gray values used for non-focal groups when custom_nonfocal is not
NULL. Lower values are darker and higher values are lighter. \code{gray_start}
must be less than or equal to \code{gray_end}.}

\item{focal_start, focal_end}{Numeric values between 0 and 1 controlling the
portions of the viridis palette used for focal groups when custom_focal is
not NULL. By default, \code{scale_focus_plus()} draws from the darker and lighter
ends of the palette while avoiding the middle, as humans are generally more
drawn to very bright and very dark colors. \code{focal_end} must be less than
or equal to \code{focal_start}.}

\item{custom_focal}{Optional custom color(s) for focal group(s). When
\code{diff_focal = TRUE}, this must be a named character vector whose names
match the unique values in \code{focal_groups}. When \code{diff_focal = FALSE},
this must be a character vector of length 1.}

\item{custom_nonfocal}{Optional custom color(s) for non-focal group(s). When
\code{diff_nonfocal = TRUE}, this must be a named character vector whose names
match the non-focal values in \code{group_var}. When \code{diff_nonfocal = FALSE},
this must be a character vector of length 1.}

\item{...}{Additional arguments passed to
\code{\link[ggplot2:scale_manual]{ggplot2::scale_colour_manual()}} or \code{\link[ggplot2:scale_manual]{ggplot2::scale_fill_manual()}}. Do not
supply \code{values}; \code{scale_focus_plus()} constructs the \code{values} argument
internally. All other arguments should be accessible, including \code{labels}
and \code{name}. Use these to relabel and retitle the created scale.}
}
\value{
A ggplot2 scale object.
}
\description{
\code{scale_focus_plus()} is a wrapper for \code{ggplot2}'s \code{scale_fill/colour_manual}
functions that helps a user quickly creates a manual color or fill scale
that highlights one or more focal groups while de-emphasizing all other
groups (via desaturation, by default). This is useful when a graph would
ideally call attention to specific groups without removing the broader
context and transparency provided by the remaining groups. This reduces
cognitive load by allowing non-essential information to "fall into the
background" to be readily ignored, increasing the reading rate, and also
helps to signpost for the reader where the "message" is within the plot.
}
\details{
By default, focal groups are assigned visually prominent colors from the
Universal-Design-oriented viridis color palette via \code{viridisLite::viridis()},
while non-focal groups are assigned a shared gray. Focal groups are
differentiated from one another by default; non-focal groups are not. These
defaults are intended to support a common graph-design pattern:
show all groups, but make the intended comparison obvious.

Note that the default values for \code{gray_start}, \code{gray_end}, \code{focal_start}, and
\code{focal_end} intentionally map to different regions of the luminance (light
to dark) scale so as to render the colors still distinguishable in grayscale
by virtue of variance in luminance. This variance should be maintained for
accessibility even if different inputs are provided.

\code{scale_focus_plus()} is a convenience wrapper around
\code{\link[ggplot2:scale_manual]{ggplot2::scale_colour_manual()}} and \code{\link[ggplot2:scale_manual]{ggplot2::scale_fill_manual()}}. It does
not alter the data or add any geoms. Instead, it constructs a named vector of
colors from \code{group_var} and \code{focal_groups}, then passes that vector to the
appropriate ggplot2 manual color/fill scale.

This function is most useful when the focal/non-focal distinction is the
primary visual message, and all non-focal groups may be secondary. When
individual non-focal groups must remain distinguishable, set
\code{diff_nonfocal = TRUE} or provide \code{custom_nonfocal}.

Although \code{scale_focus_plus()} is designed for discrete data, it can also be
used when the data requiring (de-)emphasis is continuous. In those cases,
first create a discrete grouping variable in the data, then map that variable
to \code{colour} or \code{fill}. For example, a continuous measurement could be
converted to groups such as \code{"High cover"} and \code{"Other"} before calling
\code{scale_focus_plus()}. See the examples section for an example.
}
\examples{
lake_dat = data.frame(
  year = rep(2012:2020, times = 5),
  lake = rep(paste("Lake", LETTERS[1:5]), each = 9),
  cpue = c(
    10, 12, 13, 14, 16, 18, 19, 21, 23,
    18, 17, 16, 16, 15, 14, 13, 13, 12,
    8, 9, 11, 13, 16, 20, 24, 27, 30,
    22, 21, 21, 20, 19, 18, 18, 17, 17,
    12, 13, 13, 15, 15, 16, 17, 18, 20
  )
)

ggplot2::ggplot(
  lake_dat,
  ggplot2::aes(x = year,
               y = cpue,
               colour = lake,
               group = lake)
) +
  ggplot2::geom_line(linewidth = 1) +
  ggplot2::geom_point(size = 2) +
  scale_focus_plus(aes = "colour",
             group_var = lake_dat$lake,
             focal_groups = c("Lake A", "Lake C"))

# One can use a shared focal color and a custom non-focal gray.
ggplot2::ggplot(
  lake_dat,
  ggplot2::aes(x = year,
               y = cpue,
               colour = lake,
               group = lake)
) +
  ggplot2::geom_line(linewidth = 1) +
  scale_focus_plus(aes = "colour",
             group_var = lake_dat$lake,
             focal_groups = c("Lake A", "Lake C"),
             diff_focal = FALSE,
             custom_focal = "#440154",
             custom_nonfocal = "gray70")

cover_dat = data.frame(
  taxon = c("Native plants",
            "Starry stonewort",
            "Eurasian watermilfoil",
            "Curly-leaf pondweed"),
  mean_cover = c(62, 28, 18, 11)
)

ggplot2::ggplot(
  cover_dat,
  ggplot2::aes(x = taxon,
               y = mean_cover,
               fill = taxon)
) +
  ggplot2::geom_col() +
  scale_focus_plus(aes = "fill",
             group_var = cover_dat$taxon,
             focal_groups = "Starry stonewort") +
  ggplot2::labs(x = NULL,
                y = "Mean percent cover")

# Focal groups can also be created from continuous variables. Here's how:
}
