extract_states: Extract summaries of states

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

Extract summaries of states

Description

Extracts a state from a dataset and provides their start and end times, as well as duration and epoch. The state does not have to exist in the dataset, but can be dynamically created. Extracted states can have group-dropping disabled, meaning that summaries based on the extracted states show empty groups as well.

Usage

extract_states(
  data,
  State.colname,
  State.expression = NULL,
  Datetime.colname = Datetime,
  handle.gaps = FALSE,
  epoch = "dominant.epoch",
  drop.empty.groups = TRUE,
  group.by.state = TRUE
)

Arguments

data	A light logger dataset. Expects a dataframe.
State.colname	The variable or condition to be evaluated for state exctration. Expects a symbol. If it is not part of the data, a State.expression is required.
State.expression	If State.colname is not part of the data, this expression will be evaluated to generate the state. The result of this expression will be used for grouping, so it is recommended to be factor-like. If State.colname is part of the data, this argument will be ignored
Datetime.colname	Column name that contains the datetime. Defaults to "Datetime" which is automatically correct for data imported with LightLogR. Expects a symbol.
handle.gaps	Logical whether the data shall be treated with gap_handler(). Is set to FALSE by default, due to computational costs.
epoch	The epoch to use for the gapless sequence. Can be either a lubridate::duration() or a string. If it is a string, it needs to be either '"dominant.epoch"' (the default) for a guess based on the data or a valid lubridate::duration() string, e.g., "1 day" or "10 sec".
drop.empty.groups	Logical. Should empty groups be dropped? Only works if .drop = FALSE has not been used with the current grouping prior to calling the function. Default to TRUE. If set to FALSE can lead to an error if factors are present in the grouping that have more levels than actual data. Can, however, be useful and necessary when summarizing the groups further, e.g. through summarize_numeric() - having an empty group present is important when averaging numbers.
group.by.state	Logical. Should the output be automatically be grouped by the new state?

Value

a dataframe with one row per state instance. Each row will consist of the original dataset grouping, the state column. A state.count column, start and end Datetimes, as well as a duration of the state

Examples

#summarizing states "photoperiod"
states <-
sample.data.environment |>
  add_photoperiod(c(48.52, 9.06)) |>
  extract_states(photoperiod.state)
states |> head(2)
states |> tail(2)
states |> summarize_numeric(c("state.count", "epoch"))

LightLogR documentation built on June 10, 2025, 5:12 p.m.