pulse_plot: Plot processed PULSE data

Description

A shortcut function based on ggplot2 to facilitate the quick inspection of the results of the analysis (with the option to separate channels or not).

Usage

pulse_plot(
  heart_rates,
  ID = NULL,
  normalized = FALSE,
  smooth = TRUE,
  points = TRUE,
  facets = TRUE,
  bpm = FALSE
)

Value

A ggplot object that can be augmented using ggplot2 syntax or plotted right away

Arguments

heart_rates: the output from PULSE() (or pulse_heart() and any of the downstream functions).
ID: character string naming a single target channel id (must match exactly); defaults to NULL, which results in all IDs being plotted
normalized: logical, defaults to FALSE; whether to plot hz_norm (TRUE) or hz (FALSE).
smooth: logical, defaults to TRUE; whether to plot a loess smoothing curve (TRUE) or a line (FALSE).
points: logical, defaults to TRUE; whether to overlay data points.
facets: logical, defaults to TRUE; whether to separate channels in facets (TRUE) or to plot all data together (FALSE)
bpm: logical, defaults to FALSE; whether to plot heartbeat frequency using Hz (FALSE) or Beats Per Minute (TRUE); forced to FALSE if normalized is set to TRUE

Details

This function is NOT meant for high-level displaying of PULSE data - it's simply a quick shortcut to facilitate data inspection.

When inspecting the plot with smooth = TRUE, assess if the loess confidence intervals are too wide for any given channel, which is indicative of data with high variability (not ideal).

If using smooth = FALSE, then look for the width of the confidence interval for each data point.

Examples

Run this code

## Begin prepare data ----
paths <- pulse_example()
chn <- paste0("c", formatC(1:10, width = 2, flag = "0"))
heart_rates <- PULSE(
  paths,
  discard_channels  = chn[-9],
  raw_v_smoothed = FALSE,
  show_progress = FALSE)
## End prepare data ----

# Default
pulse_plot(heart_rates)

# A single ID
pulse_plot(heart_rates, ID = "c09")

# Without facets, the different basal heartbeat rates become evident in #' non-normalized data
pulse_plot(heart_rates, facets = FALSE)

# Without facets, normalized data always lines up (around 1) during the #' baseline period
pulse_plot(
  pulse_normalize(heart_rates),
  normalized = TRUE,
  facets = FALSE)

# The plot can be modified using ggplot2 syntax
pulse_plot(heart_rates) + ggplot2::theme_dark()

# Data can also be visualized using BPM (Beats Per Minute)
pulse_plot(heart_rates, bpm = TRUE)

# If inspecting the heart rate estimates for a single ID and suppressing the
# LOESS smoothing, the confidence interval of each estimate is also shown
pulse_plot(heart_rates, ID = "c09", smooth = FALSE)