LCYA: Locus Coeruleus - Young Adults Study

Overview

This repository contains the supplementary materials and analysis code for the LCYA (Locus Coeruleus - Young Adults) study. The study investigates the effects and interactions of concurrent physical and cognitive effort on behavioral performance and pupillometric responses in younger adults.

Study Design

Main Research Question

How do concurrent physical effort (handgrip force) and cognitive effort (task difficulty) affect:

• Behavioral performance (accuracy, reaction time)
• Physiological arousal (pupil responses measured via AUC metrics)
• Individual differences in effort-related effects
• Brain-behavior relationships

Tasks

Participants performed perceptual discrimination tasks under varying levels of physical and cognitive effort:

• ADT (Auditory Discrimination Task): Frequency discrimination with concurrent handgrip
• VDT (Visual Discrimination Task): Contrast discrimination with concurrent handgrip
• CDT (Change Detection Task): Arrow direction change detection with concurrent handgrip
• MST (Mnemonic Similarity Task): Memory-based similarity judgments

Experimental Manipulations

• Cognitive Effort: Stimulus difficulty (Easy vs. Hard discrimination)
• Physical Effort: Handgrip force levels (Low: 5% MVC vs. High: 40% MVC)
• Pupillometry: Continuous pupil diameter measurement for arousal assessment

Repository Structure

The repository is organized into four main directories:

LCYA/
├── analysis/                    # All analysis scripts
│   ├── main/                   # Complete publication workflow (R Markdown)
│   └── manuscript_scripts/     # Individual analysis scripts
│       ├── figures/            # Scripts to generate manuscript figures (Figures 2-4)
│       └── *.R                 # Statistical analysis scripts
├── code/                       # Reusable code components
│   ├── plot_objects/          # ggplot theme and plot definitions
│   ├── preprocessing/         # Data preprocessing utilities (MATLAB, Python)
│   └── utilities/             # Helper functions for data processing
├── documentation/              # Documentation and results
│   ├── results_reports/       # Statistical analysis reports and summaries
│   └── *.md                   # Documentation files
└── figures/
    └── publication/           # Final publication-ready figures (PNG format)

Directory Descriptions

analysis/ - Contains all analysis scripts organized by purpose:

• main/: Complete analysis pipeline in R Markdown format
• manuscript_scripts/: Individual R scripts for specific analyses
  • figures/: Scripts that generate the manuscript figures
  • Root-level scripts: Statistical models and verification analyses

code/ - Reusable code components:

• plot_objects/: ggplot theme definitions and plot templates for each task
• preprocessing/: Tools for converting and aggregating raw eyetracker data
  • MATLAB scripts for file conversion
  • Python notebooks for data aggregation
• utilities/: Helper functions used across multiple analyses

documentation/ - Comprehensive documentation:

• Analysis overviews and methodological notes
• Statistical reports and summaries
• Results from various analysis approaches

figures/publication/ - Final publication-ready figures:

• All figures are in PNG format, high resolution (300 DPI)
• Generated by scripts in analysis/manuscript_scripts/figures/

Key Analysis Scripts

Main Analysis Pipeline

• analysis/main/Aggregated_analysis_publication.Rmd - Complete analysis pipeline and results (R Markdown)

Manuscript Figures

Figure	Script	Description	Output
Figure 2 – Behavioral performance	analysis/manuscript_scripts/figures/Figure2_Clean_Final_Version.R	Accuracy and reaction time effects across tasks and conditions	figures/publication/Figure2_Task_Performance_Effects.png
Figure 3 – Pupil waveforms	analysis/manuscript_scripts/figures/LCYA_Isolated_Cognitive_AUC_Analysis.R	Time-locked pupil responses with baseline and AUC period annotations (see details below)	figures/publication/Figure3_Pupil_Waveforms.png
Figure 4 – AUC bar plots	analysis/manuscript_scripts/figures/LCYA_Updated_Combined_AUC_Plots.R	Total AUC and Cognitive AUC effects across tasks	Figure4_Total_AUC.png, Figure4_Cognitive_AUC.png
Figure 4 – Combined layout	analysis/manuscript_scripts/figures/LCYA_Figure4_Merged_AUC_Plot.R	Merged visualization of Total and Cognitive AUC	Figure4_Merged_Total_Cognitive_AUC.png

