Skip to content

internal api

Jump to bottom
GitHub Actions edited this page Aug 14, 2025 · 2 revisions

Internal API Reference

Introduction

Below is comprehensive documentation for all internal functions in the eyeris R package. These functions are primarily intended for advanced users and developers who need to customize the preprocessing pipeline or understand the internal workings of the package.

Overview

The eyeris package is built with a modular architecture where each preprocessing step is implemented through both public (exported) and internal functions. The public functions provide the user-facing API, while the internal functions contain the core processing logic.

Note: Functions marked with @keywords internal are not exported and should be accessed using the ::: operator (e.g., eyeris:::function_name()). Use these functions at your own discretion as they may change without notice in future versions.

Core Processing Functions

Blink Removal

deblink_pupil()

File: R/pipeline-deblink.R
Description: Internal function to remove blink artifacts from pupil data by extending NA padding around detected blinks.

eyeris:::deblink_pupil(x, prev_op, extend)

Parameters:

  • x: A data frame containing pupil data
  • prev_op: The name of the previous operation’s pupil column
  • extend: Number of samples to extend padding before/after blinks

Returns: A numeric vector with blink artifacts removed (set to NA)

Transient Artifact Removal

detransient_pupil()

File: R/pipeline-detransient.R
Description: Internal function to remove transient artifacts from pupil data using speed-based thresholding.

eyeris:::detransient_pupil(x, prev_op, n, mad_thresh)

Parameters:

  • x: A data frame containing pupil data with columns time_secs and the previous operation’s pupil column
  • prev_op: The name of the previous operation’s pupil column
  • n: The constant used to compute the median absolute deviation (MAD) threshold (default: 16)
  • mad_thresh: Optional threshold override

Returns: A numeric vector with transient artifacts removed (set to NA)

speed()

File: R/pipeline-detransient.R
Description: Calculate pupil speed using finite differences between consecutive time points.

eyeris:::speed(x, y)

Parameters:

  • x: A numeric vector of pupil data
  • y: A numeric vector of time data

Returns: A vector of pupil speeds at each time point

Interpolation

interpolate_pupil()

File: R/pipeline-interpolate.R
Description: Interpolate missing pupil data using linear interpolation.

eyeris:::interpolate_pupil(x, prev_op, verbose)

Parameters:

  • x: A data frame containing pupil data
  • prev_op: The name of the previous operation’s pupil column
  • verbose: Logical, whether to print verbose output

Returns: A vector of interpolated pupil values

Filtering and Signal Processing

lpfilt_pupil()

File: R/pipeline-lpfilt.R
Description: Internal function to apply low-pass filtering to pupil data using Butterworth filter design.

eyeris:::lpfilt_pupil(x, prev_op, wp, ws, rp, rs, fs, plot_freqz)

Parameters:

  • x: A data frame containing pupil data
  • prev_op: Previous operation’s pupil column name
  • wp: Passband frequency (Hz)
  • ws: Stopband frequency (Hz)
  • rp: Maximum ripple in passband (dB)
  • rs: Minimum attenuation in stopband (dB)
  • fs: Sampling frequency
  • plot_freqz: Whether to plot frequency response

Returns: A vector of filtered pupil data

downsample_pupil()

File: R/pipeline-downsample.R
Description: Internal function to downsample pupil data with anti-aliasing filtering.

eyeris:::downsample_pupil(x, prev_op, target_fs, plot_freqz, current_fs, rp, rs)

Parameters:

  • x: Data frame containing pupil data
  • prev_op: Previous operation’s column name
  • target_fs: Target sampling frequency
  • plot_freqz: Whether to plot frequency response
  • current_fs: Current sampling frequency
  • rp, rs: Filter design parameters

Returns: A list containing the downsampled data and the decimated sample rate

bin_pupil()

File: R/pipeline-bin.R
Description: Bin pupil data into specified time bins using averaging or other methods.

eyeris:::bin_pupil(x, prev_op, bins_per_second, method, current_fs)

Parameters:

  • x: Data frame containing pupil data
  • prev_op: Previous operation’s column name
  • bins_per_second: Number of bins per second
  • method: Binning method (“mean”, “median”, etc.)
  • current_fs: Current sampling frequency

Returns: A data frame with binned pupil data

Statistical Processing

detrend_pupil()

File: R/pipeline-detrend.R
Description: Internal function to detrend pupil data using linear regression.

