Changes in version 3.1.0 (2026-06-05)                  

This minor release delivers several robustness and stability
improvements, fixing memory issues during HTML report rendering,
correcting epoch plot compression after downsampling, and improving
documentation accuracy.

🐛 Bugs fixed

  - FF (#275): Fixed HTML rendering failure on headless Linux systems
    with older pandoc versions (e.g., v2.7.3) caused by a missing
    sticker path. Previously, the blanket exclusion of ^inst/figures$ in
    .Rbuildignore caused system.file("figures", "sticker.png", package =
    "eyeris") to return "", producing <img src=''> markup that older
    pandoc versions cannot render. Replaced the blanket exclusion with
    targeted file-level exclusions for large demo assets (GIFs,
    character images, annotated example screenshots) while keeping only
    the essential sticker.png (21KB) in the installed package. Net
    package size increase is +21KB, well within CRAN's 5MB limit, by
    @shawntz in #286.

  - FF (#278): Fixed pandoc out-of-memory (exit 137) errors when
    rendering HTML reports with large epoch event data.
    format_call_stack() was calling deparse() on all parameters
    including large epoch event lists (thousands of rows), generating
    strings that consumed gigabytes of memory. Added
    should_omit_parameter() helper to detect and filter epoch-related
    parameters containing complex objects (lists/data.frames) before
    deparsing. Large parameters are now displayed as <omitted> in the
    call stack while scalar values (e.g., epoch_length = 100) are
    preserved. Added comprehensive test coverage for parameter
    filtering, case-insensitive matching, and scalar preservation, by
    @shawntz in #280.

  - FF (#291): Fixed downsampled epoch data being visually compressed in
    HTML plots. When downsampling was applied in the Glassbox pipeline,
    epoch plots showed 5-second windows compressed to ~0.5 seconds
    (a 10x compression). The root cause was that epoch_pupil() used the
    original sampling rate (info$sample.rate) instead of the decimated
    rate (decimated.sample.rate) when calculating epoch timebins,
    causing sample counts to be divided by the wrong Hz value. Updated
    epoch_pupil() to check for decimated.sample.rate first before
    falling back to the original rate. X-axis labels and CSV output were
    already correct; this fix applies the same logic to the plot
    rendering, by @shawntz and @alicexue in #292.

🔧 Minor improvements and fixes

  - FF (#287): Fixed misleading load_asc() usage pattern in the database
    guide documentation, where examples incorrectly instructed users to
    call load_asc() and pipe the result into glassbox(). This caused
    errors because eyeris expects a file path string to be passed
    directly into the pipeline; load_asc() is handled internally.
    Updated examples to show the correct usage pattern and added a
    runtime error in glassbox() that detects when a user passes an
    eyeris object instead of a file path, with a helpful message
    explaining the correct approach, by @shawntz and @alicexue in #288.

📚 Documentation

  - DOC: Added a system requirements section to the README with
    platform-specific guidance for installing runtime dependencies, by
    @shawntz in #282.

                 Changes in version 3.0.1 (2025-10-07)                  

This patch release improves dependency management for Arrow and DuckDB
to prevent installation issues on macOS and other platforms.

🔧 Dependency management improvements

  - ENH: Moved arrow from Imports to Suggests to prevent hanging
    installation issues on macOS. The arrow package requires system
    dependencies (pkg-config, cmake, apache-arrow via Homebrew on macOS)
    that could cause installation to hang indefinitely when building
    from source. eyeris now gracefully falls back to DuckDB for parquet
    operations when arrow is not available, with informative
    installation instructions provided via check_arrow() helper
    function, by @shawntz in #273.

  - ENH: Added comprehensive installation guidance for Arrow and DuckDB
    dependencies. New check_arrow() helper function provides
    platform-specific installation instructions (macOS, Linux, Windows)
    with detailed steps for installing required system dependencies.
    Startup messages now inform users about missing optional
    dependencies and point to installation documentation, by @shawntz in
    #273.

📚 Documentation

  - DOC: Updated README with detailed instructions for installing Arrow
    and DuckDB dependencies across different platforms, including
    Homebrew setup for macOS, system package installation for Linux
    distributions, and notes about when these packages are required, by
    @shawntz in #273.

                 Changes in version 3.0.0 (2025-09-17)                  

This major release delivers multiple performance enhancements and
feature improvements, reducing processing time and improving overall
efficiency across the pipeline.

🚨 Breaking changes & deprecations

  - DEPRECATED: merge_runs and merge_epochs parameters in bidsify():
    Both merge_runs and merge_epochs parameters are now deprecated. All
    runs and epochs are now saved as separate files following proper
    BIDS conventions, which is the recommended approach for neuroimaging
    data standards. Users relying on these features should update their
    analysis workflows to handle separate run and epoch files.
    Deprecation warnings will be shown when these parameters are used.

🚀 New features

  - NF: Zip-based epoch gallery system: Replaced individual epoch image
    files with zip-based storage and loading system. The make_gallery()
    function now creates epoch images in zip files instead of individual
    PNG files, and uses zip.js to dynamically load images in the HTML
    gallery. This reduces file count, improves organization, and
    provides more efficient loading while maintaining full backward
    compatibility with existing individual image files. This is
    particularly beneficial for high-throughput compute environments
    with limited inode quotas and simplifies file transfers to cloud
    storage providers like GitHub LFS, by @shawntz in #254.

  - NF: Automated source figure cleanup: Added post-render cleanup
    functionality that automatically zips all png and jpg files in each
    source/figures/run-xx/ directory after the main HTML report is
    generated before deleting the individual image files, further
    reducing file count burden while preserving all figure data in
    compressed format, creating only one zip file per run per subject
    instead of hundreds of individual image files, by @shawntz in #255.

  - NF - DuckDB database integration: Added optional DuckDB database
    functionality to bidsify() as an alternative to CSV files for
    large-scale analyses. When db_enabled = TRUE, all eyeris data
    (timeseries, epochs, events, blinks, confounds) are written to a
    centralized database for efficient querying and analysis. Features
    include seamless out-of-the-box configuration, user-friendly
    database functions (eyeris_db_collect(), eyeris_db_connect(),
    eyeris_db_read(), eyeris_db_list_tables()), and dplyr-style data
    access. CSV file generation can be optionally disabled with
    csv_enabled = FALSE for cloud compute environments, by @shawntz in
    #256.

  - NF: Added parallel processing support for DuckDB database operations
    to prevent concurrency issues during batch processing. Implemented
    temporary database creation with automatic merging and cleanup
    mechanisms. Added environment variable detection for common HPC
    schedulers (SLURM, PBS, SGE, LSF) and manual parallel_processing
    parameter override. Includes comprehensive file locking, process/job
    ID logging, and full test coverage, by @shawntz in #262.

This enhancement enables seamless parallel compute and batch processing
when using db_enabled = TRUE. Each parallel job now writes to a unique
temporary database, preventing the crashes that occurred when multiple
processes attempted concurrent writes to the same DuckDB file.

Key features:

  - Automatic Detection: Detects HPC environments (SLURM_JOB_ID,
    PBS_JOBID, etc.)
  - Temporary Databases: Each job uses PID + timestamp for unique temp
    database names
  - Safe Merging: File-based locking prevents concurrent access during
    merge operations
  - Rich Logging: Job ID and process ID included in all parallel
    processing messages
  - Zero Breaking Changes: All existing functionality preserved

Usage examples:

# Automatic detection in HPC environments
data |> bidsify(db_enabled = TRUE)

# Manual enable for testing/development
data |> bidsify(db_enabled = TRUE, parallel_processing = TRUE)

# Environment variable override
Sys.setenv(PARALLEL_PROCESSING = "1")
data |> bidsify(db_enabled = TRUE)

  - NF: Large-scale database export functionality. Added
    eyeris_db_to_chunked_files() and process_chunked_query() functions
    to handle really large eyerisdb databases by processing data in
    configurable chunks (default 1M rows) with automatic file size
    limits (default 500MB) and numbered file splitting (_01-of-N
    pattern). Supports both CSV and Parquet output formats with
    memory-efficient streaming processing, by @shawntz in #266.

  - NF: Robust parquet export/read for eyerisdb mixed schemas.
    eyeris_db_to_parquet() and read_eyeris_parquet() now combine
    tables/files using schema-aligned binding (by column name; fill
    missing) via data.table::rbindlist(use.names = TRUE, fill = TRUE).
    Fixes "numbers of columns of arguments do not match" when different
    epochs_* tables have slightly different columns, by @shawntz in
    #266.
    
    Key Features:
    
      - Chunked Processing: Handles databases of any size without memory
        issues using configurable chunk sizes
      - Automatic File Splitting: Creates numbered files when size
        limits exceeded (e.g., data_01-of-03.csv)
      - Smart Schema Grouping: Dynamically groups tables by column
        structure to prevent SQL UNION errors
      - Database Safety: Comprehensive temp table cleanup and
        contamination prevention
      - Comprehensive Documentation: Detailed vignette with real-world
        examples and troubleshooting

  - NF: Database sharing and distribution functionality. Added
    eyeris_db_split_for_sharing() and
    eyeris_db_reconstruct_from_chunks() functions to facilitate sharing
    of large eyeris databases via platforms with file size limits
    (GitHub, OSF, data repositories). Supports chunking strategies by
    data type, count, or size limits with epoch label grouping for
    efficient organization. Includes comprehensive metadata for reliable
    database reconstruction, by @shawntz in #269.

🔧 Major code improvements

  - Simplified bidsify() function: Significantly refactored and
    streamlined the pipeline-bidsify.R file to improve maintainability
    and reduce code complexity:
    
      - Removed merge_runs and merge_epochs logic: Eliminated ~250+
        lines of complex conditional logic for merging runs and epochs,
        simplifying the codebase while ensuring BIDS compliance
      - Consolidated baseline data access: Updated helper functions to
        prioritize baseline information stored within
        epoch_xx$block_1$baseline structure, providing consistent data
        access patterns while maintaining backward compatibility with
        legacy storage locations
      - Simplified epoch summary generation: Replaced 257 lines of
        repetitive sapply() calls with a clean 77-line implementation
        using unlist() approach for generating *_desc-epoch_summary.csv
        files, improving code readability and maintainability
      - Added helper functions: Created centralized functions
        (get_epoch_info(), get_baseline_events(), get_baseline_type(),
        has_baseline()) to eliminate code duplication and provide
        consistent data access across the pipeline

  - ENH: Added post-render cleanup of figures directories in
    pipeline-bidsify.R. Enhanced zip_and_cleanup_source_figures to
    remove existing zip files before reprocessing, move new zip files to
    the parent figures directory, and delete run directories after
    successful zipping. This streamlines figures management and prevents
    leftover files from previous runs, by @shawntz in #261.
    
    Further cleans up number of derived files in eyeris BIDS directories
    (which is especially useful for cloud compute deployments).
    
    The new behavior will be:
    
    1.  Create zip files in the figures/ directory (i.e., one level up
        from the run directories)
    2.  Remove existing zip files when reprocessing
    3.  Remove the entire run-XX/ directories after successful zip
        creation
    
    As such, the final file structure will be:
    
      sub-01/
      └── ses-enc/
          ├── sub-01.html
          └── source/
              ├── figures/
              │   ├── run-01.zip  # now contains all images from run-01/
              │   ├── run-02.zip  # now contains all images from run-02/
              │   └── run-03.zip  # now contains all images from run-03/
              └── logs/
                  ├── run-01_metadata.json
                  ├── run-02_metadata.json
                  └── run-03_metadata.json

  - FF: Handle non-finite values in plotting xlim ranges to prevent
    plot.window() crashes. Added finite=TRUE parameter to range() calls
    and fallback logic when no finite values exist in timebin or x_seq
    data. Resolves "need finite 'xlim' values" error during epoch
    visualization, by @shawntz in #263.

  - FF: Standardize column structure before rbind in epoch summaries to
    prevent column mismatch errors. Different epochs can have varying
    metadata structures (9 vs 10 fields), causing rbind() to fail. Added
    logic to collect all unique column names, standardize structure with
    NA values for missing columns, and ensure consistent column ordering
    before combining data frames, by @shawntz in #264.

  - ENH: Improved database summary performance. eyeris_db_summary() now
    extracts subject/session/task information directly from table names
    instead of sampling database contents, providing complete coverage
    of all subjects and much faster execution, by @shawntz in #266.

  - ENH: Enhanced temp table safety. All database export functions now
    automatically detect, warn about, and exclude temporary tables from
    processing. Added safe temporary table operations with guaranteed
    cleanup even on process crashes, by @shawntz in #266.

  - ENH: Optimized database export performance and reliability.
    eyeris_db_to_chunked_files() now uses a hybrid approach:
    database-level export via DuckDB's COPY command for large file size
    limits (≥500MB) for maximum performance, and chunked processing for
    smaller limits (<500MB) to ensure proper file size splitting for
    git-lfs workflows. Additionally, parquet file handling has been
    improved to eliminate unreliable appending that caused _chunk_
    files, now using a cleaner numbered file approach with 80% size
    thresholds to prevent append failures, by @shawntz in #268.

  - ENH: Enhanced chunked database export with epoch label grouping.
    eyeris_db_to_chunked_files() now supports group_by_epoch_label
    parameter (default: TRUE) that processes epoch-related data types
    separately by epoch label, reducing memory footprint and creating
    label-specific output files. Added helper functions for epoch label
    extraction and improved table grouping logic for better organization
    of exported data, by @shawntz in #270.

🔧 Minor improvements and fixes

  - BF (#250): Updated functions in pipeline-confounds.R and
    pipeline-epoch.R to handle cases where 'start_matched_event' is used
    instead of 'matched_event' in epoched data. Resolved an issue with
    inconsistent variable naming introduced in #a8df0c0, and fixed time
    and duration calculations in epoch_start_end_msg() to use correct
    units and sample counts, by @shawntz in #251.

  - RF: Added Bootstrap and Lightbox assets (CSS, JS, fonts, images) to
    inst/www and updated .Rbuildignore to exclude them from builds.
    Refactored make_gallery to use local copies of these dependencies
    with CDN fallbacks, improving offline support and reliability of
    gallery reports, by @shawntz in #252.

  - DOC: Added a comprehensive 'Internal API Reference' vignette
    documenting all internal functions for advanced users and developers
    and updated the README to link to the new vignette/included it in
    the pkgdown docs site configuration, by @shawntz in #257.

  - RF: Updated documentation and comments across multiple files to
    improve clarity and align terminology throughout the codebase,
    especially in function descriptions, parameter names, and return
    value documentation, by @shawntz in #257.

  - FF: Updated the log_message() function to use tryCatch when applying
    glue interpolation, ensuring that errors (e.g., from malformed
    braces or embedded JSON) do not interrupt logging; now, the original
    message is used if interpolation fails, by @shawntz in #258.

  - CHORE: Add a GitHub Actions workflow to auto-render vignettes and
    publish them to the eyeris GitHub repo wiki, by @shawntz in #259.

  - RF - post-render cleanup to remove figures directory: The
    cleanup_source_figures_post_render() function now removes the entire
    source/figures directory after report generation, as images are
    embedded in the HTML. Documentation and comments updated to reflect
    this change, and unused parameters are noted for compatibility, by
    @shawntz in #261.

  - RF - increase zip file embed size limit to 1GB: Raised the maximum
    allowed zip file size for data URL embedding from 10MB to 1GB in
    print_lightbox_img_html(). Updated warning message to reflect the
    new limit, by @shawntz in #261.

  - RF - update report title in make_report function: Changed the report
    title from 'preprocessing summary report' to 'preprocessing report'
    for consistency and clarity, by @shawntz in #261.

  - CHORE - update logo image URL: Changed the logo image source in
    README files to use a GitHub raw URL for better compatibility, by
    @shawntz in #261.

  - FF: Detect grouping column for epoch diagnostic plots. For start/end
    epochs (e.g., "PROBE_S {STIM}" to "PROBE_E {STIM}"), the epoched
    data contains start_matched_event instead of matched_event. Added
    automatic detection logic with priority: requested column →
    start_matched_event → end_matched_event. Includes informative
    logging and graceful fallback when no suitable column found, by
    @shawntz in #265.

  - FF: Improved handling of mismatched start/end events in epoch().
    When using start/end event pairs (e.g., c("PROBE_S {STIM}", "PROBE_E
    {STIM}")), the function now automatically matches events by
    extracting identifiers from event messages instead of failing with
    "Start and end timestamps must have the same number of rows".
    Unmatched events are filtered out and the process continues with
    matched pairs only, with informative logging about the filtering
    process, by @shawntz in #267.

  - DOC: Updated package documentation to include newly exported
    database functions in _pkgdown.yml, core function reference table in
    README.Rmd, and internal API vignette. Enhanced documentation
    coverage for database export and management functionality, by
    @shawntz in #270.

                 Changes in version 2.1.1 (2025-07-26)                  

This release patches a few bugs that emerged as a result of the v2.1.0
minor release.

🔧 Minor improvements and fixes

  - BF (#237): Ensure full raw timeseries .csv file is written by
    bidsify() for single-run (monocular) data, including cases with or
    without epoching and with run number override. Previously, the file
    was only written for multi-run data by @shawntz in #240.

  - FF (#236): Certain sprintf-formatted log messages (e.g., those with
    '%s') for blinks/events writing in pipeline-bidsify.R now parse and
    display correctly in the logger by using the internal alert()
    wrapper by @shawntz in #241.

  - FF (#238): Only log [INFO] Filtered epochs: ... when data is epoched
    by @shawntz in #242.

  - CHORE (#239): Remove duplicate logging events for "Created gaze
    heatmap" in bidsify() pipeline. The log message now appears only
    once per run and uses the [OKAY] log level for both run-level and
    epoch-level heatmap creation, improving clarity and consistency in
    logs, by @shawntz in #243.

  - ENH DOC: Add GitHub Actions workflow for automated spellchecking of
    documentation and code using r-spellcheck-action. The workflow runs
    on pushes and pull requests to dev and release/** branches by
    @shawntz in #244

  - CHORE: Adjust pkgdown CI deployment trigger conditions for PRs to be
    more specific about which branches should trigger the workflow by
    @shawntz in #245.

  - CHORE: Update the GitHub Actions workflow configuration to fix CI
    triggers for the R CMD build/check action. The changes modify the
    workflow name and expand branch pattern matching to include release
    branches with additional path segments, by @shawntz in #246.

  - CHORE: Standardize the GitHub Actions workflow configurations for
    air formatting operations. The changes update workflow names and
    branch targeting patterns to ensure consistent formatting checks and
    suggestions across the development workflow, by @shawntz in #247.

  - CHORE: Resolve spelling errors throughout the package by correcting
    typos in documentation, comments, and code, while also creating a
    WORDLIST file for the spellchecker to recognize domain-specific
    terms by @shawntz in #248.

                 Changes in version 2.1.0 (2025-07-22)                  

This minor release introduces significant enhancements, new features,
and robust improvements focusing on binocular data support, standardized
logging, and improved reporting and development workflows, substantially
elevating eyeris' functionality, robustness, and user experience.

✨ New features & enhancements

  - Comprehensive Binocular Recording Support: eyeris now provides full
    binocular recording support, resolving a critical data loading bug
    previously encountered with binocular EyeLink recording data files
    (#216 reported by @anomalosepia). This enhancement includes nesting
    eyeris class lists with left and right parent lists to explicitly
    separate left eye (L) and right eye (R) data. All downstream
    operations are now designed to treat L and/or R as separate
    entities, which ensures no cross-contamination between data from the
    two eyes during processing. Additionally, the bidsify() function now
    appends _eye-L and/or _eye-R to all derivatives and output HTML
    reports for binocular data for clear naming conventions. Pipeline
    functions such as deblink(), interpolate(), lpfilt(), detransient(),
    zscore(), epoch(), downsample(), detrend(), and bin() have been
    updated to handle binocular objects. A new
    plot_binocular_correlation() function has also been added, and
    vignettes were updated to explain binocular data structures and
    usage with glassbox(); by @shawntz in #228.

  - Standardized Logging and Error Handling (using cli package): The
    eyeris package has undergone comprehensive refactoring to
    standardize and enhance the clarity of logging, warning, and error
    messages by transitioning fully to the cli R package. This replaces
    base R functions like message(), stop(), and warning() with
    cli::cli_alert_*, cli::cli_abort(), and cli::cli_alert_warning()
    respectively. Consistent log level tags such as [INFO], [OKAY],
    [WARN], and [EXIT] are now implemented within cli alert messages for
    clearer categorization and improved message clarity and uniformity
    across various pipelines and functions. These changes have been
    applied across key components including run_bidsify,
    detransient_pupil, pipeline-epoch.R, interpolate_pupil,
    make_epoch_label, check_and_create_dir, compute_baseline, load_asc,
    process_eyeris_data, pipeline-glassbox.R, and plot.eyeris.R; by
    @shawntz in #229.

  - Enhanced HTML Reports for Multi-Run Data: HTML reports now
    accurately reflect all detected runs, including their metadata and
    call stack. This addresses a previous issue where only the latest
    run was shown, by modifying make_report() to detect all run-xx
    folders in source/figures/ and updating
    save_progressive_summary_plots() to use the folder structure rather
    than eyeris$timeseries names. The metadata section now shows one
    line per run for the .asc file source and a formatted call stack for
    each run; by @shawntz in #224.

  - Integration of Air R Formatter: The project's R code formatting has
    transitioned to Air, an R formatter and language server written in
    Rust, replacing the lintr-based formatting system. This change
    involved deleting the .github/workflows/linter.yml file, introducing
    a new .air.toml configuration file, and adding two new GitHub
    workflows for format checking and suggestions. Furthermore,
    comprehensive code reformatting has been applied to all R source
    files to match Air's standards, ensuring better line breaks,
    consistent spacing, and improved argument alignment throughout the
    entire codebase; by @shawntz in #234.

🔧 Minor improvements and fixes

  - Improved HTML Report Navigation: The table of contents depth in HTML
    reports has been increased from 3 to 6 levels for better navigation
    by @shawntz in #229.

  - Refined Makefile Targets: New Makefile targets have been added for
    CRAN presubmission checks, CRAN submission, GitHub releases, and
    code formatting with Air. This also includes expanded dependency
    installation and improved output formatting and redirection for
    cleaner logs by @shawntz in #230.

  - Event Placeholder Fix: The event placeholder in example code and
    documentation has been updated from {type} to {startstop} to resolve
    a name conflict with an existing type column name in the derived
    .csv data files by @shawntz in #232.

📚 Documentation & Development Workflow Updates

  - Revamped README: The README has been significantly expanded with
    detailed feature highlights, a comprehensive function reference
    table, and new sections outlining the BIDS-like file structure for
    both monocular and binocular data. It also includes quick links to
    eyeris tutorials (R CRAN package vignettes), improved example
    output, and updated section headings for clarity and visual appeal;
    by @shawntz in #231.

  - Enhanced Pull Request Template: The GitHub pull request template has
    been updated to provide a more structured and detailed format for
    contributors. This update includes structured sections for problem
    description, key changes, and acknowledgments, providing detailed
    examples and expanding the breaking changes section into a more
    comprehensive checklist; by @shawntz in #227.

  - Makefile Maintenance: Comments and section headers in the Makefile
    have been updated and clarified for better maintainability by
    @shawntz in #230.

                 Changes in version 2.0.0 (2025-07-03)                  

This is the largest update yet for eyeris, introducing a wealth of new
features and addressing numerous small issues to significantly enhance
functionality, robustness, and user experience (#215).

✨ New features

Enhanced reporting and visualization:

  - Progressive preprocessing summary plots can now be generated and
    saved, visualizing the effects of each preprocessing step on pupil
    data and updating report structures to include these visualizations.
    The plot.eyeris() function now includes an add_progressive_summary
    parameter to optionally generate these plots by @shawntz in #212.

  - Gaze heatmap generation is added for both runs and epoch groups
    within bidsify(), enabling visualizations of eye coordinate
    distributions, data quality, and participant attention when eye
    tracking and screen dimension data are available. A new
    plot_gaze_heatmap() function is introduced for this purpose by
    @gustxsr and @shawntz in #213.

  - Interactive HTML reports now include a floating table of contents,
    enhancing navigation for longer reports by @shawntz in #182.

  - The html_report parameter in bidsify() now defaults to TRUE by
    @shawntz in #212.

Core data processing functions:

  - New bin() and downsample() functions are introduced for pupil time
    series data processing, including anti-aliasing filtering for
    downsampling and averaging for binning. Both functions are
    integrated into the eyeris::glassbox() pipeline by @shawntz and
    @mh105 in #204.

  - Unique identifiers (text_unique) are now added to event messages in
    eyeris::load_asc() to prevent duplicate event merges, and the
    merge_events_with_timeseries() function is updated to utilize these
    for correct event matching and merging by @shawntz in #181.

  - Confounds calculation and export are integrated into the processing
    pipelines, with eyeris::summarize_confounds() now included in
    eyeris::glassbox() and eyeris::epoch() pipelines by @shawntz in
    #182.

Pipeline robustness and reproducibility:

  - Tracking of pipeline step provenance is improved, adding the
    original function call and parameters for each step via a new
    call_info argument. This metadata is passed to eyeris functions to
    enhance reproducibility and debugging by @shawntz in #209.

  - The eyelogger() utility documentation has been updated with a new
    section in the README, detailing its purpose, usage examples,
    parameters, and generated log files for improved reproducibility and
    debugging by @shawntz in #214.

🔧 Minor improvements and fixes

Robustness and error handling:

  - Enhanced plotting robustness includes tryCatch blocks to handle
    errors and display informative messages in plots, and time series
    plotting now iterates over all intermediate steps to ensure plots
    are generated even with missing or incomplete data by @shawntz in
    #181, #183.

  - Handling of missing valid samples in random epoch plotting has been
    improved in plot.eyeris(), adding warning messages and placeholder
    plots when no valid samples are found by @shawntz in #181, #183.

  - Stricter validation checks are added for the prev_op argument in the
    eyeris::zscore_pupil() internal function to catch missing,
    non-existent, or corrupted column names early, improving error
    handling by @shawntz in #207.

  - Validation for pupil data in the eyeris::lpfilt_pupil() internal
    function ensures data is numeric, non-empty, and contains only
    finite values before filtering, preventing errors related to invalid
    matrix extents by @shawntz in #210.

  - Stricter checks for corrupted or empty latest pointers and output
    column names are added in eyeris::pipeline_handler(), improving
    error handling and transitioning operation calls to use do.call for
    flexible argument passing by @shawntz in #211.

  - The eyeris::load_asc() function now correctly sets the latest
    pointer as a named list for multi-block structures and as a single
    value for single block data, enhancing multi-block support by
    @shawntz in #211.

  - Fixes an edge case where mad_val is NA in the
    eyeris::detransient_pupil() internal function (occurring when all
    pupil data is NA), ensuring the original pupil data is returned
    unchanged and preventing comparison to zero when mad_val is NA by
    @shawntz in #193.

  - Baseline handling in eyeris::epoch() is simplified by deprecating
    calc_baseline and apply_baseline in favor of a single baseline
    parameter, also resolving bugs related to baseline computation and
    event mismatches by @shawntz in #177.

Pipeline and data logic:

  - The eyeris::glassbox() function has been refactored to process each
    block in the time series individually (except load_asc), improving
    modularity and ensuring correct error handling of multi-block data
    by @shawntz in #189.

  - The calculation of mean_gaze_distance_from_center_px now correctly
    uses the screen center coordinates (cx, cy) instead of defaulting to
    the origin, ensuring the metric reflects distance from the actual
    screen center by @shawntz in #199.

  - The eyeris::bidsify() function is refactored to handle cases where
    no epochs are present, preventing errors and unnecessary processing
    for users who want summary reports of the entire pupil time series
    without prior epoching by @shawntz in #201.

  - The eyeris::bidsify() function now properly allows manual
    specification of the run_num for single-block data, while still
    auto-numbering multi-block files for improved naming consistency by
    @shawntz in #203.

  - The recalculation of epoched confounding variables is now performed
    when new epochs are created by @shawntz in #182.

Documentation and internal clean-up:

  - Extensive documentation cleanup has been performed, including fixing
    various spelling errors/typos in multiple function documentations by
    @shawntz in #179, #214.

  - The pdf_report parameter is eyeris::bidsify() has been deprecated in
    favor of html_report = TRUE, with associated removal of PDF
    rendering logic from the render_report() internal function by
    @shawntz in #197.

  - Updates to _pkgdown.yml, README, NAMESPACE, and R/zzz.R to support
    new features and functionality, including exposing the
    eyeris_color_palette() and other global variables by @shawntz in
    #214.

  - The structure of the latest field in mock data for unit tests was
    fixed to be a named list to ensure tests do not fail due to
    incorrectly specified data structures by @shawntz in #208.

  - Added MASS, viridis, and fields package dependencies to Imports to
    support new gaze heatmaps functionality by @shawntz in #213.

                 Changes in version 1.2.1 (2025-06-13)                  

✨ New features

  - eyelogger(): a new utility function to automatically capture and
    record R console output, errors, and the evaluated eyeris command
    into timestamped log files (.out, .err, and .cmd) for improved
    reproducibility, record keeping, and debugging by @shawntz in #171
    
    eyelogger() usage example
    
    Logging your eyeris commands with eyelogger() is as simple as
    wrapping your command like this:
    
    eyelogger({
      glassbox(eyelink_asc_demo_dataset(), interactive_preview = FALSE)
    }, log_dir = file.path("~/Documents", "eyeris_logs"))

🐛 Bugs fixed

  - Fixed edge case related to non-finite samples in bidsify epoch
    plotting function by @gustxsr in #166
  - Fixed multi-block epoch bug by extracting data from blocks using
    their names rather than their indices by @hyang336 in #168
  - Fixed plotting bug (#165) by @shawntz in #169

🔧 Other minor improvements and fixes

  - ENH: make plot color scheme more accessible/easier to read by
    @shawntz in #169
  - FF: missing x-axis labels on histograms in rendered reports by
    @shawntz in #169
  - NF: add detrend fitted values diagnostic plot to rendered reports by
    @shawntz in #169

                 Changes in version 1.2.0 (2025-06-07)                  

✨ New features

  - NF: Add vertical lines to plots to indicate where missing data (such
    as blinks and/or removed artifacts) are located in the time series
  - ENH: Plotting now takes time ranges in seconds directly and does the
    conversion to row index using tracker Hz on the backend, making
    plotting in eyeris more intuitive. To demonstrate:

plot(eyeris_preproc,
  steps = c(1, 5),
  preview_window = c(0, max(eyeris_preproc$timeseries$block_1$time_secs))
)

🐛 Bug fixes

  - BF: NA slot offset in diagnostic plotting (#161)
  - BF: normalize physical machine time bins and convert to seconds /
    start at 0 seconds (#162)
  - BF: unit displayed on the x-axis doesn't match the unit listed on
    the x-axis text label in plots (#162)
  - BF: minor issue where a manually specified block number in
    load_asc() wasn't being translated to the column block in the
    resulting list of time series data frames
  - BF: minor issue where setting block = NULL in load_asc() didn't
    actually omit the block column values from the resulting data frames
    within the returned eyeris list object

🔧 Minor improvements and fixes

  - RF: update package title to match that of the published bioRxiv
    preprint
  - RF: Deprecated the num_previews parameter in plot().
      - Please use preview_n instead.
  - DOC: manually update citation file to include all authors + bioRxiv
    preprint DOI (#152)
  - DOC: incorrect URIs in eyeris documentation for load_asc() function
    (#160)
  - DOC: standardize default values for deblink() standalone [previously
    40ms] vs. in glassbox() [now all 50ms] (#163)
  - DOC: updates to pkgdown documentation website:
      - Matching accent color theme with the eyeris hex logo
      - New nav bar items (buttons/links to access the bioRxiv preprint
        and socials)
      - Update funders and contributors list
      - Add funders disclaimer statement to the footer

                 Changes in version 1.1.0 (2025-04-24)                  

✨ New features

  - NF: Simplify glassbox() caller with redesigned parameters that
    enhance continuity across all pipeline steps (#148)

📚 Documentation

  - DOC: Improved function documentation across the package and added
    more usage notes for clarity.
  - DOC: Updated styling of documentation website.

🔧 Minor improvements and fixes

  - ENH: Make histograms disabled by default when plotting an eyeris
    object (#156).
  - RF: Deprecated the confirm parameter in glassbox().
      - Please use interactive_preview instead.
  - RF: Deprecated the num_previews parameter in glassbox().
      - Please use preview_n instead.
  - BF: Random seed assignment was not behaving as expected within the
    glassbox() pipeline.
  - RF: Modify paths to documentation assets to fix broken links at
    build.

                        Changes in version 1.0.1                        

This non-CRAN release patches a small handful of documentation-related
chores that have no direct impact on the functionality of eyeris for the
end user. The minor improvements and fixes contained within this release
will soon be bundled with a more substantial feature upgrade when
submitted to CRAN to reduce burden on the CRAN reviewers at this time.
Stay tuned!

🔧 Minor improvements and fixes (#159)

  - CHORE: fix duplicate LICENSE file issue in release/** branches
    (#145)
  - CHORE: update funders list on DESCRIPTION (#149)
  - CHORE: add DOI badge to README (#150)
  - CHORE: fix citation years in DESCRIPTION (i.e., put them in
    parentheses, per request of CRAN reviewer) (#151)
  - DOC: update README to include CRAN install code + option for @latest
    dev branch via download with devtools/GitHub (#153)
  - DOC: fix version titles + urls on changelog webpage (#154)
  - CHORE: change pkgdown docs website deployment rules so that public
    webpage only updates on pushes to official release branches, and not
    the dev branch (#155)
  - DOC: add CONTRIBUTING.md guidelines file for GitHub (#157)
  - DOC: fix /man/figures/... image ref issues which is leading to
    broken links on the R CRAN read-only GitHub mirror repo (#158)

                 Changes in version 1.0.0 (2025-03-31)                  

🎉 First CRAN release! (#144)

This version marks the official launch of the eyeris package on CRAN.

✨ New features (#125)

  - Added example vignettes to demonstrate core functionality:
      - Preprocessing pipelines with glassbox()
      - Event-based epoching with epoch()
      - BIDS-style export with bidsify()
      - Custom pipeline extensions using pipeline_handler()

📚 Documentation (#125)

  - Improved function documentation across the package
  - Added citation guidance and reproducibility tips

Thanks for checking out eyeris! 🧠

Pre-CRAN dev GitHub releases:

                     Changes in version 0.1.1.9000                      

🔧 Minor improvements and fixes

  - FF (#115): add more aggressive handling of edge cases in
    eyeris::detransient() (#121)
      - Specifically, situations where pupil data appear to have already
        undergone some type of online filtering directly from the
        EyeLink Host PC machine.
      - There is now detailed instructions on what to do if this
        exception is raised.
      - Furthermore, a new mad_thresh override parameter has been added
        to eyeris::detransient() for advanced users to override the
        mad_thresh computed property. Note: this new mad_thresh
        parameter defaults to NULL (and should pretty much always stay
        as such).
  - FF (#122): fixed issue with incompatible unicode character in plot
    titles (#123)

                     Changes in version 0.1.0.9000                      

💥 Breaking changes

  - NF (#10): add support for .asc files containing multiple recording
    segments within the same file (#120)
      - There is a new block argument added to the load_asc() function
      - The default setting is "auto", which aims to automatically
        handle multiple recording segments within the same .asc file. We
        recommend using this default as this is likely the safer choice
        rather than assuming a single-block recording. Furthermore, add
        downstream functions are intentionally designed to support any N
        number of blocks; using the "auto" setting automatically enables
        this support for .asc files containing single recording blocks
        by labeling the single recording session as block_1
      - You can also manually specify a different block value (numeric)
        instead of "auto", which can be helpful for multi-block
        experiments where each block/run was recorded to a separate .asc
        file. This is especially important to consider when running the
        downstream epoch() and bidsify() functions so that derived files
        and summary reports are properly labeled with the correction
        block/run number
      - Currently, there is also a NULL option; however, this is likely
        going to just be a part of beta testing and will probably be
        removed in a future version given the foregoing 2 options should
        cover most (if not all) use cases

✨ New features

  - NF: robust HTML and PDF output summary sidecar reports within
    bidsify() (#120)
      - Here, reports are well-organized both by block/run and any
        specific event message epochs that have been processed using the
        epoch() function
      - For epoched data, we now provide a useful interactive utility
        within the epoch-specific HTML reports: you can now use your
        mouse and/or keyboard to swiftly navigate through an interactive
        gallery of pupil plot segments from every single trial from any
        given subject, right out-of-the-box! We hope this alleviates
        some of the complexities/roadblocks users might face when
        needing to perform manual inspections of their data for quality
        assurance and/or diagnostic purposes.

🔧 Minor improvements and fixes

  - FF (#118): resolved a minor bug in the EyeLink EDF header model and
    version fields for data collected on newer EyeLink hardware/software
    (#120)
  - ENH: event epoching is now both more robust and super fast (#120)
      - We have implemented more efficient data structures to swiftly
        handle large sets of pupil samples in rapid time
      - We have also added in better visual feedback within the console
        regarding epoching progress
      - Similarly, these added benefits coincide nicely with the new
        multi-block support (#10)
  - General bug fixes and enhancements to codebase and front-end UX
    (#120)

                     Changes in version 0.0.0.9000                      

  - Initial beta release