Constructing melanopic light exposure profiles from sparse daily-route measurements

1. Overview

This repository contains the Python and R code required to reproduce the analyses, figures, and tables presented in:

Tabandeh, N., Veitch, J. A., & Spitschan, M. (2026). Constructing melanopic light exposure profiles from sparse daily-route measurements. Preprint: https://doi.org/10.21203/rs.3.rs-9868828/v1

If you have any comments or queries, please contact:

• Niloufar Tabandeh (niloufar.tabandehsaravi@tum.de)
• Manuel Spitschan (manuel.spitschan@tum.de)

The repository is designed to be fully reproducible across operating systems. All internal paths are relative.

All data required to reproduce the analyses presented in the manuscript are included in the data/ directory of this repository. No external datasets are required to reproduce the results.

The repository combines Python and R workflows to generate synthetic melanopic exposure sequences, compute summary metrics, and reproduce all figures and tables reported in the manuscript.

The input files included in the data/ directory were derived from measurements collected as part of the SCENES dataset. The complete SCENES dataset, including the original measurement data and accompanying documentation, is publicly available through the EDMOND research data repository:

SCENES dataset: https://doi.org/10.17617/3.PYHUO5

The analysis pipeline involves both Python and R code and must be executed in the order described in the Workflow section of this document.

An independent CODECHECK review successfully reproduced the outputs generated by this repository. The full certificate is available on Zenodo (link to be added).

---

2. Repository Structure

📁 TabandehEtAl_npjBiolTimingSleep_2026/
 ├── 📄README.md
 ├── 📄LICENSE
 ├── 📄TabandehEtAl_npjBiolTimingSleep_2026.Rproj
 ├── 📄environment.yml
 └── 📄renv.lock
 📁 code/
     ├── 📄 LightLogR.html
     ├── 📄 LightLogR.qmd
     └── 📄 trajectory.ipynb
 📁 data/
     ├── 📄 20230614RoofBox1min.csv               # Downwelling data 20230614
     ├── 📄 20230616RoofBox1min.csv               # Downwelling data 20230616
     ├── 📄 20230619RoofBox1min.csv               # Downwelling data 20230619
     ├── 📄 metadata_jeti_scenes.csv              # Data and metadata 
     ├── 📄 real_world_dataset.csv
     └── 📄 tailored_trajectory_sequences.xlsx    # Tailored scenarios sequences
 📁 renv/
     ├── 📄 activate.R
     └── 📄 settings.json
 📁 results/
     └── 📄 datatree.txt
│    📁 plots/
│       ├── 📄 Figure*.pdf
│       ├── 📄 Figure*.png
│       ├── 📄 <model-name>.pdf
│       ├── 📄 <model-name>.png
│       └── ...
│    📁 tables/
│       ├── 📄 pivot_melanopic_metadata_trajectory_canada.csv
│       ├── 📄 pivot_photopic_melanopic_trajectory_canada.csv
│       ├── 📄 pivot_summary_metrics_stats.csv
│       └── 📄 pivot_summary_trajectory_canada.csv
│   │   📁 LightLogR/
│   │   │   📁 metrics_raw/
│   │   │       ├── 📄 <model-name>_melanopic.csv
│   │   │       └── 📄 <model-name>_melanopic_numeric.csv
│   │   📁 sequences/
│   │       └── 📄 <model-name>_melanopic_sequence.csv

---

3. Environment Setup

The analysis requires both Python and R environments. The Python environment is used to generate synthetic melanopic exposure sequences and produce the final manuscript figures, while the R environment is used to calculate summary metrics from the generated sequences using LightLogR.

3.1 Python Environment

Create and activate the Python environment:

conda env create -f environment.yml
conda activate trajectory_env

This environment contains all dependencies required to run the Jupyter notebook and reproduce the sequence-generation and figure-creation workflow.

3.2 R Environment

The LightLogR analysis is defined in code/LightLogR.qmd.

R package versions are recorded in renv.lock, which targets R 4.5.0. Quarto is installed separately and is not managed by renv.

Prerequisites

• R 4.5.0
• Quarto CLI
• Git

Restore the project-specific R environment from the repository root:

# Confirm that Quarto is available
quarto check

# Restore the project-local R package library
Rscript -e 'renv::restore(prompt = FALSE)'

# Create the output directory expected by LightLogR.qmd
Rscript --vanilla -e 'dir.create("results/tables/LightLogR/metrics_raw", recursive = TRUE, showWarnings = FALSE)'