eyeris:::detrend_pupil(x, prev_op)

Parameters:

  • x: Data frame containing pupil data
  • prev_op: Previous operation’s column name

Returns: A list containing the fitted values, coefficients, and residuals

zscore_pupil()

File: R/pipeline-zscore.R
Description: Internal function to z-score normalize pupil data.

eyeris:::zscore_pupil(x, prev_op)

Parameters:

  • x: Data frame containing pupil data
  • prev_op: Previous operation’s column name

Returns: A numeric vector of z-scored pupil data

get_zscores()

File: R/pipeline-zscore.R
Description: Calculate z-scores for a numeric vector.

eyeris:::get_zscores(x)

Parameters:

  • x: Numeric vector

Returns: A numeric vector of z-scores

Epoching Functions

Core Epoching Logic

epoch_pupil()

File: R/pipeline-epoch.R
Description: Main epoching and baselining logic that coordinates the epoching process.

eyeris:::epoch_pupil(x, prev_op, evs, lims, label, c_bline, a_bline, bline_type, bline_evs, bline_per, hz, verbose)

Parameters:

  • x: Data frame containing pupil data
  • prev_op: Previous operation’s column name
  • evs: Event specification (start/end messages or timestamps)
  • lims: Time limits around events
  • label: Epoch label
  • c_bline, a_bline: Deprecated baseline calculation and application options
  • bline_type: Baseline type (“divisive”, “subtractive”)
  • bline_evs: Baseline events
  • bline_per: Baseline period
  • hz: Sampling frequency
  • verbose: Verbose output

Returns: A list containing epoch and baseline results

epoch_and_baseline_block()

File: R/pipeline-epoch.R
Description: Block-by-block epoch and baseline handler for multi-block data.

eyeris:::epoch_and_baseline_block(x, blk, lab, evs, lims, msg_s, msg_e, c_bline, a_bline, bline_type, bline_evs, bline_per, hz, verbose)

Returns: A list containing epoch and baseline results for the specified block

process_epoch_and_baselines()

File: R/pipeline-epoch.R
Description: Epoch and baseline processor that handles the core epoching mathematics.

eyeris:::process_epoch_and_baselines(eyeris, timestamps, evs, lims, hz, verbose)

Returns: A list containing epoch and baseline results

Epoching Strategies

epoch_manually()

File: R/pipeline-epoch.R
Description: Manually epoch using provided start/end dataframes of timestamps.

eyeris:::epoch_manually(eyeris, ts_list, hz, verbose)

epoch_only_start_msg()

File: R/pipeline-epoch.R
Description: Epoch based on a single event message without explicit limits.

eyeris:::epoch_only_start_msg(eyeris, start, hz, verbose)

epoch_start_msg_and_limits()

File: R/pipeline-epoch.R
Description: Epoch using a start message with fixed limits around it.

eyeris:::epoch_start_msg_and_limits(eyeris, start, lims, hz, verbose)

epoch_start_end_msg()

File: R/pipeline-epoch.R
Description: Epoch using both start and end messages with explicit timestamps.

eyeris:::epoch_start_end_msg(eyeris, start, end, hz, verbose)

Confounds Analysis Functions

Core Confounds Calculation

get_confounds_for_step()

File: R/pipeline-confounds.R
Description: Calculate comprehensive confounding variables for a single pupil data processing step.

eyeris:::get_confounds_for_step(pupil_df, pupil_vec, screen_width, screen_height, hz)

Parameters:

  • pupil_df: Data frame containing pupil data
  • pupil_vec: Vector of pupil values for current step
  • screen_width, screen_height: Screen dimensions in pixels
  • hz: Sampling frequency

Returns: A data frame containing confounds metrics for the current step

calculate_epoched_confounds()

File: R/pipeline-confounds.R
Description: Calculate confounds specifically for epoched data.

eyeris:::calculate_epoched_confounds(eyeris, epoch_names, hz, verbose)

Returns: An updated eyeris object with epoched confounds

Data Quality Metrics

tag_blinks()

File: R/pipeline-confounds.R
Description: Tag blinks in pupil data based on missing values and physiological constraints.

eyeris:::tag_blinks(pupil_df, pupil_vec)

Returns: A data frame with added column: is_blink

calc_euclidean_dist()

File: R/pipeline-confounds.R
Description: Calculate Euclidean distance between consecutive gaze points.