Figure 3 Details:

• Baseline correction: 500ms pre-squeeze window (-0.5s to 0s) for optimal separation
• Time range: From -0.5s (baseline period) to response onset for complete trial visualization
• Smoothing: GAM trajectories with 95% confidence intervals
• Task-specific annotations:
  • CDT: Shows "Pre-trial Baseline" (grey) and "Total AUC" (blue) only. Cognitive AUC excluded per analytical recommendations.
  • ADT/VDT: Shows "Pre-trial Baseline" (grey), "Total AUC" (blue), "Pre-stimulus Baseline" (grey, 500ms before target onset), and "Cognitive AUC" (orange)
• Event markers: Task-specific labels ("Array onset" for CDT, "Target onset" for ADT/VDT, "Probe + Response" for CDT, "Response" for ADT/VDT)

Statistical Analyses

Analysis	Script	Description	Output Location
Full manuscript pipeline	analysis/manuscript_scripts/LCYA_Final_Corrected_Analysis.R	Complete statistical analysis (behavioral, physiological, individual differences)	documentation/results_reports/
Pupillometry AUC models	analysis/manuscript_scripts/LCYA_AUC_Analysis.R	Linear mixed-effects models for Total, Cognitive, and Physical AUC	Model summaries to console/file
Bayesian individual differences	analysis/manuscript_scripts/Bivariate_Individual_Differences_brms.R	Multivariate Bayesian models examining individual-level associations	documentation/results_reports/Individual_Differences_Brms_Report.md
Subject-means individual differences	analysis/manuscript_scripts/Updated_Individual_Differences_Accuracy_RT_SubjectMeans.R	Alternative approach using subject-level means	documentation/results_reports/subject_means/results/
Frequentist verification	analysis/manuscript_scripts/Final_Individual_Differences_Verification.R	Verification of correlations using frequentist methods	Console output
Response bias analysis	analysis/manuscript_scripts/response_bias_analysis.R	GLMM for Same/Different judgment bias	Console output

Data Preprocessing

• MATLAB scripts (code/preprocessing/):
  • eyetracker_mat_to_csv_converter.m - Convert individual MATLAB eyetracker files to CSV
  • batch_convert_eyetracker_files.m - Batch conversion of all eyetracker files
• Python notebooks (code/preprocessing/python_notebooks/):
  • Task-specific aggregation notebooks for trial-level data
  • See code/preprocessing/README.md for detailed preprocessing documentation

Dependencies

Required R Packages

Core Analysis:

• tidyverse - Data manipulation and visualization (dplyr, ggplot2, tidyr, readr, purrr)
• lme4 - Linear mixed-effects models
• lmerTest - p-values for mixed-effects models
• brms - Bayesian regression models (for individual differences)
• mgcv - Generalized additive models (GAM) for smoothing
• patchwork / cowplot - Combining multiple plots
• posterior - Bayesian posterior analysis (for brms)

Visualization:

• ggplot2 - Primary plotting package
• gridExtra - Additional plot arrangement tools
• viridis - Color palettes
• ggridges - Distribution visualizations

Other:

• rmcorr - Repeated measures correlation (optional, for sensitivity analyses)

Installation

# Install CRAN packages
install.packages(c("tidyverse", "lme4", "lmerTest", "mgcv", 
                   "patchwork", "cowplot", "viridis", "ggridges", 
                   "rmcorr", "posterior"))

# Install brms (requires compilation)
install.packages("brms")
# Note: brms may require additional system dependencies; see brms documentation

Usage

Quick Start: Reproducing Manuscript Figures

1. Set up R environment: Install all required packages (see Dependencies section)

