Package 'gpbiometrics'

Description

Aligns biometric rows to TTL/event markers and returns event-relative time and sample indices. The helper is conservative: TTL events are detected from rising edges by default, validity flags are used when available, and no physiological interpretation is added.

Usage

align_gazepoint_biometrics_to_ttl(
  data,
  ttl_cols = NULL,
  event_col = NULL,
  ttl_valid_col = NULL,
  time_col = NULL,
  sample_col = NULL,
  group_cols = NULL,
  participant_col = NULL,
  stimulus_col = NULL,
  trial_col = NULL,
  event_value = NULL,
  valid_values = c(TRUE, 1, "1"),
  event_edge = c("rising", "change", "active"),
  pre_window_ms = 1000,
  post_window_ms = 5000,
  pre_window_samples = NULL,
  post_window_samples = NULL,
  collapse_nearby_ms = 0,
  require_valid_ttl = TRUE
)

Arguments

Value

A list with overview, events, aligned_data, and settings.

Description

Computes summaries for specialised alternating-current EDA recordings. This function is for true AC admittance/susceptance data, not ordinary DC skin-conductance columns such as GSR_US.

Usage

analyze_gazepoint_ac_susceptance(
  dat,
  conductance_col = NULL,
  susceptance_col = NULL,
  admittance_col = NULL,
  phase_col = NULL,
  frequency_col = NULL,
  time_col = NULL,
  group_cols = NULL
)

Arguments

Value

A list with overview, timeseries, summary, and settings.

Description

Computes dependency-light linear Granger-style directionality tests between a respiration proxy and heart-rate or IBI/RR signal. This estimates predictive directionality in a VAR-style model. It does not prove physiological causality from observational data by itself.

Usage

analyze_gazepoint_cardiorespiratory_causality(
  dat,
  respiration_col,
  cardiac_col,
  time_col = NULL,
  group_cols = NULL,
  lag_order = 3,
  min_rows = 30,
  standardise = TRUE
)

Arguments

Value

A list with overview, causality_summary, and settings.

Description

Computes skin-potential level and skin-potential response descriptors from a voltage-like skin-potential column. This is for endosomatic skin-potential recordings, not standard exosomatic skin conductance.

Usage

analyze_gazepoint_skin_potential(
  dat,
  sp_col,
  time_col,
  group_cols = NULL,
  response_direction = c("both", "positive", "negative"),
  response_threshold = NULL,
  min_response_distance_s = 1
)

Arguments

Value

A list with overview, level_summary, response_table, timeseries, and settings.

Description

Computes descriptive quality-control summaries for a Gazepoint HRP/PPG waveform column. The output is intended for waveform availability, missingness, flatness, and timing-gap review. It does not infer diagnosis, emotion, valence, cognition, preference, or true physiological state.

Usage

assess_gazepoint_hrp_waveform_quality(
  data,
  hrp_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  min_rows = 20,
  min_finite_prop = 0.8,
  max_flat_prop = 0.95,
  flat_tolerance = 1e-08,
  max_gap_multiplier = 3
)

Arguments

Value

A list with overview, group_quality, row_flags, and settings.

Description

Summarises missingness and zero values for Gazepoint biometric columns. This is useful because Gazepoint exports may contain biometric columns even when a channel was inactive or invalid during recording.

Usage

audit_gazepoint_biometric_missingness(data, columns = NULL)

Arguments

Value

A data frame with one row per audited column.

Description

Audits timing or row-order information in Gazepoint Biometrics exports. The function checks monotonicity, duplicate timestamps, nonpositive intervals, and estimated sampling rate when the selected time column has a real time unit. If only CNT is available, the function can still check ordering but does not estimate a sampling rate unless time_unit is explicitly meaningful.

Usage

audit_gazepoint_biometric_sampling(
  data,
  group_columns = NULL,
  time_column = NULL,
  time_unit = c("seconds", "milliseconds", "microseconds", "samples"),
  expected_rate_hz = 60,
  tolerance_hz = 5
)

Arguments

Value

A data frame with one row per group.

Description

Combines time-order/reset diagnostics with conservative signal-lag summaries across signal pairs and groups. The helper is intended for quality control and synchronization review. It does not infer emotional valence, cognitive states, causal timing, or true physiological latency.

Usage

audit_gazepoint_biometric_sync_drift(
  data,
  time_col = NULL,
  group_cols = NULL,
  signal_pairs = NULL,
  signal_cols = NULL,
  reference_signal_col = NULL,
  max_lag = 1000,
  lag_step = NULL,
  drift_tolerance = NULL,
  method = c("pearson", "spearman"),
  min_complete_pairs = 20,
  use_first_difference = FALSE,
  include_reset_segments = TRUE
)

Arguments

Value

A list with overview, checks, time_reset_audit, lag_by_group, lag_profile, drift_summary, and settings.

Description

Compares signal distributions across sessions/blocks using baseline-vs-current differences, Kolmogorov-Smirnov tests, and Population Stability Index (PSI).

Usage

audit_gazepoint_distributional_drift(
  dat,
  signal_cols,
  session_col = "session",
  participant_col = NULL,
  reference_session = NULL,
  bins = 10,
  psi_warn = 0.1,
  psi_fail = 0.25
)

Arguments

Value

A list with overview, drift_summary, and settings.

Description

Flags row-level artifacts in Gazepoint electrodermal activity signals, preferring GSR_US conductance when available. The helper detects abrupt jumps, abrupt slopes, flatline runs, zero runs, negative conductance values, and optional out-of-range values. It is a conservative preprocessing/QC helper and does not interpret EDA as emotional valence.

Usage

audit_gazepoint_eda_artifacts(
  data,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  prefer_gsr_us = TRUE,
  jump_threshold_sd = 6,
  slope_threshold_sd = 6,
  flat_run_length = 20,
  zero_run_length = 20,
  saturation_min = NULL,
  saturation_max = NULL,
  negative_allowed = NULL
)

Arguments

Value

A list with overview, row_flags, artifact_runs, group_summary, and settings.

Description

Audits Gazepoint engagement-dial values for missingness, inactive rows, validity flags, plausible range, flatlining, and usable sample coverage.

Usage

