gg_states: Add states to gg_day() or gg_days() plots

In LightLogR: Process Data from Wearable Light Loggers and Optical Radiation Dosimeters

Add states to gg_day() or gg_days() plots

Description

gg_states() is a helper function to add state information to plots generated with gg_day(), gg_days(), or gg_doubleplot(). The function can draw on any column in the dataset, but factor-like or logical columns make the most sense.

Usage

gg_states(
  ggplot_obj,
  State.colname,
  aes_fill = NULL,
  aes_col = NULL,
  ymin = -Inf,
  ymax = Inf,
  Datetime.colname = Datetime,
  alpha = 0.2,
  on.top = FALSE,
  ignore.FALSE = TRUE,
  extract.metric = NULL,
  return.state.data = FALSE,
  ...
)

Arguments

ggplot_obj	A ggplot object generated with gg_day() or gg_days() (or gg_doubleplot().
State.colname, Datetime.colname	The colnames of the state to add to the plot, and the column containing the datetimes. Must be part of the dataset. Expects a symbol.
aes_fill, aes_col	conditional aesthetics for ggplot2::geom_rect(). The default (NULL) will be ignored, so that col and fill arguments can be set through the ... arguments. As the states work from a summarized dataset, only a few columns are available for filling/coloring: The State.colname, Grouping variables, and variables created by using extract_states().
ymin, ymax	customize the height of the state rectangle. By default it will cover the whole vertical range (-Inf, Inf), but can be set to any value, including variables generated by extract_states(), which generates the data for the geom. New variables are accessible through the extract_metrics argument.
alpha	A numerical value between 0 and 1 representing the transparency of the states. Default is 0.2.
on.top	Logical scalar. If TRUE, the states will be plotted on top of the existing plot. If FALSE, the states will be plotted underneath the existing plot. Default is FALSE.
ignore.FALSE	Logical that drops FALSE values of a logical state column, so that only TRUE values are recognized as a state. Is only relevant for logical state columns and will be ignored otherwise. Default is TRUE.
extract.metric	Expression to be used in extract_metric(). Can be used to extract additional information that is then available for aes_fill, aes_col, ymin, and ymax. Requires a list containing variable names and formulas to be converted into calls. E.g., calculating the median during each state would require list(new_metric = ~median(MEDI)). Then new_metric is available for the conditional arguments.
return.state.data	Used for debugging. Returns a tibble with the extracted state data. If you are uncertain what information is available, set this to TRUE.
...	Additional arguments given to the ggplot2::geom_rect() used to construct the state shading. Can be used to change the fill color or other aesthetic properties.

Value

a modified ggplot object with the states added.

Examples

#creating a simple TRUE/FALSE state in the sample data: Light above 250 lx mel EDI
#and a second state that cuts data into chunks relating to the Brown et al. 2022 thresholds
#(+aggregating Data to 5 minute intervals & reducing it to three days)
state_data <-
  sample.data.environment |>
   dplyr::mutate(state = MEDI > 250) |>
   Brown_cut(MEDI, state2) |>
   aggregate_Datetime(unit = "5 mins") |>
   filter_Datetime(length = "3 days")

state_data |>
 gg_days() |>
 gg_states(state)

#state 2 has more than one valid state, thus we need to assign a fill aesthetic
state_data |>
 gg_days() |>
 gg_states(state2, aes_fill = state2) +
 ggplot2::scale_fill_manual(values=c("#868686FF", "#EFC000FF", "#0073C2FF"))
 #this line is simply for sensible colors

#same, but with gg_day()
state_data |>
 dplyr::filter(Id == "Participant") |>
 gg_day(geom = "line") |>
 gg_states(state, fill = "red")

 #more complex state
 state_data |>
 dplyr::filter(Id == "Participant") |>
 gg_day(geom = "line") |>
 gg_states(state2, aes_fill = state2)

 #with gg_doubleplot
 state_data |>
 dplyr::filter(Id == "Participant") |>
 gg_doubleplot() |>
 gg_states(state2, aes_fill = state2)

 #setting the height of the bars 
 state_data |>
 dplyr::filter(Id == "Participant") |>
 gg_day(geom = "line") |>
 gg_states(state2, aes_fill = state2, ymin= -0.5, ymax = 0, alpha = 1) +
 ggplot2::scale_fill_manual(values=c("#868686FF", "#EFC000FF", "#0073C2FF"))

 #setting the height of the bars conditionally based on the median value
 state_data |>
 dplyr::filter(Id == "Participant") |>
 gg_day(geom = "line") |>
 gg_states(state2, aes_fill = state2, ymin= -Inf, ymax = median, alpha = 0.75,
           extract.metric = list(median = ~median(MEDI))) +
 ggplot2::scale_fill_manual(values=c("#868686FF", "#EFC000FF", "#0073C2FF"))

LightLogR documentation built on Nov. 28, 2025, 5:09 p.m.