Extract RR Interval Data from a FIT File Object with Artifact Correction

Extracts and processes RR interval data (HRV data) from a FIT file object with integrated artifact detection and correction. This function combines data extraction with research-validated preprocessing methods.

extract_rr_data(
  fit_object,
  correction_method = "linear",
  threshold_level = "medium",
  hr_adaptive = TRUE,
  ...
)

Arguments

fit_object

A FIT file object, typically created by FITfileR::readFitFile(). The object should be the result of reading a FIT file that is expected to contain HRV (RR interval) data.

correction_method

Character string specifying the artifact correction method. Options are: "linear", "cubic", "lipponen", "none". Default is "linear"

threshold_level

Character string specifying detection threshold level: "low", "medium", "strong". Default is "medium" (0.25s)

hr_adaptive

Logical indicating whether to use HR-adaptive thresholds. Default is TRUE

...

Additional arguments passed to correction functions

Value

A data frame containing the processed RR data with the following structure:

• time: Numeric vector of RR intervals (corrected if method != "none")

• Additional columns may be present depending on correction method

• Attributes include correction metadata for diagnostic purposes

Details

The function implements a comprehensive preprocessing pipeline:

1. Input Validation: Validates the fit_object using validate_fit_object()

2. HRV Data Extraction: Extracts raw HRV data using FITfileR::hrv()

3. Artifact Detection: Applies Kubios-style adaptive threshold detection

4. Artifact Correction: Applies selected correction method if artifacts found

5. Return Structured Output: Returns corrected data with metadata

Correction Methods:

• "linear": Linear interpolation (lowest RMSSD bias, recommended default)

• "cubic": Cubic spline interpolation (Kubios-style, good automation)

• "lipponen": Lipponen-Tarvainen algorithm (state-of-the-art, <2% error)

• "none": No correction applied (returns raw extracted data)

Artifact Detection: Uses research-validated Kubios-style time-varying thresholds with dRR series analysis to differentiate ectopic beats from normal sinus rhythm. The medium threshold (0.25s) provides optimal balance for most populations.

See also

detect_artifacts_kubios(), correct_rr_linear(), correct_rr_cubic_spline(), correct_rr_lipponen_tarvainen()

Examples

if (FALSE) { # \dontrun{
# Basic usage with default linear correction
fit_file <- FITfileR::readFitFile("activity.fit")
rr_data <- extract_rr_data(fit_file)

# Specify correction method
rr_corrected <- extract_rr_data(fit_file, correction_method = "cubic")

# No correction, just extraction
rr_raw <- extract_rr_data(fit_file, correction_method = "none")

# Advanced: custom threshold
rr_strict <- extract_rr_data(fit_file, threshold_level = "strong")
} # }