Decomposition Module¶

PLR waveform decomposition methods for extracting interpretable components.

Overview¶

The decomposition module provides methods to decompose PLR signals into meaningful components (e.g., transient, sustained, PIPR). This is useful for understanding the physiological origins of classification features.

Methods¶

Method	Description
Template Fitting	Fit canonical PLR template to signal
PCA	Principal Component Analysis
Rotated PCA	Varimax-rotated PCA for interpretability
Sparse PCA	L1-regularized PCA for sparse components
GED	Generalized Eigenvalue Decomposition

API Reference¶

template_fitting ¶

Template Fitting Decomposition for PLR Waveforms.

Fits physiologically-constrained basis functions to PLR data: - Transient/Phasic: Fast M-pathway response - Sustained/Tonic: Maintained P-pathway response - PIPR: Post-illumination pupil response (melanopsin)

Reference: Kelbsch et al. 2019, Kawasaki et al. 2002

pca_methods ¶

PCA-based Decomposition Methods for PLR Waveforms.

Provides three PCA variants: 1. Standard PCA - Orthogonal principal components 2. Rotated PCA (Promax) - Oblique rotation for correlated components 3. Sparse PCA - L1-penalized for interpretable sparse loadings

Reference: Bustos 2024 "Pupillary Manifolds", Zou 2006 "Sparse PCA"

ged ¶

Generalized Eigendecomposition (GED) for PLR Waveforms.

GED finds components that maximize contrast between two conditions, e.g., stimulus period vs baseline. This is ideal for PLR where we want components that respond maximally to light stimuli.

Reference: Cohen MX (2022) "A tutorial on generalized eigendecomposition for denoising, contrast enhancement, and dimension reduction in multichannel electrophysiology" NeuroImage 247:118809

aggregation ¶

Group-level aggregation of PLR decomposition results with confidence intervals.

Phase 4 of the decomposition figure pipeline: 1. Load preprocessed signals from DuckDB 2. Apply decomposition methods per preprocessing config 3. Aggregate across subjects within each preprocessing category 4. Compute bootstrap confidence intervals

This module is designed to work with the per-subject DuckDB created by scripts/extract_decomposition_signals.py

Usage Example¶

from src.decomposition import decompose_pca, aggregate_decomposition_results

# Decompose a single signal
components = decompose_pca(plr_signal, n_components=3)

# Aggregate across subjects
group_stats = aggregate_decomposition_results(all_decompositions)