audit_gazepoint_engagement_dial(
  data,
  value_column = "DIAL",
  validity_column = "DIALV",
  min_value = 0,
  max_value = 1,
  jump_threshold = NULL
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Audits Gazepoint GSR/EDA columns for missingness, inactive zero rows, validity flags, plausible value ranges, flatlining, and usable sample coverage. When available, GSR_US is used by default because it represents skin conductance in microsiemens in Gazepoint exports.

Usage

audit_gazepoint_gsr_quality(
  data,
  value_column = NULL,
  validity_column = "GSRV",
  min_value = 0,
  max_value = 100,
  jump_threshold = NULL
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Checks whether a Gazepoint GSR/EDA column looks more like conductance in microSiemens or resistance/impedance-like values in Ohms. This is a preprocessing safety audit, not a definitive device calibration test.

Usage

audit_gazepoint_gsr_units(
  dat,
  gsr_col = "GSR",
  convert = FALSE,
  output_col = NULL,
  resistance_to_us_factor = 1e+06
)

Arguments

Value

A list with overview, diagnostics, recommendation, and, when requested, data.

Description

Audits Gazepoint heart-rate values for missingness, inactive zero rows, validity flags, plausible value ranges, sudden jumps, flatlining, and usable sample coverage. HRV is treated as the heart-rate validity flag, not as a heart-rate-variability metric.

Usage

audit_gazepoint_hr_quality(
  data,
  value_column = "HR",
  validity_column = "HRV",
  min_value = 30,
  max_value = 220,
  jump_threshold = 25
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Audits inter-beat interval (IBI) or RR-interval values in Gazepoint Biometrics-style exports. This helper deliberately does not use raw HRV columns as HRV metrics. HRV-style summaries should be derived only from genuine IBI/RR interval columns.

Usage

audit_gazepoint_ibi_quality(
  data,
  ibi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  unit = c("auto", "milliseconds", "seconds"),
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  max_jump_ms = 500
)

Arguments

Value

A list with overview, samples, group_summary, and settings.

Examples

df <- data.frame(
  USER = rep(c("P1", "P2"), each = 4),
  IBI = c(800, 810, 790, 805, 900, 910, 905, 920)
)
audit_gazepoint_ibi_quality(df, group_cols = "USER")

Description

Screens biometric signal columns for missingness, all-zero channels, constant values, low variation, and active signal presence within groups. This helper is designed to identify inactive files or channels before event-level EDA, HR, IBI, or multimodal analysis.

Usage

audit_gazepoint_signal_activity(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  zero_is_inactive = TRUE,
  min_unique_nonzero = 2,
  missing_as_inactive = TRUE
)

Arguments

Value

A list with overview, signal_by_group, inactive_groups, inactive_signals, and settings.

Description

Flags or removes the initial stabilization period in each recording/group. This is intended to prevent early skin-electrode drift from being treated as a stable physiological baseline.

Usage

audit_gazepoint_stabilization_period(
  dat,
  time_col = "CNT",
  group_cols = NULL,
  stabilization_minutes = 10,
  action = c("flag", "trim"),
  output_col = "in_stabilization_period",
  time_units = c("auto", "seconds", "milliseconds")
)

Arguments

Value

A data frame with stabilization-period attributes.

Description

Detects negative time steps, duplicate time steps, non-finite time values, and recording segments within grouped Gazepoint biometric exports. This helper is intended for quality control and synchronization inspection. It does not alter raw values unless return_reindexed_time = TRUE, in which case an additional segment-relative time column is added.

Usage

audit_gazepoint_time_resets(
  data,
  time_col = NULL,
  group_cols = NULL,
  allow_ties = TRUE,
  split_on_negative_step = TRUE,
  return_reindexed_time = FALSE,
  min_segment_rows = 1
)

Arguments

Value

A list with overview, segment_summary, row_flags, data_with_segments, and settings.

Description

Adds a baseline-corrected GSR/EDA column to a Gazepoint Biometrics table. When available, GSR_US is used by default because it represents skin conductance in microsiemens in Gazepoint exports. The baseline is estimated from rows selected by baseline_rows, optionally within groups.

Usage

baseline_correct_gazepoint_gsr(
  data,
  baseline_rows,
  value_column = NULL,
  validity_column = "GSRV",
  group_columns = NULL,
  output_column = NULL,
  summary = c("mean", "median"),
  exclude_zero = TRUE
)

Arguments

Value

A data frame with the added baseline-corrected column and a baseline-summary attribute named "baseline_summary".

Description

Adds a baseline-corrected heart-rate column to a Gazepoint Biometrics table. HRV is treated as the heart-rate validity flag, not as a heart-rate variability metric.

Usage

baseline_correct_gazepoint_hr(
  data,
  baseline_rows,
  value_column = "HR",
  validity_column = "HRV",
  group_columns = NULL,
  output_column = NULL,
  summary = c("mean", "median"),
  exclude_zero = TRUE
)

Arguments

Value

A data frame with the added baseline-corrected column and a baseline-summary attribute named "baseline_summary".

Description

Applies subtractive or divisive baseline correction to pupil-size data within trials or other grouping units.

Usage

baseline_correct_gazepoint_pupil(
  dat,
  pupil_col = NULL,
  time_col = "CNT",
  stimulus_onset_col = NULL,
  trial_cols = NULL,
  baseline_window = c(-240, -200),
  baseline_function = c("median", "mean"),
  correction = c("subtract", "divide"),
  suffix = "_baseline_corrected",
  min_baseline_rows = 2,
  overwrite = FALSE
)

Arguments

Value

A data frame with a corrected pupil column and baseline attributes.

Description

Calculates dependency-light RSA proxy summaries from IBI/RR intervals and, optionally, PPG-derived respiration features from extract_gazepoint_pdr_signals(). This provides peak-to-trough and Porges-Bohrer-inspired band-power proxy summaries. These outputs should be interpreted as respiration-informed HRV/RSA features, not direct clinical vagal-tone estimates.

Usage

calculate_gazepoint_rsa(
  dat,
  ibi_col = "IBI",
  time_col = "CNT",
  group_cols = NULL,
  pdr = NULL,
  resp_rate_hz = NULL,
  respiration_band = c(0.12, 0.4),
  resample_rate = 4
)

Arguments

Value

A list with overview, rsa_summary, and settings.

Description

Checks whether a data frame contains known Gazepoint Biometrics columns. This function does not assume that the channels are active. It only checks whether the expected columns are present.

Usage

check_gazepoint_biometric_columns(data)

Arguments

Value

A data frame describing expected columns, their signal family, interpretation, and whether they are present.

Description

Checks whether an object follows the package's plotting return convention.

Usage

check_gazepoint_plot_contract(
  plot,
  require_plot_data = TRUE,
  require_settings = TRUE
)

Arguments

Value

A list with overview, checks, plot_data, and settings.

Description

Adds programmatic fixed-duration chunks/episodes to continuous biometric data. This is useful for baseline segmentation, repeated-measures feature extraction, and analyses that do not rely on external TTL markers.

Usage

chunk_gazepoint_biometrics(
  dat,
  time_col = "CNT",
  group_cols = NULL,
  chunk_seconds = 60,
  start_time = NULL,
  chunk_col = "chunk_id",
  episode_col = "episode_id",
  include_partial = FALSE
)

Arguments

Value

A data frame with chunk columns and chunk-summary attributes.

Description

Classifies descriptive EDA response patterns from an EDA/SCR feature column. The labels are intended for quality-control and descriptive reporting only. They do not infer emotion, valence, stress, trust, preference, cognition, or diagnosis.

Usage

classify_gazepoint_eda_response_pattern(
  data,
  response_col = NULL,
  group_cols = NULL,
  summary_function = c("max_abs", "mean_abs", "median_abs"),
  no_response_threshold = 0.01,
  low_response_threshold = 0.05,
  moderate_response_threshold = 0.2
)

Arguments

Value

A list with overview, classifications, and settings.

Description

Classifies extracted SCRs into first-, second-, and third-interval response windows based on response latency after stimulus onset.

Usage

classify_gazepoint_scr_intervals(
  dat,
  response_time_col = NULL,
  stimulus_onset_col = NULL,
  latency_col = NULL,
  output_col = "scr_interval",
  latency_output_col = "scr_latency_s",
  fir = c(1, 4),
  sir = c(4, 7),
  tir = c(7, 10)
)

Arguments

Value

A data frame with interval labels and latency metadata.

Description

Compares recorded HR against HR derived from genuine IBI/RR intervals using 60000 / IBI_ms.

Usage

compare_gazepoint_hr_ibi_consistency(
  data,
  hr_col = "HR",
  ibi_col = "IBI",
  time_col = NULL,
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  max_abs_diff_bpm = 10,
  max_rel_diff_prop = 0.15
)

Arguments

Value

A list with overview, row_diagnostics, group_summary, and settings.

Description

Converts GSR resistance values to conductance in microSiemens. The helper is intentionally conservative. If a conductance column such as GSR_US is already present, the data are returned unchanged unless overwrite = TRUE. If input_unit = "auto", conversion is performed only when the source column has a resistance-like name, such as GSR_OHMS or resistance_ohms.

Usage

convert_gazepoint_gsr_to_conductance(
  data,
  gsr_col = NULL,
  output_col = "GSR_US",
  input_unit = c("auto", "ohms", "kohms", "microsiemens"),
  overwrite = FALSE
)

Arguments

Details

Generic GSR columns are not automatically assumed to be resistance because Gazepoint exports and workflows may represent GSR/EDA differently. For a generic GSR column, use input_unit = "ohms" or input_unit = "kohms" only when the study documentation confirms resistance units.

Value

The input data frame with a conductance column when conversion is possible. A structured conversion summary is stored in the gsr_conversion_summary attribute.

Examples

df <- data.frame(GSR_OHMS = c(1000000, 500000, NA))
convert_gazepoint_gsr_to_conductance(df)

Description

Regresses an EDA/conductance signal on one or more continuous temperature covariates and returns a temperature-adjusted residual series. The adjusted signal is temperature-adjusted EDA, not "pure" cognitive or emotional EDA.

Usage

correct_gazepoint_eda_temperature(
  dat,
  eda_col = "GSR_US",
  temperature_cols,
  group_cols = NULL,
  time_col = NULL,
  output_col = "eda_temperature_adjusted",
  fitted_col = "eda_temperature_fitted",
  model_by_group = TRUE,
  add_intercept_mean = TRUE
)

Arguments

Value

A data frame with adjusted EDA columns and model-summary attributes.

Description

Creates a compact reporting checklist for Gazepoint Biometrics exports. The checklist summarises detected biometric channels, validation issues, signal quality, missingness, available workflow domains, and interpretation cautions. It is intended to support transparent manuscript reporting and reviewer-facing methods documentation.

Usage

create_gazepoint_biometrics_checklist(data, require_active_signal = TRUE)

Arguments

Value

A list with overview, channels, quality, missingness, validation_issues, workflow_capabilities, feature_inventory, reporting_guidance, and interpretation_cautions.

Description

Creates a structured inventory of implemented gpbiometrics helper functions. This is useful for reporting, readiness checks, documentation, and package development audits.

Usage

create_gazepoint_biometrics_feature_inventory(include_internal = FALSE)

Arguments

Value

A list with overview, inventory, domain_summary, missing_expected, and settings.

Description

Creates a compact draft methods paragraph describing Gazepoint Biometrics data processing. The text is intentionally cautious and avoids making emotional or cognitive claims from physiological or eye-tracking measures alone.

Usage

create_gazepoint_biometrics_methods_text(
  checklist = NULL,
  data = NULL,
  include_cautions = TRUE
)

Arguments

Value

A character string containing draft methods text.

Description

Creates a structured, manuscript-oriented report object for Gazepoint Biometrics data, workflow outputs, quality checks, report tables, methods text, and reporting checklists. The report is intentionally conservative: GSR/EDA is described as electrodermal activity/arousal-related signal rather than emotional valence; heart-rate interpretation is tied to baseline/task context; eye-tracking is described as visual attention rather than direct cognition; and raw HRV columns are not treated as HRV metrics.

Usage

create_gazepoint_biometrics_report(
  data = NULL,
  workflow = NULL,
  validation = NULL,
  quality = NULL,
  sampling = NULL,
  missingness = NULL,
  exclusions = NULL,
  report_tables = NULL,
  methods_text = NULL,
  checklist = NULL,
  title = "Gazepoint Biometrics report",
  subtitle = NULL,
  output_file = NULL,
  format = c("markdown", "html"),
  include_timestamp = FALSE,
  overwrite = FALSE,
  max_table_rows = 20L
)

Arguments

Details

The function can also write a lightweight Markdown or HTML file without adding heavy reporting dependencies.

Value

A list of class "gazepoint_biometrics_report" with overview, sections, tables, objects, output_file, and settings.

Examples

df <- data.frame(
  CNT = 1:5,
  GSR = c(1, 1.1, 1.2, 1.1, 1),
  HR = c(70, 71, 72, 71, 70),
  DIAL = c(40, 42, 44, 43, 41)
)
report <- create_gazepoint_biometrics_report(df)
names(report)

Description

Creates compact report-ready tables from a Gazepoint Biometrics workflow object or from separate workflow components. The function does not write files. It returns cleaned tables that can be printed, exported, or inserted into reports and supplementary materials.

Usage

create_gazepoint_biometrics_report_tables(
  workflow = NULL,
  validation = NULL,
  quality = NULL,
  sampling = NULL,
  diagnostics = NULL,
  exclusion_recommendations = NULL,
  ttl_events = NULL,
  max_ttl_events = 20
)

Arguments

Value

A list of report-ready tables.

Description

Creates a structured six-phase analysis pipeline for Gazepoint Biometrics EDA/GSR workflows. The helper maps each phase to native gpbiometrics functions, optional external-method bridges, and optional downstream model templates for brms and lme4.

Usage

create_gazepoint_eda_analysis_pipeline(
  include_external_bridges = TRUE,
  include_model_templates = TRUE,
  include_reporting_guidance = TRUE,
  style = c("compact", "detailed")
)

Arguments

Details

This function does not fit statistical models, does not run external software, and does not infer emotion, valence, stress, trust, preference, cognition, or diagnosis. It is a reproducible planning and reporting aid.

Value

A list with overview, phases, function_map, model_templates, reporting_guidance, interpretation_guardrails, and settings.

Description

Creates a cautious preregistration template for Gazepoint Biometrics EDA/GSR workflows.

Usage

create_gazepoint_preregistration_template(
  study_title = "Gazepoint biometrics study",
  signal_standardization = c("within_participant_z", "range_correction", "none"),
  artifact_rules = c("kleckner_style", "custom", "none"),
  eda_min_us = 0.01,
  eda_max_us = 100,
  rapid_change_threshold = 20,
  output_file = NULL
)

Arguments

Value

A character string.

Description

Creates descriptive tonic and phasic EDA columns from Gazepoint GSR/EDA data. If vendor-provided tonic/phasic columns such as GSR_US_TONIC and GSR_US_PHASIC are available, they are used by default. Otherwise, a simple rolling-median tonic estimate is used and the phasic component is calculated as signal minus tonic. This helper is intentionally conservative and does not replace specialised biosignal-processing software.

Usage

decompose_gazepoint_eda(
  data,
  signal_col = NULL,
  tonic_col = NULL,
  phasic_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  window_size = 31L,
  output_prefix = "eda",
  overwrite = FALSE
)

Arguments

Value

A data frame with added tonic, phasic, and method columns. Attributes include overview and settings.

Examples

df <- data.frame(CNT = 1:10, GSR_US = seq(1, 2, length.out = 10))
out <- decompose_gazepoint_eda(df, signal_col = "GSR_US", window_size = 3)
names(out)

Description

Applies a user-supplied reconstruction function or model to fixed-length EDA windows. No pretrained neural network is bundled. This function is an interoperability bridge for validated user-supplied autoencoders.

Usage

denoise_gazepoint_eda_autoencoder(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  model = NULL,
  window_samples = 128,
  output_col = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with reconstructed signal and denoising attributes.

Description

Applies simple Haar wavelet soft-threshold denoising to EDA signals within optional groups. This is a dependency-light wavelet denoising helper and should not be described as an exact reproduction of stationary-wavelet artifact-removal algorithms.

Usage

denoise_gazepoint_eda_wavelet(
  dat,
  eda_col = "GSR_US",
  group_cols = NULL,
  output_col = NULL,
  levels = 3,
  threshold_multiplier = 1,
  overwrite = FALSE
)

Arguments

Value

A data frame with denoised EDA and denoising attributes.

Description

Applies a user-supplied reconstruction function or model to fixed-length PPG windows. No pretrained neural network is bundled. This function is an interoperability bridge for validated user-supplied autoencoders.

Usage

denoise_gazepoint_ppg_autoencoder(
  dat,
  ppg_col = "HRP",
  time_col = NULL,
  group_cols = NULL,
  model = NULL,
  window_samples = 128,
  output_col = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with reconstructed signal and denoising attributes.

Description

Adds uniform white noise with magnitude tied to hardware resolution. This is intended only for nonlinear phase-space methods that are sensitive to exact repeated values caused by coarse interval quantization.

Usage

denoise_gazepoint_quantization_noise(
  dat,
  signal_cols,
  resolution,
  group_cols = NULL,
  output_suffix = "_quantization_jittered",
  seed = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with jittered columns and quantization-noise attributes.

Description

Detects whether GSR/EDA, heart-rate, engagement-dial, and TTL channels are present and whether they appear active. A channel can be present but inactive when validity flags are zero or the signal contains only zeros or missing values. For each signal family, summary_column identifies the primary column used for the reported minimum and maximum values.

Usage

detect_active_biometric_channels(data)

Arguments

Value

A data frame with one row per signal family.

Description

Detects likely biometric, timing, marker, and identifying columns in a Gazepoint Biometrics export. The function is deliberately descriptive. It reports what appears to be present and active, but it does not infer emotion, valence, or HRV from ambiguous raw columns.

Usage

detect_gazepoint_biometric_schema(data)

Arguments

Value

A list with overview, columns, time_columns, timebase, name_map, and notes.

Examples

df <- data.frame(
  CNT = 1:5,
  TIME = seq(0, by = 1 / 60, length.out = 5),
  GSR = c(100, 101, 102, 101, 100),
  HR = c(70, 71, 72, 71, 70),
  HRV = c(1, 1, 1, 1, 1)
)
detect_gazepoint_biometric_schema(df)

Description

Inspects timing and counter columns and returns a conservative summary of the likely primary timebase. Sampling rate is estimated only when numeric timing information is available and intervals are positive.

Usage

detect_gazepoint_biometric_timebase(data, time_col = NULL, counter_col = NULL)

Arguments

Value

A list with overview, time_columns, interval_summary, and warnings.

Examples

df <- data.frame(CNT = 1:5, TIME = seq(0, by = 1 / 60, length.out = 5))
detect_gazepoint_biometric_timebase(df)

Description

Detects abrupt changes in noisy biological time series using a dependency-light stochastic rolling-window approximation. The score combines adjacent-window changes in mean and variance with a robust adaptive threshold.

Usage

detect_gazepoint_doubly_stochastic_changepoints(
  dat,
  signal_col,
  time_col = "CNT",
  group_cols = NULL,
  window_seconds = 10,
  step_seconds = 2,
  threshold_mad_multiplier = 6,
  min_distance_s = 5
)

Arguments

Details

This is not a full reproduction of any specific doubly stochastic model. It is a transparent approximation for QC and exploratory segmentation.

Value

A list with overview, score_table, changepoints, and settings.

Description

Detects simple SCR-like peaks from a phasic EDA signal. If a phasic column is not supplied, the function first creates a descriptive phasic component using decompose_gazepoint_eda(). This helper is intended for exploratory quality control and descriptive summaries, not as a replacement for specialised SCR detection pipelines.

Usage

detect_gazepoint_scr_events(
  data,
  phasic_col = NULL,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  threshold = NULL,
  min_peak_distance = 10L,
  window_size = 31L
)

Arguments

Value

A list with overview, events, group_summary, and settings.

Examples

df <- data.frame(
  CNT = 1:20,
  GSR_US_PHASIC = c(rep(0, 5), 0.2, 0.8, 0.2, rep(0, 12))
)
detect_gazepoint_scr_events(df, phasic_col = "GSR_US_PHASIC", time_col = "CNT")

Description

Detects candidate skin conductance responses (SCRs) from Gazepoint EDA/GSR signals. The helper prefers a phasic channel such as GSR_US_PHASIC when available, and otherwise falls back to a conductance-like signal such as GSR_US. It returns explicit onset, peak, amplitude, rise-time, and recovery-time fields for downstream event-window summaries and statistical modelling.

Usage

detect_gazepoint_scr_peaks(
  data,
  signal_col = NULL,
  phasic_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  prefer_vendor_phasic = TRUE,
  amplitude_min = 0.01,
  recovery_fraction = 0.5,
  smooth_width = 1,
  min_peak_distance = 1
)

Arguments

Details

This is a conservative R-native peak detector. It is not a replacement for full model-based EDA decomposition tools such as Ledalab, PsPM, or cvxEDA.

Value

A list with overview, peaks, group_summary, signal_summary, and settings.

Description

Detects likely timing and counter columns in Gazepoint Biometrics exports. The function reports candidate timing columns rather than assuming that any single time variable is always present or always measured in the same unit.

Usage

detect_gazepoint_time_columns(data)

Arguments

Value

A data frame with one row per detected time-related column.

Examples

detect_gazepoint_time_columns(c("CNT", "TIME_MS", "GSR", "HR"))

Description

Creates a compact diagnostic readiness summary from a Gazepoint Biometrics workflow object. The function does not change or remove data. It returns a one-row decision table with pass/review/fail status and concise reasons.

Usage

diagnose_gazepoint_biometrics_workflow(
  workflow,
  require_gsr = TRUE,
  require_hr = TRUE,
  require_dial = FALSE,
  max_exclude_window_pct = 25,
  max_review_window_pct = 25
)

Arguments

Value

A one-row data frame with diagnostic status and reasons.

Description

Estimates the time shift that maximizes the association between two recorded biometric signals within each group. This is a conservative synchronization diagnostic for inspecting whether two recorded traces show similar temporal structure at different shifts. It should not be interpreted as causal timing or true physiological latency unless the design includes appropriate event markers and independently justified signal-processing assumptions.

Usage

estimate_gazepoint_signal_lag(
  data,
  signal_x_col,
  signal_y_col,
  time_col = NULL,
  group_cols = NULL,
  max_lag = 1000,
  lag_step = NULL,
  method = c("pearson", "spearman"),
  min_complete_pairs = 20,
  use_first_difference = FALSE
)

Arguments

Value

A list with overview, lag_by_group, lag_profile, and settings.

Description

Exports selected report tables, text outputs, optional plot objects, and a manifest to a local output directory. This helper is intended for reproducible reporting. It does not commit files and should not be used to export private real-data outputs into a package repository.

Usage

export_gazepoint_biometrics_report_bundle(
  bundle = NULL,
  output_dir,
  prefix = "gpbiometrics_report",
  tables = NULL,
  text = NULL,
  plots = NULL,
  include_readme = TRUE,
  include_session_info = TRUE,
  overwrite = FALSE
)

Arguments

Value

A list with overview, manifest, output_dir, and settings.

Description

Prepares cleaned inter-beat interval data for external HRV workflows. The helper writes simple beat tables with cumulative beat time and IBI/RR interval columns. It does not use the Gazepoint HRV column.

Usage

export_gazepoint_rhrv_input(
  data,
  ibi_col = "IBI_clean_ms",
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  collapse_repeated_intervals = TRUE,
  repeated_tolerance_ms = 1e-08,
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  output_dir = NULL,
  prefix = "gazepoint_rhrv"
)

Arguments

Value

A list with overview, beat_table, group_summary, manifest, and settings.

Description

Uses k-means clustering on the raw pulse waveform to classify likely heartbeat regions and then selects local extrema as beat candidates. This is a Gazepoint Biometrics-oriented fallback for difficult pulse waveforms, not an ECG-equivalent R-peak detector.

Usage

extract_gazepoint_beats_kmeans(
  dat,
  pulse_col = "HRP",
  time_col = "CNT",
  group_cols = NULL,
  k = 2,
  peak_polarity = c("positive", "negative"),
  min_distance_s = 0.3,
  sampling_rate = NULL,
  seed = NULL
)

Arguments

Value

A list with overview, beat_table, interval_table, timeseries, and settings.

Description

Computes left-right electrodermal activity asymmetry descriptors from two simultaneously recorded EDA channels. The function returns row-level asymmetry time series and group-level summaries.

Usage

extract_gazepoint_bilateral_eda_asymmetry(
  dat,
  left_col,
  right_col,
  time_col = NULL,
  group_cols = NULL,
  output_prefix = "beda"
)

Arguments

Details

These descriptors quantify bilateral EDA differences only. They do not infer hemisphere activation, amygdala activity, psychopathology, emotion, stress, cognition, health status, or diagnosis.

Value

A list with overview, asymmetry_timeseries, summary, and settings.

Description

Computes dependency-light EDA complexity descriptors, including sample entropy and detrended fluctuation analysis alpha.

Usage

extract_gazepoint_eda_complexity(
  dat,
  eda_col = "GSR_US",
  group_cols = NULL,
  min_samples = 32,
  sampen_m = 2,
  sampen_r_multiplier = 0.2
)

Arguments

Value

A list with overview, features, and settings.

Description

Computes power spectral density summaries for an EDA signal, including spectral power in the EDASymp-inspired 0.045–0.25 Hz band. This is a descriptive spectral feature and should not be interpreted as direct stress, emotion, valence, cognition, trust, preference, or diagnosis.

Usage

extract_gazepoint_eda_spectral_power(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  band = c(0.045, 0.25),
  min_samples = 32,
  detrend = TRUE
)

Arguments

Value

A list with overview, spectral_summary, settings, and interpretation text.

Description

Computes a dependency-light approximation of TVSymp-style time-varying spectral EDA power using sliding-window spectral analysis. The default band is 0.08–0.24 Hz, following the TVSymp literature. This function does not claim exact VFCDM reproduction.

Usage

extract_gazepoint_eda_tvsymp(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  band = c(0.08, 0.24),
  window_seconds = 60,
  step_seconds = 5,
  min_valid_fraction = 0.7,
  normalise = TRUE
)

Arguments

Value

A list with overview, tvsymp_timeseries, summary, and settings.

Description

Extracts an ECG-derived respiration proxy from beat-level ECG morphology features using principal component analysis. This function requires ECG-derived morphology columns, such as QRS amplitudes, widths, or sampled beat-shape features. It is not intended for HR, IBI, or PPG-only data.

Usage

extract_gazepoint_edr_pca(
  dat,
  ecg_cols,
  time_col = NULL,
  group_cols = NULL,
  n_components = 1,
  scale = TRUE,
  output_prefix = "edr_pca"
)

Arguments

Value

A list with overview, edr_timeseries, component_summary, and settings.

Description

Computes dependency-light heart-rate asymmetry descriptors from IBI/RR intervals, including acceleration/deceleration proportions, signed run summaries, and Guzik-style squared-difference asymmetry.

Usage

extract_gazepoint_hrv_asymmetry(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  zero_tolerance = 0
)

Arguments

Details

Positive IBI/RR differences are treated as decelerations because the heart period lengthens. Negative IBI/RR differences are treated as accelerations.

Value

A list with overview, features, run_table, and settings.

Description

Computes simple time-domain HRV features from genuine IBI/RR intervals. This helper does not use the Gazepoint HRV column as an HRV outcome.

Usage

extract_gazepoint_hrv_features(
  data,
  ibi_col = "IBI_clean_ms",
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  min_intervals = 3,
  min_duration_s = 30,
  diff_threshold_ms = 50,
  collapse_repeated_intervals = TRUE,
  repeated_tolerance_ms = 1e-08
)

Arguments

Value

A list with overview, features, settings.

Description

Computes dependency-light heart-rate fragmentation descriptors from IBI/RR intervals. Metrics include percentage of inflection points (PIP), inverse average segment length (IALS), percentage of short segments (PSS), percentage of alternation segments (PAS), and long/short segment summaries.

Usage

extract_gazepoint_hrv_fragmentation(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  zero_tolerance = 0,
  short_segment_length = 3
)

Arguments

Details

These are fragmentation descriptors of interbeat interval dynamics. They should not be interpreted as clinical diagnoses or direct autonomic-state labels by themselves.

Value

A list with overview, features, and settings.

Description

Computes fuzzy entropy and Lorenz/Poincare-derived cardiac sympathetic index style descriptors from IBI/RR intervals.

Usage

extract_gazepoint_hrv_fuzzy_csi(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  m = 2,
  r_multiplier = 0.2,
  fuzzy_power = 2,
  min_intervals = 10
)

Arguments

Details

These outputs are nonlinear/geometric HRV descriptors. They do not infer seizure status, diagnosis, health status, emotion, stress, or cognition.

Value

A list with overview, features, and settings.

Description

Computes dependency-light geometric HRV descriptors, including the HRV triangular index and an approximate TINN-style triangular interpolation width.

Usage

extract_gazepoint_hrv_geometric(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  bin_width = NULL
)

Arguments

Value

A list with overview, features, and settings.

Description

Computes dependency-light nonlinear HRV descriptors from IBI/RR intervals, including Poincare SD1/SD2, sample entropy, approximate entropy, multiscale entropy, and detrended fluctuation analysis.

Usage

extract_gazepoint_hrv_nonlinear(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  min_intervals = 10,
  sampen_m = 2,
  sampen_r_multiplier = 0.2,
  mse_scales = 1:5
)

Arguments

Details

These are variability and complexity descriptors. They should not be interpreted as direct emotion, cognitive-load, health-status, or diagnostic labels by themselves.

Value

A list with overview, features, and settings.

Description

Computes refined composite multiscale entropy (RCMSE) from IBI/RR intervals. RCMSE pools template-match counts across all coarse-grained offsets at each scale, making it more stable than ordinary MSE for shorter physiological time series.

Usage

extract_gazepoint_hrv_rcmse(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  scales = 1:10,
  m = 2,
  r_multiplier = 0.2,
  min_intervals = 20
)

Arguments

Value

A list with overview, rcmse_by_scale, summary, and settings.

Description

Computes dependency-light recurrence quantification analysis (RQA) features from IBI/RR intervals. This is intended as a compact nonlinear HRV summary and not as a clinical diagnostic tool.

Usage

extract_gazepoint_hrv_rqa(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  embedding_dimension = 2,
  delay = 1,
  radius = NULL,
  radius_multiplier = 0.2,
  min_line_length = 2
)

Arguments

Value

A list with overview, features, and settings.

Description

Extracts dependency-light PPG-derived respiration proxy features from a Gazepoint pulse/PPG waveform. The function estimates respiration-modulated pulse features such as respiratory-induced intensity variability (RIIV), pulse amplitude variability (PAV), pulse width variability (PWV), and pulse-rate variability (PRV).

Usage

extract_gazepoint_pdr_signals(
  dat,
  ppg_col = "HRP",
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  min_peak_distance_s = 0.3,
  smooth_window = 5,
  respiration_band = c(0.1, 0.6),
  pdr_resample_rate = 4
)

Arguments

Details

These are proxy respiratory features. They should not be treated as a replacement for a respiration belt or clinical respiratory measurement.

Value

A list with overview, pulse_features, pdr_timeseries, pdr_summary, and settings.

Description

Extracts respiration-like components from PPG or ECG-derived respiratory proxy signals. If external_fun is supplied, it is used as the CEEMDAN backend. Otherwise, the function uses a dependency-light multiscale decomposition fallback and labels the result accordingly.

Usage

extract_gazepoint_respiration_ceemdan(
  dat,
  signal_col,
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  respiration_band = c(0.1, 0.6),
  scales = c(5, 15, 30, 60, 120),
  external_fun = NULL
)

Arguments

Details

This function does not claim to reproduce full CEEMDAN unless a validated external CEEMDAN function is supplied.

Value

A list with overview, component_table, respiration_timeseries, summary, and settings.

Description

Extracts 50 percent half-recovery time (rec.t2) and 63 percent recovery time (rec.tc) for skin conductance responses from an EDA waveform and event onsets.

Usage

extract_gazepoint_scr_recovery_times(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  event_onset_col = NULL,
  group_cols = NULL,
  pre_onset_baseline_s = 2,
  peak_window_s = 5,
  recovery_window_s = 20
)

Arguments

Value

A list with overview, recovery_table, and settings.

Description

Extracts TTL marker events from Gazepoint Biometrics exports. The function can return either rows where TTL marker values change or all nonzero TTL rows. By default, rows are retained only when the TTL validity column is present and greater than zero. This avoids treating invalid placeholder TTL values as experimental events.

Usage

extract_gazepoint_ttl_events(
  data,
  ttl_columns = NULL,
  group_columns = NULL,
  validity_column = "TTLV",
  require_validity = TRUE,
  mode = c("changes", "nonzero"),
  include_initial = TRUE
)

Arguments

Value

A data frame of TTL events.

Description

Flags and optionally cleans implausible inter-beat interval values. The helper is conservative and does not remove rows; instead, it returns row-level flags and a cleaned IBI column with implausible values set to NA.

Usage

filter_gazepoint_ibi_implausible(
  data,
  ibi_col = "IBI",
  time_col = NULL,
  group_cols = NULL,
  validity_col = NULL,
  unit = c("auto", "ms", "seconds"),
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  max_change_ms = 400,
  max_change_prop = 0.3,
  output_col = "IBI_clean_ms"
)

Arguments

Value

A list with overview, data, row_flags, group_summary, and settings.

Description

Applies a user-supplied model or prediction function to segment-level artifact features. No pretrained model is bundled, so this function avoids pretending to reproduce any proprietary or externally trained classifier.

Usage

flag_gazepoint_artifacts_svm(
  x,
  model = NULL,
  feature_cols = NULL,
  probability_threshold = 0.5,
  ...
)

Arguments

Value

A data frame with artifact probabilities/classes where available.

Description

Flags missing-value runs and sustained flatline runs in Gazepoint biometric signal columns. Missing dropouts are defined as consecutive missing or non-finite numeric samples. Flatline dropouts are defined as consecutive finite numeric samples that remain unchanged within a tolerance.

Usage

flag_gazepoint_biometric_dropouts(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  time_col = NULL,
  min_missing_run = 5L,
  min_flatline_run = 10L,
  constant_tolerance = 0,
  prefix = "biometric_dropout"
)

Arguments

Details

The function adds row-level flags and stores a dropout summary in the returned data frame attributes. It does not remove rows.

Value

The input data frame with added logical dropout columns. The attributes dropout_summary and dropout_settings contain structured summaries.

Examples

df <- data.frame(
  CNT = 1:8,
  GSR = c(1, NA, NA, NA, 2, 2, 2, 3),
  HR = c(70, 71, 72, 73, 74, 75, 76, 77)
)
flag_gazepoint_biometric_dropouts(df, min_missing_run = 3, min_flatline_run = 3)

Description

Flags dependency-light, subject-specific EDA artifact categories using robust median absolute deviation (MAD) logic. The categories are heuristic QC labels: step artifacts, needle artifacts, flatline artifacts, and wall artifacts.

Usage

flag_gazepoint_mad_artifacts(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  mad_multiplier = 8,
  flatline_tolerance = 1e-06,
  flatline_min_run = 5,
  wall_abs_change = NULL,
  output_prefix = "mad"
)

Arguments

Value

A data frame with artifact flags and artifact-summary attributes.

Description

Applies simple transparent EDA artifact flags: non-finite values, physiological range violations, rapid percent change per second, and transitional padding around flagged samples.

Usage

flag_kleckner_eda_artifacts(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  min_us = 0.01,
  max_us = 100,
  max_abs_percent_change_per_second = 20,
  transition_padding = 1,
  output_prefix = "kleckner"
)

Arguments

Details

This helper is Kleckner-style rather than a claim of exact reproduction of every rule in a specific external implementation.

Value

A data frame with artifact flag columns and summary attributes.

Description

Adds user-facing labels and interpretation metadata to the package feature inventory. This helper is intentionally non-breaking: it does not replace the core inventory object returned by create_gazepoint_biometrics_feature_inventory().

Usage

format_gazepoint_biometrics_feature_inventory(
  inventory = NULL,
  include_internal = FALSE,
  sort = TRUE
)

Arguments

Value

A data frame with polished user-facing inventory columns.

Description

Fuses two respiration proxy streams, such as PPG-derived respiration and ECG-derived respiration, using a transparent one-dimensional Kalman filter. This is a linear Kalman fusion helper. It is not an extended Kalman filter unless the user supplies nonlinear state/measurement logic externally.

Usage

fuse_gazepoint_respiration_kalman(
  dat,
  primary_col,
  secondary_col,
  time_col = NULL,
  group_cols = NULL,
  process_var = 0.01,
  primary_var = 0.05,
  secondary_var = 0.05,
  output_col = "respiration_kalman_fused"
)

Arguments

Value

A data frame with fused respiration output and Kalman attributes.

Description

Extract stored plot data

Usage

get_gazepoint_plot_data(plot)

Arguments

Value

A data frame.

Description

Extract stored plot settings

Usage

get_gazepoint_plot_settings(plot)

Arguments

Value

A list.

Description

Reads rectangular Gazepoint CSV exports from a folder and combines files that contain at least one known Gazepoint Biometrics column. This function is designed for all-gaze and fixation-style exports. Multi-section Gazepoint Data Summary files should be parsed separately.

Usage

import_gazepoint_biometric_folder(
  path,
  pattern = "\\.csv$",
  recursive = FALSE,
  include_fixations = TRUE,
  include_all_gaze = TRUE,
  include_other_csv = FALSE,
  na = c("", "NA", "NaN")
)

Arguments

Value

A data frame with all imported rows combined. The output includes a source_file column and has class "gazepoint_biometrics_folder".

Description

Reads a Gazepoint CSV export containing biometric columns such as GSR, heart rate, interbeat interval, pulse signal, engagement dial, and TTL synchronization fields. The function is conservative: it preserves original column names, removes only empty trailing columns, and attaches a basic biometric-column summary as an attribute.

Usage

import_gazepoint_biometrics(file, na = c("", "NA", "NaN"))

Arguments

Value

A data frame with Gazepoint export columns preserved. The returned object has class "gazepoint_biometrics" and an attribute named "biometric_columns".

Description

Reads a multi-section Data_Summary_export_*.csv file produced by Gazepoint Analysis. These files are not ordinary rectangular CSV files. They contain metadata followed by sections such as ⁠AOI Summary⁠ and ⁠AOI Statistics (for each user)⁠. The latter may include AOI-level biometric summaries such as average dial value, average GSR, average heart rate, average interbeat interval, and pupil diameter.

Usage

import_gazepoint_data_summary(file)

Arguments

Value

A list with metadata, aoi_summary, and aoi_statistics data frames. The returned object has class "gazepoint_data_summary".

Description

Reads an XDF file through the optional Python pyxdf package via reticulate. This supports high-end LSL workflows without making Python a hard dependency of gpbiometrics.

Usage

import_gazepoint_lsl_xdf(
  path,
  stream_name_pattern = "Gazepoint|GP3|GSR|EDA|Biometric|TTL|Pupil|Gaze",
  include_all_streams = FALSE,
  flatten = TRUE,
  pyxdf_module = "pyxdf"
)

Arguments

Value

A list with overview, streams, header, and settings.

Description

Compatibility wrapper for join_gazepoint_biometrics_to_master(). This alias is provided for users who work with a gp3tools master table and want an explicit gp3tools-facing function name. The implementation delegates to the canonical biometric-to-master join helper.

Usage

join_gazepoint_biometrics_to_gp3tools(biometrics, gp3tools_master, ...)

Arguments

Value

The output of join_gazepoint_biometrics_to_master().

Examples

biometrics <- data.frame(USER = rep("P1", 3), CNT = 1:3, HR = c(70, 71, 72))
master <- data.frame(USER = rep("P1", 3), CNT = 1:3, AOI = c("A", "B", "A"))
join_gazepoint_biometrics_to_gp3tools(
  biometrics,
  master,
  by = c("USER", "CNT")
)

Description

Convenience wrapper around sync_gazepoint_biometrics_with_gaze() for joining biometric data to a gp3tools-style master table or any other analysis-ready gaze table.

Usage

join_gazepoint_biometrics_to_master(master, biometrics, by, all_x = TRUE)

Arguments

Value

A data frame with biometric columns joined to the master table.

Description

Creates event-time, inter-event interval, and inverse-Gaussian-style summary tables for EDA/SCR events. Events can be supplied directly through an event column or derived from positive EDA-derivative bursts.

Usage

model_gazepoint_eda_point_process(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  event_time_col = NULL,
  event_indicator_col = NULL,
  derivative_mad_multiplier = 6,
  min_event_distance_s = 1
)

Arguments

Details

This function is a compact point-process summary/model-preparation helper. It does not fit a full latent sympathetic state-space model.

Value

A list with overview, event_table, interval_table, process_summary, and settings.

Description

Creates beat-time, interbeat interval, and inverse-Gaussian-style summary tables from IBI/RR intervals. This is a compact point-process model-preparation helper, not a full adaptive Bayesian heartbeat filter.

Usage

model_gazepoint_hr_point_process(
  dat,
  ibi_col = "IBI",
  time_col = NULL,
  beat_time_col = NULL,
  group_cols = NULL,
  ibi_units = c("auto", "seconds", "milliseconds")
)

Arguments

Value

A list with overview, beat_table, interval_table, process_summary, and settings.

Description

Builds an impulse-train representation of heartbeat timing from IBI/RR intervals or beat times and computes a simple spectrum of the resulting impulse train. This is an IPFM-style model-preparation helper, not a perfect reconstruction of sinoatrial-node physiology.

Usage

model_gazepoint_hrv_ipfm(
  dat,
  ibi_col = "IBI",
  beat_time_col = NULL,
  group_cols = NULL,
  ibi_units = c("auto", "seconds", "milliseconds"),
  output_sampling_rate = 4,
  max_frequency = 0.5
)

Arguments

Value

A list with overview, beat_table, impulse_table, spectrum_table, summary, and settings.

Description

Performs a dependency-light grid search over the slow Bateman impulse-response time constant used in cvxEDA-style EDA decomposition workflows. The default fast time constant is fixed at 0.7 seconds and the slow time constant is searched between 2 and 4 seconds. This function does not run the original cvxEDA optimisation; it provides a subject-specific tau-selection bridge for downstream cvxEDA-style workflows.

Usage

optimize_gazepoint_cvxeda_tau(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  tau0_grid = seq(2, 4, by = 0.25),
  tau1 = 0.7,
  sampling_rate = NULL,
  ridge_lambda = 0.01,
  max_irf_seconds = 20
)

Arguments

Value

A list with overview, best_tau, optimization_table, and settings.

Description

Plots AOI-biometric summary values as a ggplot object.

Usage

plot_gazepoint_aoi_biometrics(
  x,
  value_col = "mean_value",
  aoi_col = "aoi_label",
  signal_col = "signal",
  group_col = NULL,
  plot_type = c("boxplot", "point", "line"),
  title = NULL
)

Arguments

Value

A ggplot object with plot data stored in attributes.

Description

Plots and summarises biometric quality indicators such as dropout flags, validity flags, missingness flags, and quality/audit flags. When no explicit quality columns are available, the function can derive missingness indicators from detected biometric signal columns.

Usage

plot_gazepoint_biometric_quality(
  data,
  quality_cols = NULL,
  signal_cols = NULL,
  time_col = NULL,
  group_col = NULL,
  dropout_prefix = "biometric_dropout",
  max_points = 5000L,
  main = NULL,
  plot = TRUE,
  ...
)

Arguments

Value

A list with overview, quality_summary, group_summary, plot_data, and settings.

Examples

df <- data.frame(
  CNT = 1:5,
  GSR = c(1, NA, 1.2, 1.1, NA),
  HR_valid = c(1, 1, 0, 1, 1)
)
plot_gazepoint_biometric_quality(df, signal_cols = "GSR", plot = FALSE)