heartbeatr (version 1.0.0)

pulse_plot_raw: Plot raw PULSE data

Description

A shortcut function based on ggplot2 to facilitate the quick inspection of the raw data underlying the analysis (with the peaks detected signaled with red dots). Useful to visually inspect the performance of the algorithm.

Usage

pulse_plot_raw(heart_rates, ID, target_time = NULL, range = 0, target_i = NULL)

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

target_time

a target time expressed as POSIX time or a string that can be converted directly by as.POSIXct(); target_i will be computed as the window closest to the target_time

range

numeric, defaults to 0 (only target_i will be plotted); value indicating how many more windows to plot (centered around the target window, i.e., if target_i = 5 and range = 2, windows 3 to 7 will be plotted, with window 5 at the center)

target_i

numeric; value pointing to the index of the target window (which can be found in the column i of heart_rates)

Details

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

When inspecting the plot, assess if red dots top all heartbeats and no more than that. Difficult datasets may result in true heartbeats being missed (false negatives) or non-heartbeats (noise) being erroneously detected (false positives). Note that the wider the time window (controlled by the window_width_secs parameter in pulse_split()) and the higher the heartbeat rate, the less critical are a few false positives or negatives (over a 10 secs window, missing 1 peak in 10 results in hz to drop by 10% (from 1 to 0.9), while over a 30 secs window, missing 1 peak in 30 results in a drop of 3.33% (from 1 to 0.967), and missing 1 peak in 60 results in a drop of just 1.7%.

See Also

• use pulse_plot() to plot processed PULSE data for a several channels

• PULSE() (or pulse_heart() and any of the downstream functions) generates the input for pulse_plot_raw

• call pulse_normalize() to anchor heart beat data from each channel to a reference period during the experiment

Examples

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

# Single window (in both cases, the 5th window)
# using a target date and time
pulse_plot_raw(heart_rates, "c08", "2024-10-01 10:56")
# using the index
pulse_plot_raw(heart_rates, "c08", target_i = 5)

# Multiple windows (less detail, but more context)
pulse_plot_raw(heart_rates, "c08", "2024-10-01 10:56", 2)

# The plot can be modified using ggplot2 syntax
pulse_plot_raw(heart_rates, "c08", target_i = 5) + ggplot2::theme_classic()