heartbeatr (version 1.0.0)

pulse_normalize: Normalize PULSE heartbeat rate estimates

Description

Take the output from PULSE() and compute the normalized heartbeat rates. The normalization of heartbeat rates is achieved by calculating, for each individual (i.e., PULSE channel), the average heartbeat rate during a reference baseline period (ideally measured during acclimation, before the stress-inducing treatment is initiated).

Usage

pulse_normalize(
  heart_rates,
  FUN = mean,
  t0 = NULL,
  span_mins = 10,
  overwrite = FALSE
)

Value

The same tibble provided as input, with an additional column hz_norm containing the normalized heart beat frequencies (overwrite = FALSE) or with the same number of columns and normalized data saved to the column hz (overwrite = TRUE).

Arguments

heart_rates

the output from PULSE(), pulse_heart(), pulse_doublecheck() or pulse_choose_keep.

FUN

the function to be applied to normalize the data within the baseline period (defaults to mean; median may be more suited in some situations; any other function that returns a single numeric value is technically acceptable).

t0

either NULL (default), a lubridate::POSIXct object or a character string that can be directly converted to a lubridate::POSIXct object. Represents the beginning of the period to be used to establish the baseline heart beat frequency (same value is used for all channels). If set to NULL, the baseline period is set to the earliest timestamp available.

span_mins

numeric, defaults to 10; number of minutes since t0, indicating the width of the baseline period (baseline from t0 to t0 + span_mins mins)

overwrite

logical, defaults to FALSE; should the normalized values be stored in a different column (hz_norm if overwrite = FALSE; RECOMMENDED) or replace the data in the column hz (overwrite = TRUE; WARNING: the original hz values cannot be recovered).

Different baseline periods for each channel

pulse_normalize only allows setting a single baseline period. If different periods are needed for different channels or groups of channels, generate two or more subsets of heart_rates containing heart_rates$id that share the same baseline periods, normalize each independently and bind all data together at the end (see the examples section below).

Details

Normalizing heartbeat rates is important because even individuals from the same species, the same age cohort and subjected to the same treatment will have different basal heart beat frequencies. After normalizing, these differences are minimized, and the analysis can focus on the change of hear beat frequency relative to a reference period (the baseline period chosen) rather than on the absolute values of heart beat frequency - which can be misleading.

The period chosen for the baseline doesn't need to be long - it's much more important that conditions (and hopefully heart beat frequencies) are as stable and least stressful as possible during that period.

After normalization, heart beat frequencies during the baseline period will, by definition, average to 1. Elsewhere, normalized heart beat frequencies represent ratios relative to the baseline: 2 represents a heart beat frequency double the basal frequency, while 0.5 indicates half of the basal frequency. This means that two individuals may experience a doubling of heart beat frequency throughout an experiment even if their absolute heart beat frequencies are markedly different from each other (e.g., individual 1 with hz = 0.6 at t0 and hz = 1.2 at t1, and individual 2 with hz = 0.8 at t0 and hz = 1.6 at t1, will both show hz_norm = 1 at t0 and hz_norm = 2 at t1).

See Also

• pulse_heart(), pulse_doublecheck() and pulse_choose_keep() are the functions that generate the input for pulse_normalize

• pulse_plot() can be called to visualize the output from pulse_normalize

• PULSE() is a wrapper function that executes all the steps needed to process PULSE data at once, and its output can also be passed on to pulse_normalize

Examples

## Begin prepare data ----
pulse_data_sub <- pulse_data
pulse_data_sub$data <- pulse_data_sub$data[,1:5]
pulse_data_split <- pulse_split(
   pulse_data_sub,
   window_width_secs = 30,
   window_shift_secs = 60,
   min_data_points = 0.8)
pulse_data_split <- pulse_optimize(pulse_data_split, multi = pulse_data$multi)
heart_rates <- pulse_heart(pulse_data_split)
heart_rates <- pulse_doublecheck(heart_rates)
## End prepare data ----

# Normalize data using the same period as baseline for all channels
pulse_normalize(heart_rates)

# Using a different (complex) function
pulse_normalize(heart_rates, FUN = function(x) quantile(x, 0.4))

# Apply different baseline periods to two groups of IDs
group_1 <- c("limpet_1", "limpet_2")
rbind(
  # group_1
  pulse_normalize(heart_rates[ (heart_rates$id %in% group_1), ], span_mins = 10),
  # all other IDs
  pulse_normalize(heart_rates[!(heart_rates$id %in% group_1), ], span_mins = 30)
)