forked from shawntz/eyeris
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
564 lines (434 loc) Β· 29.9 KB
/
Copy pathREADME.Rmd
File metadata and controls
564 lines (434 loc) Β· 29.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
---
output: github_document
---
<!-- README.md is generated from README.Rmd-->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# `eyeris`: Flexible, Extensible, & Reproducible Pupillometry Preprocessing <a href="https://shawnschwartz.com/eyeris/" title="eyeris website"><img src="https://raw.githubusercontent.com/shawntz/eyeris/refs/heads/dev/man/figures/logo.png" align="right" width="100" alt="eyeris website" /></a>
<!-- badges: start -->
[](https://github.com/shawntz/eyeris/tree/dev)
[](https://CRAN.R-project.org/package=eyeris)
[](https://cran.r-project.org/package=badger)
[](https://doi.org/10.1101/2025.06.01.657312)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/shawntz/eyeris/actions/workflows/build.yml)
[](https://github.com/shawntz/eyeris/actions/workflows/air-format-check.yml)
[](https://github.com/shawntz/eyeris/actions/workflows/air-format-suggest.yml)
[](https://github.com/shawntz/eyeris/actions/workflows/spellcheck.yml)
[](https://github.com/shawntz/eyeris/actions/workflows/pkgdown.yml)
<!-- badges: end -->
<div class="alert alert-light">
<h2>π» eyeris DevOps Dashboard</h2>
Dive deeper into <code>eyeris'</code> development and operational insights with our new <a href="https://shawnschwartz.notion.site/eyeris-devops" target="_blank">eyeris DevOps Dashboard</a>!
</div>
<!-- The goal of eyeris is to ... -->
## π‘ Motivation
Despite decades of pupillometry research, many established packages
and workflows unfortunately lack design principles based on
(F)indability (A)ccessbility (I)nteroperability (R)eusability (FAIR)
principles. `eyeris`, on the other hand follows a thoughtful design
philosophy that results in an intuitive, modular, performant, and extensible
pupillometry data preprocessing framework. Much of these design principles were
heavily inspired by `Nipype`.
`eyeris` also provides a highly opinionated pipeline for tonic and phasic
pupillometry preprocessing (inspired by `fMRIPrep`). These opinions are the
product of many hours of discussions from core members and signal processing
experts from the Stanford Memory Lab (Shawn Schwartz, Mingjian He, Haopei Yang,
Alice Xue, and Anthony Wagner).
`eyeris` also introduces a `BIDS`-like
structure for organizing derivative (preprocessed) pupillometry data, as
well as an intuitive workflow for inspecting preprocessed pupillometry epochs
within beautiful, interactive HTML report files (see demonstration below β¬)!
The package also includes gaze heatmaps that show the distribution of eye
coordinates across the entire screen area, helping you assess data quality
and participant attention patterns. These heatmaps are automatically generated
in the BIDS reports and can also be created manually.
## π Feature Highlights
- `π¦ Modular Design`: Each preprocessing step is a standalone function that can be used independently or combined into custom pipelines.
- `π Interactive Reports`: Beautiful, interactive HTML reports that summarize preprocessing steps and visualize data quality.
- `π Flexible Extensions`: Easily create custom extensions to the preprocessing pipeline by writing your own functions and adding them to the pipeline.
- `π Data Quality Assessment`: Automatically generated figures of each preprocessing step and its effect on the pupil signal (at the global and trial levels), as well as gaze heatmaps and binocular correlation plots to assess data quality and participant attention patterns.
- `ποΈ BIDS-like File Structure`: Organizes preprocessed data using a BIDS-like directory structure that supports both monocular and binocular eye-tracking data.
- `π Logging Commands`: Automatically capture all console output and errors to timestamped log files.
```{r, echo=FALSE, fig.dpi=300, out.width='100%'}
knitr::include_graphics("https://github.com/shawntz/eyeris/raw/dev/inst/figures/interactive-reports-demo.gif")
```
## π Function Reference
Below is a table of all main `eyeris` functions, organized by feature, with links to their documentation and a brief description.
| **Feature** | **Function Documentation** | **Description** |
|----------------------------|---------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| **Pipeline Orchestration** | [glassbox()](https://shawnschwartz.com/eyeris/reference/glassbox.html) | Run the full recommended preprocessing pipeline with a single function call. |
| **BIDSify** | [bidsify()](https://shawnschwartz.com/eyeris/reference/bidsify.html) | Create a BIDS-like directory structure for preprocessed data as well as interactive HTML reports for data and signal processing provenance. |
| **Data Loading** | [load_asc()](https://shawnschwartz.com/eyeris/reference/load_asc.html) | Load EyeLink `.asc` files into an `eyeris` object. |
| **Blink Artifact Removal** | [deblink()](https://shawnschwartz.com/eyeris/reference/deblink.html) | Remove blink artifacts by extending and masking missing samples. |
| **Transient (Speed-Based) Artifact Removal** | [detransient()](https://shawnschwartz.com/eyeris/reference/detransient.html) | Remove transient spikes in the pupil signal using a moving MAD filter. |
| **Linear Interpolation** | [interpolate()](https://shawnschwartz.com/eyeris/reference/interpolate.html) | Interpolate missing (NA) samples in the pupil signal. |
| **Lowpass Filtering** | [lpfilt()](https://shawnschwartz.com/eyeris/reference/lpfilt.html) | Apply a Butterworth lowpass filter to the pupil signal. |
| **Downsampling** | [downsample()](https://shawnschwartz.com/eyeris/reference/downsample.html) | Downsample the pupil signal to a lower sampling rate. |
| **Binning** | [bin()](https://shawnschwartz.com/eyeris/reference/bin.html) | Bin pupil data into specified time bins using mean or median. |
| **Detrending** | [detrend()](https://shawnschwartz.com/eyeris/reference/detrend.html) | Remove slow drifts from the pupil signal by linear detrending. |
| **Z-scoring** | [zscore()](https://shawnschwartz.com/eyeris/reference/zscore.html) | Z-score the pupil signal within each block. |
| **Confound Summary** | [summarize_confounds()](https://shawnschwartz.com/eyeris/reference/summarize_confounds.html) | Summarize and visualize confounding variables for each preprocessing step. |
| **Epoching & Baselining** | [epoch()](https://shawnschwartz.com/eyeris/reference/epoch.html) | Extract time-locked epochs from the continuous pupil signal. |
| **Plotting** | [plot()](https://shawnschwartz.com/eyeris/reference/plot.eyeris.html) | Plot the pupil signal and preprocessing steps. |
| **Gaze Heatmaps** | [plot_gaze_heatmap()](https://shawnschwartz.com/eyeris/reference/plot_gaze_heatmap.html) | Generate heatmaps of gaze position across the screen. |
| **Binocular Correlation** | [plot_binocular_correlation()](https://shawnschwartz.com/eyeris/reference/plot_binocular_correlation.html) | Compute correlation between left and right eye pupil signals. |
| **Demo (Monocular) Dataset** | [eyelink_asc_demo_dataset()](https://shawnschwartz.com/eyeris/reference/eyelink_asc_demo_dataset.html) | Load a demo monocular recording EyeLink dataset for testing and examples. |
| **Demo (Binocular) Dataset** | [eyelink_asc_binocular_demo_dataset()](https://shawnschwartz.com/eyeris/reference/eyelink_asc_binocular_demo_dataset.html) | Load a demo binocular recording EyeLink dataset for testing and examples. |
| **Logging Commands** | [eyelogger()](https://shawnschwartz.com/eyeris/reference/eyelogger.html) | Automatically capture all console output and errors to timestamped log files. |
| **Database Storage** | [eyeris_db_collect()](https://shawnschwartz.com/eyeris/reference/eyeris_db_collect.html) | High-performance database storage and querying alternative to CSV files. |
| **Database Summary** | [eyeris_db_summary()](https://shawnschwartz.com/eyeris/reference/eyeris_db_summary.html) | Get comprehensive overview of database contents and metadata. |
| **Database Connection** | [eyeris_db_connect()](https://shawnschwartz.com/eyeris/reference/eyeris_db_connect.html) | Connect to eyeris databases for custom queries and operations. |
| **Database Export (Chunked)** | [eyeris_db_to_chunked_files()](https://shawnschwartz.com/eyeris/reference/eyeris_db_to_chunked_files.html) | Export large databases in configurable chunks with automatic file size limits. |
| **Database Export (Parquet)** | [eyeris_db_to_parquet()](https://shawnschwartz.com/eyeris/reference/eyeris_db_to_parquet.html) | Export database to high-performance Parquet format files. |
| **Read Parquet Files** | [read_eyeris_parquet()](https://shawnschwartz.com/eyeris/reference/read_eyeris_parquet.html) | Read and combine eyeris Parquet files with schema-aligned binding. |
| **Database Sharing (Split)** | [eyeris_db_split_for_sharing()](https://shawnschwartz.com/eyeris/reference/eyeris_db_split_for_sharing.html) | Split databases into chunks for easier sharing and collaboration. |
| **Database Sharing (Reconstruct)** | [eyeris_db_reconstruct_from_chunks()](https://shawnschwartz.com/eyeris/reference/eyeris_db_reconstruct_from_chunks.html) | Reconstruct complete databases from shared chunks. |
| **Custom Extensions** | _See vignette: [Custom Extensions](https://shawnschwartz.com/eyeris/articles/custom-extensions.html)_ | Learn how to write your own pipeline steps and integrate them with `eyeris`. |
| **Internal API Reference** | _See vignette: [Internal API Reference](https://shawnschwartz.com/eyeris/articles/internal-api.html)_ | Comprehensive documentation of all internal functions for advanced users and developers. |
> For a full list of all functions, see the [eyeris reference index](https://shawnschwartz.com/eyeris/reference/index.html).
## π Tutorials
### π Start Here
- [β Getting Started: Complete (Opinionated) Pupillometry Pipeline Walkthrough](https://shawnschwartz.com/eyeris/articles/complete-pipeline.html)
- [π Extracting Data Epochs and Exporting Pupil Data](https://shawnschwartz.com/eyeris/articles/epoching-bids-reports.html)
### π Pupil Data Quality Control
- [π QC with Interactive Reports](https://shawnschwartz.com/eyeris/articles/reports.html)
### π― Advanced Topics
- [π« Anatomy of an `eyeris` Object](https://shawnschwartz.com/eyeris/articles/anatomy.html)
- [π Building Your Own Custom Pipeline Extensions](https://shawnschwartz.com/eyeris/articles/custom-extensions.html)
- [π Database Storage Guide: Scalable Alternative to CSV Files](https://shawnschwartz.com/eyeris/articles/database-guide.html)
## π¦ Package Installation
### Stable release from CRAN
You can install the stable release of [`eyeris` from CRAN](https://cran.r-project.org/package=eyeris) with:
```r
install.packages("eyeris")
```
or
``` r
# install.packages("pak")
pak::pak("eyeris")
```
### Development version from GitHub
You can install the development version of [`eyeris` from GitHub](https://github.com/shawntz/eyeris) with:
``` r
# install.packages("devtools")
devtools::install_github("shawntz/eyeris", ref = "dev")
```
### Optional: Database and Parquet Support
`eyeris` offers optional high-performance database storage (via `DuckDB`) and parquet file I/O (via `Arrow`) as alternatives to CSV files. These packages are **not required** for core functionality but provide significant performance benefits for large-scale analyses.
#### Installing DuckDB (for database features)
The `duckdb` package enables efficient storage and querying of large datasets. Required for `bidsify(..., db_enabled = TRUE)` and all `eyeris_db_*` functions:
```r
install.packages("duckdb")
```
**Platform-specific notes:**
- **macOS**: `install.packages("duckdb", type = "binary")`
- **Linux**: Use system packages (e.g., `sudo apt-get install r-cran-duckdb`) or install from CRAN
- **Windows**: `install.packages("duckdb")`
#### Installing Arrow (for faster parquet operations)
The `arrow` package provides high-performance parquet file I/O for functions like `eyeris_db_to_parquet()`, `read_eyeris_parquet()`, and related export/import operations. When not available, `eyeris` automatically falls back to DuckDB for parquet operations (slower but functional).
**macOS users:** Arrow requires system dependencies via Homebrew:
```bash
# Install system dependencies first
brew update
brew install pkg-config cmake apache-arrow
# Then install the R package
```
```r
install.packages("arrow", type = "binary")
```
**Linux users (Ubuntu/Debian):**
```bash
# Install system dependencies
sudo apt-get update
sudo apt-get install -y libcurl4-openssl-dev libssl-dev
```
```r
install.packages("arrow")
```
**Linux users (Fedora/RHEL):**
```bash
# Install system dependencies
sudo dnf install libcurl-devel openssl-devel
```
```r
install.packages("arrow")
```
**Windows users:**
```r
install.packages("arrow")
```
For more details, see the [Arrow R documentation](https://arrow.apache.org/docs/r/).
> **Note:** When you load `eyeris`, startup messages will inform you if DuckDB or Arrow are not installed and provide detailed platform-specific installation instructions. You can also access these instructions anytime via `?check_duckdb` and `?check_arrow`. Once installed, restart R and reload `eyeris` to enable these features.
## β Example
### The `glassbox()` "prescription" function
This is a basic example of how to use `eyeris` out of the box with our very
*opinionated* set of steps and parameters that one should start out with when
preprocessing pupillometry data. Critically, this is a "glassbox" -- as opposed
to a "blackbox" -- since each step and parameter implemented herein is fully
open and accessible to you. We designed each pipeline step / function to be like
a LEGO brick -- they are intentionally and carefully designed in a way that allows you
to flexibly construct and compare different pipelines.
We hope you enjoy! -Shawn
```{r glassbox-example, echo=TRUE, results='hide', fig.show='hide', fig.dpi=120}
set.seed(32)
library(eyeris)
demo_data <- eyelink_asc_demo_dataset()
eyeris_preproc <- glassbox(
demo_data,
lpfilt = list(plot_freqz = FALSE)
)
```
### Step-wise correction of pupillary signal
```{r glassbox-plot, echo=TRUE, eval=FALSE, results='hide', fig.show='hide', warning=TRUE, message=TRUE, fig.width=12, fig.height=7, fig.dpi=300}
plot(eyeris_preproc, add_progressive_summary = TRUE)
```
<div style="display: flex; justify-content: center; gap: 20px;"><span><img src="https://github.com/shawntz/eyeris/raw/dev/inst/figures/ts_coalesced.gif" width="49%" alt="glassbox timeseries animation"></span><span><img src="https://github.com/shawntz/eyeris/raw/dev/inst/figures/hists_coalesced.gif" width="49%" alt="glassbox histograms animation"></span></div>
### Final pre-post correction of pupillary signal (raw β‘ preprocessed)
```{r timeseries-plot, echo=TRUE, fig.width=7, fig.height=4, fig.dpi=120}
start_time <- min(eyeris_preproc$timeseries$block_1$time_secs)
end_time <- max(eyeris_preproc$timeseries$block_1$time_secs)
plot(eyeris_preproc,
# steps = c(1, 5), # uncomment to specify a subset of preprocessing steps to plot; by default, all steps will plot in the order in which they were executed by eyeris
preview_window = c(start_time, end_time),
add_progressive_summary = TRUE
)
plot_gaze_heatmap(
eyeris = eyeris_preproc,
block = 1
)
```
## π Database Storage: Scalable Alternative to CSV Files
`eyeris` includes powerful database functionality powered by `DuckDB` that provides a scalable, efficient alternative to CSV file storage. This is especially valuable for large studies, cloud computing, and collaborative research projects.
### Why Use Databases?
**π Performance at Scale**
- Handle hundreds of subjects efficiently vs. managing thousands of CSV files
- Faster queries: filter and aggregate at the database level instead of loading all data into `R`
- Reduced memory usage: load only the data you need
**π― Cloud Computing Optimized**
- Reduce I/O costs on AWS, GCP, Azure
- Single database file vs. thousands of CSV files for data transfer
- Bandwidth efficient and cost-effective for large datasets
**π Data Integrity**
- Built-in schema validation prevents data corruption
- Automatic metadata tracking and timestamps
### Quick Start: `eyeris` Project Database Creation
Enable `eyeris` project database storage alongside or instead of CSV files:
```{r database-example, eval=FALSE}
bidsify(
processed_data,
bids_dir = "~/my_study",
participant_id = "001",
session_num = "01",
task_name = "memory_task",
csv_enabled = TRUE, # keep traditional BIDS-style CSV output files
db_enabled = TRUE, # but also create an eyeris project database
db_path = "study_database"
)
bidsify(
processed_data,
bids_dir = "~/my_study",
participant_id = "001",
session_num = "01",
task_name = "memory_task",
csv_enabled = FALSE, # skip CSV creation
db_enabled = TRUE, # cloud-optimized: Database only (no CSV files)
db_path = "study_database"
)
```
### Simple Data Extraction
Extract all your data with one function call:
```{r database-extraction, eval=FALSE}
# extract ALL data for ALL subjects
all_data <- eyeris_db_collect("~/my_study", "study_database")
# access specific data types
timeseries_data <- all_data$timeseries
confounds_data <- all_data$run_confounds
# targeted extraction: specific subjects and data types
subset_data <- eyeris_db_collect(
"~/my_study",
"study_database",
subjects = c("001", "002", "003"),
data_types = c("timeseries", "epochs", "confounds_summary")
)
```
### Database Overview and Management
```{r database-management, eval=FALSE}
# get a comprehensive database summary
summary <- eyeris_db_summary("~/my_study", "study_database")
summary$subjects # all subjects in database
summary$data_types # available data types
summary$total_tables # number of tables
# connect to eyeris database for custom operations
con <- eyeris_db_connect("~/my_study", "study_database")
# ... custom SQL queries ...
eyeris_db_disconnect(con)
```
> **π‘ Pro Tip**: Use `csv_enabled = FALSE, db_enabled = TRUE` for cloud computing to maximize efficiency and minimize costs.
> **π Complete Guide**: See the [Database Storage Guide](https://shawnschwartz.com/eyeris/articles/database-guide.html) for comprehensive tutorials, advanced usage, and real-world examples.
## π BIDS-like file structure
`eyeris` organizes preprocessed data using a BIDS-like directory structure that supports both monocular and binocular eye-tracking data. The `bidsify()` function creates a standardized directory hierarchy with separate organization for different data types.
### Monocular data structure
For single-eye recordings, data are organized in the main eye directory:
```
bids_dir/
βββ derivatives/
βββ sub-001/
βββ ses-01/
βββ sub-001.html
βββ eye/
βββ sub-001_ses-01_task-test_run-01_desc-timeseries_eye.csv
βββ sub-001_ses-01_task-test_run-01_desc-confounds.csv
βββ sub-001_ses-01_task-test_run-01_epoch-stimulus_desc-preproc_pupil.csv
βββ sub-001_ses-01_task-test_run-01_baseline-stimulus_desc-preproc_pupil.csv
βββ sub-001_ses-01_task-test_run-01_events.csv
βββ sub-001_ses-01_task-test_run-01_blinks.csv
βββ sub-001_ses-01_task-test_run-01_summary.csv
βββ sub-001_ses-01_task-test_run-01.html
βββ source/
βββ figures/
β βββ run-01/
β βββ run-01_fig-1_deblink.jpg
β βββ run-01_fig-2_detrend.jpg
β βββ run-01_fig-3_interpolate.jpg
β βββ run-01_fig-4_lpfilt.jpg
β βββ run-01_fig-5_zscore.jpg
β βββ run-01_gaze_heatmap.png
β βββ run-01_detrend.png
β βββ run-01_desc-progressive_summary.png
βββ logs/
βββ run-01_metadata.json
```
### Binocular data structure
For binocular recordings, data are organized into separate `left` and `right` eye subdirectories:
```
bids_dir/
βββ derivatives/
βββ sub-001/
βββ ses-01/
βββ sub-001-L.html
βββ sub-001-R.html
βββ eye-L/
β βββ sub-001_ses-01_task-test_run-01_desc-timeseries_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_desc-confounds_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_epoch-stimulus_desc-preproc_pupil_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_baseline-stimulus_desc-preproc_pupil_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_events_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_blinks_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_summary_eye-L.csv
β βββ sub-001_ses-01_task-test_run-01_eye-L.html
β βββ source/
β βββ figures/
β β βββ run-01/
β βββ logs/
β βββ run-01_metadata.json
βββ eye-R/
βββ sub-001_ses-01_task-test_run-01_desc-timeseries_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_desc-confounds_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_epoch-stimulus_desc-preproc_pupil_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_baseline-stimulus_desc-preproc_pupil_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_events_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_blinks_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_summary_eye-R.csv
βββ sub-001_ses-01_task-test_run-01_eye-R.html
βββ source/
βββ figures/
β βββ run-01/
βββ logs/
βββ run-01_metadata.json
```
### File naming convention
All files follow a consistent BIDS-like naming pattern:
- **Timeseries data**: `desc-timeseries_eye` (with `_eye-L` or `_eye-R` suffix for binocular data)
- **Confounds**: `desc-confounds` (with eye suffix for binocular data)
- **Epochs**: `epoch-{event}_desc-preproc_pupil` (with eye suffix for binocular data)
- **Baselines**: `baseline-{event}_desc-preproc_pupil` (with eye suffix for binocular data)
- **Events**: `events` (with eye suffix for binocular data)
- **Blinks**: `blinks` (with eye suffix for binocular data)
- **Reports**: HTML files with eye suffix for binocular data
### Events and blinks data
The events and blinks CSV files contain the raw event markers and blink detection data as stored in the eyeris object:
**Events file structure:**
- `block`: Block/run number
- `time`: Timestamp of the event
- `text`: Raw event text from the ASC file
- `text_unique`: Unique event identifier
**Blinks file structure:**
- `block`: Block/run number
- `stime`: Start time of the blink
- `etime`: End time of the blink
- `dur`: Duration of the blink in milliseconds
- `eye`: Eye identifier (L/R for binocular data)
### Key features
- **Organized Structure**: Clear separation between monocular and binocular data
- **Consistent Naming**: Standardized file naming across all data types
- **Complete Documentation**: HTML reports with preprocessing summaries and visualizations
- **Quality Assessment**: Gaze heatmaps and binocular correlation plots for data quality evaluation
- **Reproducibility**: Metadata files documenting preprocessing parameters and call stacks
## π Logging `eyeris` commands with `eyelogger()`
The `eyelogger()` utility lets you run any `eyeris` command (or block of R code) while automatically capturing all console output and errors to timestamped log files. This is especially useful for reproducibility, debugging, or running batch jobs.
**How it works:**
- All standard output (`stdout`) and standard error (`stderr`) are saved to log files in a directory you specify (or a temporary directory by default).
- Each run produces two log files:
- `<timestamp>.out`: all console output
- `<timestamp>.err`: all warnings and errors
### Usage
You can wrap any `eyeris` command or block of code in `eyelogger({ ... })`:
```r
library(eyeris)
# log a simple code block with messages, warnings, and prints
eyelogger({
message("eyeris `glassbox()` completed successfully.")
warning("eyeris `glassbox()` completed with warnings.")
print("some eyeris-related information.")
})
# log a real eyeris pipeline run, saving logs to a custom directory
log_dir <- file.path(tempdir(), "eyeris_logs")
eyelogger({
glassbox(eyelink_asc_demo_dataset(), interactive_preview = FALSE)
}, log_dir = log_dir)
```
### Parameters
- `eyeris_cmd`: The code to run (wrap in `{}` for multiple lines).
- `log_dir`: Directory to save logs (default: a temporary directory).
- `timestamp_format`: Format for log file names (default: `"%Y%m%d_%H%M%S"`).
### What you get
After running, you'll find log files in your specified directory, e.g.:
```
20240614_153012.out # console output
20240614_153012.err # warnings and errors
```
This makes it easy to keep a record of your preprocessing runs and debug any issues that arise.
---
## :see_no_evil: `eyeris` dependency graph
```{r, eval=TRUE, echo=FALSE, fig.width=8.5, fig.height=10, fig.dpi=120, warning=FALSE}
depgraph::plot_dependency_graph(
pkg = ".",
suggests = FALSE,
option = "turbo",
ggrepel_opts = list(max.overlaps = 150)
)
```
---
## π€ Contributing to `eyeris`
Thank you for considering contributing to the open-source `eyeris` R package; there are many ways one could contribute to `eyeris`.
We believe the best preprocessing practices emerge from collective expertise and rigorous discussion. Please see the [contribution guidelines](https://shawnschwartz.com/eyeris/CONTRIBUTING.html) for more information on how to get started..
## π Code of Conduct
Please note that the eyeris project is released with a [Contributor Code of Conduct](https://shawnschwartz.com/eyeris/CODE_OF_CONDUCT.html). By contributing
to this project, you agree to abide by its terms.
## π¬ Suggestions, questions, issues?
Please use the issues tab (https://github.com/shawntz/eyeris/issues) to make note of any bugs, comments, suggestions, feedback, etc... all are welcomed and appreciated, thanks!
## π Citing `eyeris`
<div class="alert alert-light" style="padding-bottom: 0;">
If you use the `eyeris` package in your research, please consider citing our preprint!
Run the following in R to get the citation:
</div>
```{r}
citation("eyeris")
```