eyeris:::calc_euclidean_dist(x1, y1, x2, y2)

Returns: A numeric vector of Euclidean distances

normalize_gaze_coords()

File: R/pipeline-confounds.R
Description: Normalize gaze coordinates to screen-relative units (0-1 range).

eyeris:::normalize_gaze_coords(pupil_df, screen_width, screen_height)

Returns: A data frame with added normalized coordinate columns

tag_gaze_coords()

File: R/pipeline-confounds.R
Description: Tag gaze coordinates as on-screen or off-screen.

eyeris:::tag_gaze_coords(pupil_df, screen_width, screen_height, overshoot_buffer)

Returns: A data frame with added column: is_offscreen

Export Functions

export_confounds_to_csv()

File: R/pipeline-confounds.R
Description: Export confounds data to CSV files and/or database with comprehensive error handling.

eyeris:::export_confounds_to_csv(confounds_list, output_dir, filename_prefix, verbose, run_num, csv_enabled, db_con, sub, ses, task, eye_suffix, epoch_label)

Returns: Invisibly returns a vector of created file paths

Logging System

Core Logging Functions

get_log_timestamp()

File: R/core-logging.R
Description: Generate formatted timestamp for logging messages.

eyeris:::get_log_timestamp()

Returns: Character string with current timestamp in format [YYYY-MM-DD HH:MM:SS]

log_message()

File: R/core-logging.R
Description: Core logging function with timestamp and glue-style string interpolation.

eyeris:::log_message(level, ..., verbose, wrap, .envir)

Parameters:

  • level: Log level (“INFO”, “SUCCESS”, “WARN”, “ERROR”)
  • ...: Message components (supports glue syntax)
  • verbose: Whether to display the message
  • wrap: Whether to wrap long messages
  • .envir: Environment for variable evaluation

log_info(), log_success(), log_warn(), log_error()

File: R/core-logging.R
Description: Specialized logging functions for different message types.

eyeris:::log_info(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())
eyeris:::log_success(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())
eyeris:::log_warn(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())
eyeris:::log_error(..., wrap = TRUE, .envir = parent.frame())

Validation and Quality Control

Input Validation

check_input()

File: R/utils-checks.R
Description: Check if input argument is provided and not NULL.

eyeris:::check_input(arg)

check_data()

File: R/utils-checks.R
Description: Comprehensive validation of eyeris object data structure.

eyeris:::check_data(eyeris, fun)

check_time_monotonic()

File: R/utils-checks.R
Description: Verify that time series data is monotonically increasing.

eyeris:::check_time_monotonic(time_vector, time_col_name)

is_binocular_object()

File: R/utils-checks.R
Description: Determine if an eyeris object contains binocular data.

eyeris:::is_binocular_object(x)

Returns: Logical indicating if object is binocular

Directory Management

check_and_create_dir()

File: R/utils-checks.R
Description: Check for directory existence and create if needed with proper error handling.

eyeris:::check_and_create_dir(basedir, dir, verbose)

Database Functions

Connection Management

connect_eyeris_database()

File: R/utils-database.R
Description: Connect to eyeris DuckDB database with comprehensive error handling.

eyeris:::connect_eyeris_database(bids_dir, db_path, verbose)

Returns: DuckDB connection object or NULL on failure

disconnect_eyeris_database()

File: R/utils-database.R
Description: Safely disconnect from eyeris DuckDB database.

eyeris:::disconnect_eyeris_database(con, verbose)

Returns: TRUE if successful, FALSE otherwise

Data Management

create_table_name()

File: R/utils-database.R
Description: Generate standardized table names for eyeris project database storage.

eyeris:::create_table_name(data_type, sub, ses, task, run, eye_suffix, epoch_label)

Returns: A standardized table name string

write_eyeris_data_to_db()

File: R/utils-database.R
Description: Write eyeris data to DuckDB database with error handling and validation.

eyeris:::write_eyeris_data_to_db(data, db_con, data_type, sub, ses, task, run, eye_suffix, epoch_label, verbose)

Returns: TRUE if successful, FALSE otherwise

write_csv_and_db()

File: R/utils-database.R
Description: Write data to both CSV file and database with fallback handling.

eyeris:::write_csv_and_db(data, csv_path, csv_enabled, db_con, data_type, sub, ses, task, run, eye_suffix, epoch_label, verbose)

Returns: TRUE if at least one write operation succeeded

Database Export & Management

create_temp_eyeris_database()

