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).
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.
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.
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.
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.
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.
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.
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
exampleLogging 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"))bidsify epoch plotting function by @gustxsr in #166eyeris more intuitive. To demonstrate:plot(eyeris_preproc,
steps = c(1, 5),
preview_window = c(0, max(eyeris_preproc$timeseries$block_1$time_secs))
)NA slot offset in diagnostic plotting (#161)load_asc() wasn’t being translated to the column
block in the resulting list of time series data framesblock = NULL in
load_asc() didn’t actually omit the block column values
from the resulting data frames within the returned eyeris
list objectnum_previews parameter in
plot().
preview_n instead.eyeris documentation for
load_asc() function (#160)deblink()
standalone [previously 40ms] vs. in glassbox()
[now all 50ms] (#163)pkgdown documentation website:
eyeris hex
logo
glassbox() caller with redesigned
parameters that enhance continuity across all pipeline steps (#148)eyeris object (#156).confirm parameter in
glassbox().
interactive_preview instead.num_previews parameter in
glassbox().
preview_n instead.glassbox() pipeline.
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!
LICENSE file issue in
release/** branches (#145)DESCRIPTION (#149)README (#150)DESCRIPTION (i.e., put
them in parentheses, per request of CRAN reviewer)
(#151)README to include CRAN install
code + option for @latest dev branch via download
with devtools/GitHub (#153)dev branch (#155)CONTRIBUTING.md guidelines file for GitHub
(#157)/man/figures/... image ref issues which is
leading to broken links on the R CRAN read-only GitHub mirror repo (#158)This version marks the official launch of the eyeris
package on CRAN.
glassbox()epoch()bidsify()pipeline_handler()Thanks for checking out eyeris! 🧠👁️
Pre-CRAN dev GitHub releases:
eyeris::detransient() (#121)
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)..asc files containing
multiple recording segments within the same file (#120)
block argument added to the
load_asc() function.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.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 numberNULL 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 casesbidsify() (#120)
epoch() functionmodel and version fields for data collected on
newer EyeLink hardware/software (#120)