Extract summaries of states — extract

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

Usage

extract_states(
  data,
  State.colname,
  State.expression = NULL,
  Datetime.colname = Datetime,
  handle.gaps = FALSE,
  epoch = "dominant.epoch"
)

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.
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".

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)
#> # A tibble: 2 × 7
#> # Groups:   Id, photoperiod.state [1]
#>   Id          photoperiod.state state.count epoch      start              
#>   <fct>       <chr>             <chr>       <Duration> <dttm>             
#> 1 Environment day               day 1       30s        2023-08-29 06:03:23
#> 2 Environment day               day 2       30s        2023-08-30 06:04:53
#> # ℹ 2 more variables: end <dttm>, duration <Duration>
states |> tail(2)
#> # A tibble: 2 × 7
#> # Groups:   Id, photoperiod.state [1]
#>   Id          photoperiod.state state.count epoch      start              
#>   <fct>       <chr>             <chr>       <Duration> <dttm>             
#> 1 Participant night             night 6     10s        2023-09-02 20:36:49
#> 2 Participant night             night 7     10s        2023-09-03 20:34:39
#> # ℹ 2 more variables: end <dttm>, duration <Duration>
states |> summarize_numeric(c("state.count", "epoch"))
#> # A tibble: 4 × 7
#> # Groups:   Id [2]
#>   Id          photoperiod.state mean_start          mean_end           
#>   <fct>       <chr>             <dttm>              <dttm>             
#> 1 Environment day               2023-08-31 18:07:08 2023-09-01 08:39:58
#> 2 Environment night             2023-08-31 21:08:31 2023-09-01 05:14:40
#> 3 Participant day               2023-08-31 18:07:04 2023-09-01 08:39:55
#> 4 Participant night             2023-08-31 21:08:30 2023-09-01 05:14:37
#> # ℹ 3 more variables: mean_duration <Duration>, episodes <int>,
#> #   total_duration <Duration>