The repository contains an renv.lock file that records all package versions required to reproduce the manuscript results.

A reduced reproduction run can be performed using:

quarto render code/LightLogR.qmd -P n_columns:101

This command processes the first 100 generated sequences from each input dataset and is intended for testing purposes with lower computational requirements.

To reproduce the complete LightLogR analysis, run:

quarto render code/LightLogR.qmd

This generates:

• code/LightLogR.html
• Metric tables in results/tables/LightLogR/metrics_raw/

---

4. Workflow

All data required to reproduce the analyses are included in the data/ directory. No external datasets are required to reproduce the results.

The analysis combines Python and R workflows and must be executed in the order described below.

Step 1: Generate Synthetic Sequences (Python)

Open and run:

code/trajectory.ipynb

Execute the notebook from the beginning until the section that generates the synthetic melanopic exposure sequences.

A markdown cell within the notebook clearly indicates where execution should stop before proceeding to the R analysis.

This step:

• Loads the input data from data/
• Generates synthetic sequences for all hierarchical rules
• Saves sequence files to:

results/tables/sequences/

Step 2: Calculate Light Exposure Metrics (R)

After all synthetic sequences have been generated, render:

quarto render code/LightLogR.qmd

This step:

• Loads the generated sequence files from results/tables/sequences/
• Calculates LightLogR metrics for each sequence
• Produces summary metric tables
• Saves outputs to:

results/tables/LightLogR/metrics_raw/

The generated metric tables are required for the remaining analysis steps in the Python notebook.

Step 3: Generate Final Results (Python)

Return to:

code/trajectory.ipynb

Continue executing the remaining notebook cells.

This step:

• Loads the LightLogR summary metrics generated in Step 2
• Produces all manuscript figures
• Produces summary tables
• Saves outputs to the results/ directory

Workflow Summary

The complete workflow is:

trajectory.ipynb (Part 1)
            ↓
Generate synthetic sequences
            ↓
LightLogR.qmd
            ↓
Generate summary metrics
            ↓
trajectory.ipynb (Part 2)
            ↓
Generate manuscript figures and tables

---

5. Outputs

The analysis generates outputs in the results/ directory.

Synthetic Sequences

Generated in:

results/tables/sequences/

These files contain the synthetic melanopic exposure sequences generated according to the hierarchical assignment rules.

LightLogR Metrics

Generated in:

results/tables/LightLogR/metrics_raw/

These files contain the LightLogR metrics calculated from the generated synthetic sequences.

Summary Tables

Generated in:

results/tables/

These files contain the summary statistics used throughout the manuscript.

Figures

Generated in:

results/plots/

All manuscript figures are exported in both .png and .pdf formats.

The table below maps manuscript figures to the generated output files.

Manuscript Figure	Generated File
Figure 1	results/plots/Figure1.png
Figure 2	results/plots/Figure2.png
Figure 3	results/plots/unrestricted_pooled.png
Figure 4	results/plots/outdoor_only_bound.png
Figure 5	results/plots/indoor_only_bound.png
Figure 6	results/plots/exact_slot_matched.png
Figure 7	results/plots/broad_context_matched.png
Figure 8	results/plots/activity_block_matched.png
Figure 9	results/plots/Figure9.png
Figure 10	results/plots/Figure10.png
Figure 11	results/plots/Figure11.png
Figure 12	results/plots/Figure12.png

---

6 Hierarchical Rules

Synthetic melanopic exposure sequences are generated using the following hierarchical assignment rules:

Rule	Eligible Pool or Matching Rule
Unrestricted pooled	All 63 observations available for every time slot
Outdoor-only bound	All outdoor observations available for every time slot
Indoor-only bound	All indoor observations available for every time slot
Exact-slot matched	Observations from the same 30-minute time bin
Broad-context matched	Observations from the same broad context (home, commute, office, or noon)
Activity-block matched	Observations from the same morning, noon, or afternoon activity block

The synthetic sequences generated under these rules are saved to:

results/tables/sequences/

and form the basis for the subsequent LightLogR analysis and manuscript figures.

---

7. Reproducibility Notes

• All data required to reproduce the analyses are included in the data/ directory.
• The analysis must be executed in the order described in the Workflow section.
• Synthetic sequences must be generated before running the LightLogR analysis.
• The LightLogR analysis must be completed before executing the final sections of trajectory.ipynb.
• Repository folder names and relative file paths should not be modified.
• All internal paths are relative and therefore operating-system independent.

---

8. License

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

---