bin_apply {behavr}

Bin a variable (typically time) and compute an aggregate for each bin

Description

This function is typically used to summarise (i.e. computing an aggregate of) a variable (y) for bins of a another variable x (typically time).

Usage

bin_apply(data, y, x = "t", x_bin_length = mins(30),
  wrap_x_by = NULL, FUN = mean, ...)

bin_apply_all(data, ...)

Arguments

data

data.table or behavr table (see details)

y

variable or expression to be aggregated

x

variable or expression to be binned

x_bin_length

length of the bins (same unit as x)

wrap_x_by

numeric value defining wrapping period. NULL, the default, means no wrapping (see details).

FUN

function used to aggregate (e.g. mean, median, sum and so on)

...

additional arguments to be passed to FUN

Details

bin_apply expects data from a single individual, whilst bin_apply_all works on multiple individuals identified by a unique key. wrapping is typically used to compute averages across several periods. For instance, wrap_x_by = days(1), means bins will aggregate values across several days. In this case, the resulting x can be interpreted as "time relative to the onset of the day" (i.e. Zeitgeber Time).

See Also

• behavr – the documentation of the behavr object

Examples

metadata <- data.frame(id = paste0("toy_experiment|",1:5))
dt <- toy_activity_data(metadata, duration = days(2))

# average by 30min time bins, default
dt_binned <- bin_apply_all(dt, moving)
# equivalent to
dt_binned <- dt[, bin_apply(.SD, moving), by = "id"]

# if we want the opposite of moving:
dt_binned <- bin_apply_all(dt, !moving)

# More advanced usage
dt <- toy_dam_data(metadata, duration = days(2))

# sum activity per 60 minutes
dt_binned <- bin_apply_all(dt,
                           activity,
                           x = t,
                           x_bin_length = mins(60),
                           FUN = sum)


# average activity. Time in ZT
dt_binned <- bin_apply_all(dt,
                           activity,
                           x = t,
                           wrap_x_by = days(1)
                           )