Title: Automated Cardiac Data Processing via ACF, GA & Tracking Index
Version: 0.4.2
Maintainer: Yi-Fei Gu <guyf0601@connect.hku.hk>
Description: An algorithm developed to efficiently and accurately process complex and variable cardiac data with three key features: 1. employing autocorrelation to identify recurrent heartbeats and use their periods to compute heart rates; 2. incorporating a genetic algorithm framework to minimize data loss due to noise interference and accommodate within-sequence variations; and 3. introducing a tracking index as a moving reference to reduce errors. Lau, Wong, & Gu (2026) https://ssrn.com/abstract=5153081.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.3.0)
Imports: data.table, doParallel, dplyr, foreach, ggplot2, purrr, RColorBrewer, stringr
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-02-10 09:37:37 UTC; yg
Author: Sarah Lau ORCID iD [aut, ctb], Adrian Wong [aut, ctb], Yi-Fei Gu ORCID iD [aut, cre]
Repository: CRAN
Date/Publication: 2026-02-12 20:30:08 UTC

CardiacDP - collatedata()

Description

Automatically read and collate separate .csv files in chronological order as inferred by the file names and in hierarchy.

Usage

collatedata(file_path, output_file = NULL, verbose = FALSE)

Arguments

file_path

Designate the path to your file, must be a .zip file

output_file

Optional path to write the collated data table as a CSV file. May be either a full file path (e.g. /path/to/out.csv) or an output directory (e.g. /path/to/outdir). If a directory (or a path without a file extension) is provided, a file named <input_stem>_collated.csv is written inside it. Default NULL (no file written).

verbose

Logical; if TRUE, emit progress messages. Default FALSE.

Value

A single collated data table

Examples

zip_path <- system.file("extdata", "example.zip", package = "CardiacDP")
collated <- collatedata(zip_path)

CardiacDP - computeHR()

Description

Employing the autocorrelation function (ACF) with a genetic algorithm framework to locate periodic sub-sequences within each sequence. From the candidate heart rates of these sub-sequences, the final results are either evaluated based on the autocorrelation value or a tracking index (TI).

Usage

computeHR(
  file_path,
  reduce_res = 0.01,
  pop_size = 10L,
  max_gen = 20L,
  patience = 2L,
  an_in = 1,
  acf_thres = 0.5,
  lr_thres = 0.7,
  ncore = NULL,
  output_dir = NULL,
  save_outputs = FALSE,
  verbose = FALSE
)

Arguments

file_path

Designate the path to your file, must be a .zip or .csv file

reduce_res

Time interval of reduced resolution (seconds), by default 0.01

pop_size

Number of populations used in the genetic algorithm, by default 10L

max_gen

Maximum number of generations in the genetic algorithm, by default 20L

patience

Patience threshold (maximum number of generations with no further changes) in the genetic algorithm, by default 2L

an_in

Analysis interval (length of a sequence; in minute), by default 1

acf_thres

Threshold used in ACF to classify periodic oscillations from aperiodic noises, by default 0.5

lr_thres

Linear regression r-sq threshold in extrapolating the tracking index, by default 0.7

ncore

Integer; number of CPU cores to use for the genetic algorithm. If NULL (default), uses parallel::detectCores() - 1. During ⁠R CMD check⁠, cores are clamped to a small number to satisfy check limits.

output_dir

Optional directory to write CSV/PNG outputs when save_outputs = TRUE. If NULL, defaults to tempdir().

save_outputs

Logical; if TRUE, write CSV/PNG outputs to output_dir. Default FALSE.

verbose

Logical; if TRUE, emit progress messages. Default FALSE.

Value

The positions (in indices) and durations of the sub-sequences (finalsubseq) and the corresponding candidate HR (candidateHR) obtained from the genetic algorithm, and the final results evaluating the candidates by autocorrelation values (results_ACF) or the tracking index (results_TI), which contains the details of the subsequences after checking for resolution (subseqHR with Time_min column), the weighted heart rate per sequence (weightedHR with Time_min column) and a plot (plot). If save_outputs = TRUE, file paths are recorded in output$files.

Examples


# use the default parameters to analyse a zip file
# the collatedata function will be called automatically
zip_path <- system.file("extdata", "example.zip", package = "CardiacDP")
computeHR(file_path = zip_path, save_outputs = FALSE)



# use the default parameters to analyse a csv file
csv_path <- system.file("extdata", "example.csv", package = "CardiacDP")
computeHR(file_path = csv_path, reduce_res = 0.1,
          save_outputs = FALSE)



# use customized parameters to analyse a zip file
zip_path <- system.file("extdata", "example.zip", package = "CardiacDP")
computeHR(zip_path, reduce_res = 0.1, max_gen = 30L,
          lr_thres = 0.8, save_outputs = FALSE)



# use custom parameters to analyse a csv file
csv_path <- system.file("extdata", "example.csv", package = "CardiacDP")
computeHR(csv_path, reduce_res = 0.1, pop_size = 20L,
          an_in = 1, acf_thres = 0.6, save_outputs = FALSE)