Quick Pooling Model for Photoreceptor Contributions

Fitting photoreceptor pooling models to melatonin suppression and pupillary light reflex spectral sensitivities using the Quick (1974) framework.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#E8F4FD', 'primaryBorderColor': '#7BA7C9', 'primaryTextColor': '#2C3E50', 'secondaryColor': '#FDF2E9', 'secondaryBorderColor': '#D4A574', 'secondaryTextColor': '#2C3E50', 'tertiaryColor': '#EAFAF1', 'tertiaryBorderColor': '#82C9A1', 'tertiaryTextColor': '#2C3E50', 'lineColor': '#5D6D7E', 'textColor': '#2C3E50', 'background': '#FFFFFF', 'mainBkg': '#E8F4FD', 'nodeBorder': '#7BA7C9', 'clusterBkg': '#F8F9FA', 'clusterBorder': '#BDC3C7', 'fontSize': '14px'}}}%%
flowchart LR
    A[Photoreceptor Sensitivities] --> B[Weighted Pooling]
    B --> C[Predicted Action Spectrum]
    C --> D[Fit to Data]
    D --> E[Model Selection]

    style A fill:#FDF2E9,stroke:#D4A574
    style B fill:#E8F4FD,stroke:#7BA7C9
    style C fill:#E8F4FD,stroke:#7BA7C9
    style D fill:#E8F4FD,stroke:#7BA7C9
    style E fill:#EAFAF1,stroke:#82C9A1

Loading

Overview

This repository implements several photoreceptor contribution models within the Quick pooling framework (Quick, 1974) to estimate the relative contributions of rods, cones, and melanopsin to non-visual light responses. The primary demonstration fits these models to melatonin suppression data from Thapan et al. (2001) and Brainard et al. (2001), exploring how stimulus duration affects the balance between cone-driven and melanopsin-driven responses.

Four opponent-channel models of increasing complexity are implemented, progressing from the simple additive model of McDougal and Gamlin (2010) to the spectral opponency models of Kurtenbach et al. (1999), Spitschan et al. (2014), and Woelders et al. (2018). The fitting is performed in MATLAB using constrained optimization (fmincon), with R used for statistical analysis and publication-quality plotting.

Key Features

• Four pooling models -- from simple additive to full spectral opponency (Woelders et al., 2018)
• Melatonin suppression fitting using data from Thapan et al. (2001) and Brainard et al. (2001)
• Duration-dependent analysis -- shorter (30 min) vs. longer (90 min) exposures reveal increasing melanopsin contribution
• Constrained optimization via MATLAB fmincon with configurable algorithms
• R visualization for publication-quality parameter evolution and model comparison plots
• Modular design -- photoreceptor spectra, pooling functions, and fitting routines are separated

Quick Start

# Clone with submodules
git clone --recurse-submodules https://github.com/petteriTeikari/quick_pooling.git
cd quick_pooling

# MATLAB: Run the main fitting script
# Open MATLAB and run:
#   TRY_melatonin_models_for_CUSTOM_data.m

# R: Generate plots from MATLAB output
Rscript R_code/plot_matlab_fitting.R

Project Structure

quick_pooling/
├── TRY_melatonin_models_for_CUSTOM_data.m   # Main MATLAB entry point
├── visualize_pooling_models_for_CUSTOM.m     # Model visualization
├── normalize_time_point_CUSTOM.m             # Time-point normalization
├── pooling_model/                            # Core model functions
│   ├── poolingModel_main.m                   # Optimization driver
│   ├── poolingModel_function.m               # Pooling equation
│   ├── poolingModel_defineNeededSpectra.m     # Photoreceptor templates
│   ├── fit_model_to_melatonin_wrapper.m      # Fitting wrapper
│   ├── import_the_data.m                     # Data import
│   └── defineNoFreeParameters.m              # Parameter constraints
├── R_code/                                   # R analysis and plotting
│   ├── plot_matlab_fitting.R                 # Main R plotting script
│   ├── plot_parameter_evolution.R            # Parameter trajectories
│   └── plot_model_fit_per_timepoint.R        # Per-timepoint fits
├── photoreception_tools/                     # Photoreceptor spectral tools
├── data/                                     # Input data files
├── data_out_from_matlab/                     # MATLAB fitting outputs
├── R_figures_out/                            # R-generated figures
└── images_biblio/                            # Reference figures from literature

Citation

If you use this code, please cite the relevant spectral sensitivity studies:

@article{thapan2001action,
  title={An action spectrum for melatonin suppression},
  author={Thapan, Kavita and Arendt, Josephine and Skene, Debra J.},
  journal={The Journal of Physiology},
  volume={535},
  number={1},
  pages={261--267},
  year={2001},
  doi={10.1111/j.1469-7793.2001.t01-1-00261.x}
}

@article{brainard2001action,
  title={Action spectrum for melatonin regulation in humans},
  author={Brainard, George C. and Hanifin, John P. and Greeson, Jeffrey M. and others},
  journal={Journal of Neuroscience},
  volume={21},
  number={16},
  pages={6405--6412},
  year={2001},
  doi={10.1523/JNEUROSCI.21-16-06405.2001}
}

@article{woelders2018melanopsin,
  title={Integration of color and intensity increases time signal stability for the human circadian system when sunlight is dim},
  author={Woelders, Tom and Leenheers, Thomas and Gordijn, Marijke C. M. and Hut, Roelof A. and Beersma, Domien G. M. and Wams, Emma J.},
  journal={Proceedings of the National Academy of Sciences},
  volume={115},
  number={21},
  pages={E4714--E4723},
  year={2018},
  doi={10.1073/pnas.1716281115}
}

License

This project is licensed under the MIT License. See LICENSE for details.