File: R/utils-database.R
Description: Create temporary database for parallel processing with unique naming.

eyeris:::create_temp_eyeris_database(base_db_path, parallel_id, verbose)

Returns: List with temporary database path and connection info

merge_temp_database()

File: R/utils-database.R
Description: Merge temporary database into main database with file locking.

eyeris:::merge_temp_database(temp_db_path, main_db_path, verbose)

Returns: TRUE if merge successful, FALSE otherwise

cleanup_temp_database()

File: R/utils-database.R
Description: Clean up temporary database files with comprehensive error handling.

eyeris:::cleanup_temp_database(temp_db_info, verbose)

Returns: TRUE if cleanup successful

Utility Functions

String Processing

clean_string()

File: R/utils-parsers.R
Description: Clean and sanitize strings for use in filenames or labels.

eyeris:::clean_string(str)

Returns: Cleaned string with special characters removed/replaced

sanitize_event_tag()

File: R/utils-epoch.R
Description: Sanitize event tags for safe use in filenames and labels.

eyeris:::sanitize_event_tag(string, prefix)

Returns: Sanitized string suitable for file system use

Data Parsing

get_block_numbers()

File: R/utils-parsers.R
Description: Extract block numbers from eyeris object or block names.

eyeris:::get_block_numbers(x)

Returns: Numeric vector of block numbers

BIDS Compliance

make_bids_fname()

File: R/pipeline-bidsify.R
Description: Generate BIDS-compatible filenames for data export.

eyeris:::make_bids_fname(sub_id, task_name, run_num, desc, ses_id, epoch_name, epoch_events, baseline_events, baseline_type, eye_suffix)

Returns: A BIDS-compatible filename string

run_bidsify()

File: R/pipeline-bidsify.R
Description: Internal function to run bidsify operation on a single eye’s data.

eyeris:::run_bidsify(eyeris, save_all, epochs_list, bids_dir, participant_id, session_num, task_name, run_num, save_raw, html_report, ...)

Returns: An eyeris object (typically for chaining)

Progress and Error Handling

Progress Bars

progress_bar()

File: R/utils-progress_bar.R
Description: Create a customizable progress bar for long-running operations.

eyeris:::progress_bar(total, msg, width, show_eta, clear)

Returns: A progress bar object from the progress package

counter_bar()

File: R/utils-progress_bar.R
Description: Create a simple counter-style progress bar.

eyeris:::counter_bar(total, msg, width)

tick()

File: R/utils-progress_bar.R
Description: Advance a progress bar by specified number of steps.

eyeris:::tick(pb, by)

Error Handling

error_handler()

File: R/utils-error_handler.R
Description: Generic error handler for eyeris functions with standardized error reporting.

eyeris:::error_handler(e, e_class)

Report Generation

R Markdown Reports

render_report()

File: R/utils-render_report.R
Description: Render an R Markdown report to HTML with proper error handling.

eyeris:::render_report(rmd_f)

make_report()

File: R/utils-render_report.R
Description: Generate comprehensive eyeris preprocessing report in R Markdown format.

eyeris:::make_report(eyeris, out, plots, eye_suffix, ...)

Returns: Path to the generated R Markdown file

Advanced Usage Notes

Function Chaining

Many internal functions are designed to work within the pipeline architecture:

# example of internal function chaining
eyeris_obj |>
  eyeris:::deblink_pupil(prev_op = "pupil_raw", extend = 100) |>
  eyeris:::detransient_pupil(prev_op = "pupil_raw_deblink", n = 16) |>
  eyeris:::interpolate_pupil(prev_op = "pupil_raw_deblink_detransient", verbose = TRUE)

Error Handling

All internal functions include comprehensive error handling:

# Internal functions validate inputs and provide informative errors
try({
  eyeris:::check_data(invalid_object, "function_name")
}, silent = TRUE)

Performance Considerations

  • Internal functions are optimized for performance within the pipeline
  • Use vectorized operations where possible
  • Progress bars are available for long-running operations
  • Database operations include connection pooling and error recovery

Development Guidelines

When using internal functions:

  1. Stability: Internal functions may change without notice
  2. Documentation: Always refer to this documentation for current signatures
  3. Testing: Test thoroughly when using internal functions directly
  4. Error Handling: Implement appropriate error handling in your code
  5. Performance: Consider performance implications of bypassing the main pipeline

Clone this wiki locally