Add metrics to extracted sSummary — extract

This helper function adds metric values to an extract, like from extract_states() or extract_clusters(). E.g., the average value of a variable during a cluster or state instance might be of interest. The metrics must be specified by the user using the ... argument.

Usage

extract_metric(
  extracted_data,
  data,
  identifying.colname = state.count,
  Datetime.colname = Datetime,
  ...
)

Arguments

extracted_data: A dataframe containing cluster or state summaries, typically from extract_clusters() or extract_states().
data: The original dataset that produced extracted_data
identifying.colname: Name of the column in extracted_data that uniquely identifies each row (in addition to the groups. Expects a symbol. Defaults to state.count
Datetime.colname: Column name that contains the datetime in data. Defaults to "Datetime" which is automatically correct for data imported with LightLogR. Expects a symbol. This argument is only necessary if data does not contain the cluster.colname.
...: Arguments specifying the metrics to add summary. For example: "mean_lux" = mean(lux).

Value

A dataframe containing the extracted data with added metrics.

Details

The original data does not have to have the cluster/state information, but it will be computationally faster if it does.

Examples

# Extract clusters and add mean MEDI value
sample.data.environment |>
extract_clusters(MEDI > 1000) |>
extract_metric(
  sample.data.environment,
  "mean_lux" = mean(MEDI, na.rm = TRUE)
) |>
dplyr::select(Id, state.count, duration, mean_lux)
#> # A tibble: 10 × 4
#> # Groups:   Id [2]
#>    Id          state.count duration               mean_lux
#>    <fct>       <chr>       <Duration>                <dbl>
#>  1 Environment 1           46050s (~12.79 hours)    11906.
#>  2 Environment 2           47370s (~13.16 hours)    25446.
#>  3 Environment 3           46230s (~12.84 hours)    32700.
#>  4 Environment 4           46320s (~12.87 hours)    32010.
#>  5 Environment 5           47310s (~13.14 hours)    43566.
#>  6 Environment 6           46500s (~12.92 hours)    33579.
#>  7 Participant 1           4290s (~1.19 hours)       5045.
#>  8 Participant 2           2110s (~35.17 minutes)   13440.
#>  9 Participant 3           1890s (~31.5 minutes)     7359.
#> 10 Participant 4           1850s (~30.83 minutes)    8562.

# Extract states and add mean MEDI value
dataset <-
sample.data.environment |>
 add_photoperiod(c(48.5, 9))

dataset |>
  extract_states(photoperiod.state) |>
  extract_metric(dataset, mean_lux = mean(MEDI)) |>
  dplyr::select(state.count, duration, mean_lux)
#> Adding missing grouping variables: `Id`, `photoperiod.state`
#> # A tibble: 26 × 5
#> # Groups:   Id, photoperiod.state [4]
#>    Id          photoperiod.state state.count duration                mean_lux
#>    <fct>       <chr>             <chr>       <Duration>                 <dbl>
#>  1 Environment day               day 1       52920s (~14.7 hours)  10388.    
#>  2 Environment day               day 2       52710s (~14.64 hours) 22893.    
#>  3 Environment day               day 3       52500s (~14.58 hours) 28821.    
#>  4 Environment day               day 4       52260s (~14.52 hours) 28403.    
#>  5 Environment day               day 5       52050s (~14.46 hours) 39621.    
#>  6 Environment day               day 6       51840s (~14.4 hours)  30144.    
#>  7 Environment night             night 1     21810s (~6.06 hours)      0     
#>  8 Environment night             night 2     33570s (~9.32 hours)      0.0142
#>  9 Environment night             night 3     33780s (~9.38 hours)      0.0216
#> 10 Environment night             night 4     33990s (~9.44 hours)      0.0220
#> # ℹ 16 more rows