2. Update file paths: Edit the BASE_DIR variable in each script to point to your data directory:

   BASE_DIR <- "/path/to/your/LC–YA"

3. Ensure data files are available:

   • Raw pupil data: 100 Hz/ directory with *_DS100_merged.csv files
   • Processed AUC data: PI_Feedback_Outputs/Combined_Dual_AUC_Data.csv (generated by scripts)
   • Behavioral data: Complete_Manuscript_Results/complete_analysis_data.csv

4. Run figure generation scripts (in order):

   # Figure 2: Behavioral performance
   source("analysis/manuscript_scripts/figures/Figure2_Clean_Final_Version.R")
   
   # Figure 3: Pupil waveforms
   source("analysis/manuscript_scripts/figures/LCYA_Isolated_Cognitive_AUC_Analysis.R")
   
   # Figure 4: AUC bar plots
   source("analysis/manuscript_scripts/figures/LCYA_Updated_Combined_AUC_Plots.R")

5. Find outputs: All figures are saved to figures/publication/

Complete Analysis Pipeline

For full reproduction of all analyses:

# Run the complete R Markdown pipeline
rmarkdown::render("analysis/main/Aggregated_analysis_publication.Rmd")

Data Requirements

Note: Due to data privacy and file size constraints, raw data files are not included in this repository. Data are available for reviewers upon reasonable request. Users who wish to reproduce the analyses will need to provide their own data files with the following structure:

• Raw pupil data: 100 Hz/ directory containing *_DS100_merged.csv files with columns:

  • sub (subject ID)
  • trial_index (trial number)
  • time (timestamp)
  • pupil (pupil diameter)
  • duration_label (event labels: "Squeeze", "Arrow"/"Stimulus", "Response", "Confidence")
  • stimLev (stimulus level/difficulty)
  • isStrength (effort condition: 0=Low, 1=High)

• Behavioral data: Processed behavioral data files (accuracy and reaction time)

File paths: Scripts use absolute paths that need to be adjusted for your local setup. Update the BASE_DIR variable at the top of each script.

Key Methodological Decisions

Pupil Waveform Analysis (Figure 3)

• Baseline period: 500ms pre-squeeze (-0.5s to 0s) for optimal separation
• Baseline correction: Global baseline (B0) applied throughout to ensure convergence at squeeze onset
• Task-specific analyses:
  • CDT: Physical effort only (Total AUC); Cognitive AUC excluded per analytical recommendations
  • ADT/VDT: Full 2×2 ANOVA (difficulty × effort) for both Total AUC and Cognitive AUC
• Pre-stimulus Baseline (B2b): 500ms window before target/stimulus onset, shown only for ADT/VDT (used specifically for Cognitive AUC calculation)

AUC Measures

• Pre-trial Baseline (B0): 500ms window (-0.5s to 0s) before squeeze onset, used for global baseline correction
• Pre-stimulus Baseline (B2b): 500ms window before target/stimulus onset, used specifically for Cognitive AUC calculation
• Total AUC: Raw pupil data from squeeze onset (0s) to response onset
• Cognitive AUC: Isolated pupil data (B0-corrected) from 300ms after target/stimulus onset to response onset

Individual Differences Analysis

• Primary method: Multivariate Bayesian mixed-effects models (brms)
• Target estimand: Correlation between subject-specific effort slopes
• Sensitivity analyses: rmcorr and subject-means correlations
• Statistical approach: Bayesian inference with credible intervals

Documentation

For detailed documentation, see:

• documentation/ANALYSIS_OVERVIEW.md - Comprehensive analysis overview
• documentation/CODE_DOCUMENTATION.md - Technical documentation for code files
• documentation/REPOSITORY_STRUCTURE.md - Detailed repository organization
• code/preprocessing/README.md - Data preprocessing instructions

Citation

If you use this code or reference these analyses, please cite:

[Manuscript citation - to be updated upon publication]

Contact

Mohammad Dastgheib
mdast003@ucr.edu

License

This project is licensed under the GPLv3 License - see the LICENSE file for details.