Skip to content
BranchesTags

Repository files navigation

🐳 circadiaBase_Docker

A reproducible Docker environment for chronobiology and actigraphy research, built on Python 3.11 + R 4.4 + JupyterLab + RStudio.

License: MIT Python R JupyterLab RStudio Docker

📖 What is circadiaBase_Docker?

circadiaBase_Docker is a self-contained research computing environment for the Circadia Lab. It packages a fully pinned Python + R stack into two Docker services that share the same volume, ensuring reproducibility across machines and collaborators.

  • JupyterLab — Python-based actigraphy, EEG/sleep staging, entropy, and circadian modelling
  • RStudio Server — R-based sleep and circadian analyses with GGIR, ActCR, circacompare, brms, and lme4

✨ Features

  • 🔒 Fully pinned dependencies — every package version is locked for reproducibility
  • 📓 JupyterLab — browser-based notebook interface at localhost:8889
  • 🧪 RStudio Server — full IDE for R at localhost:8787
  • 📂 Shared volume — both services read/write the same project files
  • 📡 pyActigraphy — actigraphy analysis including REST-activity metrics, cosinor, and SSA
  • 🧠 MNE + YASA — EEG processing and automatic sleep staging
  • 📊 Full scientific stack — numpy, scipy, pandas, matplotlib, scikit-learn, seaborn, statsmodels, plotly
  • 🌀 EntropyHub — entropy methods for physiological time series
  • 📈 R stats — lme4, lmerTest, emmeans, ggplot2 extensions
  • 🕰️ R circadian — GGIR, ActCR, circacompare, cosinor
  • 🔬 condor_pipeline — Circadia Lab actigraphy sleep analysis library, installed in editable mode
  • 🍎 Apple Silicon native — RStudio service uses jmgirard/rstudio2u with full ARM64 support
  • 🤖 Auto-configured — .env is generated automatically from the repo name via GitHub Actions
  • ⚙️ Gated R profiles — choose build depth via RSTUDIO_PROFILE in .env

🗂️ Project Structure

circadiaBase_Docker/
├── .github/
│   └── workflows/
│       └── setup-env.yml       # Auto-generates .env from repo name on push
├── condor_pipeline/            # Circadia Lab core actigraphy library (editable install)
│   ├── algorithms/             # Sleep scoring algorithms (Cole-Kripke, vendor)
│   ├── detection/              # Off-wrist, sleep period, WASO detection
│   ├── io/                     # Device readers (ActTrust, Actiwatch)
│   ├── preprocessing/          # Data preparation and consistency checks
│   ├── viz/                    # Actogram and visualisation helpers
│   └── pipeline.py             # High-level SleepPipeline orchestrator
├── jupyter/
│   └── Dockerfile              # Pinned Python 3.11 image
├── notebooks/                  # JupyterLab notebooks
├── rstudio/
│   ├── Dockerfile              # Placeholder — do not use directly
│   ├── Dockerfile.minimal      # r2u + RStudio, no Stan, no lunaR (default)
│   ├── Dockerfile.no-stan      # r2u + RStudio, no Stan, with lunaR
│   └── Dockerfile.full         # r2u + RStudio, Stan + lunaR
├── docker-compose.yml          # Two services: jupyter (8889) + rstudio (8787)
├── pyproject.toml              # condor_pipeline package definition
├── .env                        # Auto-generated by GitHub Actions
├── .env.example                # Template with all configurable variables
├── .gitignore
└── LICENSE

🚀 Getting Started

For a full step-by-step walkthrough, see TUTORIAL.md.

Quick start

git clone https://github.com/circadia-bio/circadiaBase_Docker.git
cd circadiaBase_Docker
cp .env.example .env
docker-compose up --build
Service URL Notes
JupyterLab http://localhost:8889/lab No token required
RStudio Server http://localhost:8787 No password required

🤖 GitHub Actions — Auto-configuration

This repository includes a GitHub Actions workflow (.github/workflows/setup-env.yml) that runs automatically on every push to main. It does two things:

1. Generates .env from the repo name

When you fork or use this repo as a template, the workflow reads the repository name, converts it to a Docker-safe format (lowercase, underscores for special characters), and writes it as IMAGE_NAME in .env. This means collaborators never need to manually configure the image name — it's set correctly the first time they push.

For example, a repo named Per3_Study becomes IMAGE_NAME=per3_study.

2. Resets the README to a stub template (first push only)

On the first push to a new repo, if the README still contains placeholder text, the workflow replaces it with a minimal stub pre-filled with the repo name and Circadia Lab authorship. This only runs once — once you customise the README, the workflow detects it has been updated and skips the reset on all future pushes.

Requirements

For the workflow to commit back to the repo, GitHub Actions needs write permissions. Enable this in your repo under:

Settings → Actions → General → Workflow permissions → Read and write permissions

Local setup (without GitHub Actions)

If you are working locally without pushing to GitHub first, create .env manually:

cp .env.example .env

Then edit IMAGE_NAME to match your project name if needed.

⚙️ Configuration

All configuration lives in .env:

IMAGE_NAME=circadia_base       # Docker image name — set automatically from repo name
DISABLE_AUTH=true              # Disable RStudio password (local dev only)
COMPOSE_PROFILES=both          # Services to run: both | jupyter | rstudio
RSTUDIO_PROFILE=minimal        # R build profile: minimal | no-stan | full

Service profiles

COMPOSE_PROFILES Services started
both (default) JupyterLab + RStudio
jupyter JupyterLab only
rstudio RStudio only

RStudio build profiles

Profile Stan lunaR Build time
minimal (default) ❌ ❌ ~5–8 min
no-stan ❌ ✅ ~10–15 min
full ✅ ✅ ~30–40 min

🔬 condor_pipeline

condor_pipeline is the Circadia Lab's core actigraphy sleep analysis library, included directly in this environment and installed in editable mode (pip install -e .). This means import condor_pipeline works out of the box in any notebook or script, and changes to the source are reflected immediately without rebuilding the image.

Modules

Module Purpose
condor_pipeline.pipeline High-level SleepPipeline orchestrator — single file and batch modes
condor_pipeline.io Device readers for ActTrust and Actiwatch formats
condor_pipeline.preprocessing Data preparation, timestamp consistency checks
condor_pipeline.detection Off-wrist detection, sleep period detection, WASO
condor_pipeline.algorithms Cole-Kripke and vendor sleep scoring algorithms
condor_pipeline.viz Actogram plotting

Quick usage

from condor_pipeline.pipeline import SleepPipeline

# Single file
pipe = SleepPipeline("data/raw/subject_01.txt", device="acttrust")
result = pipe.run()
print(result.nights)
result.plot()

# Batch
results = SleepPipeline.batch("data/raw/", device="acttrust", pattern="*.txt")
for r in results:
    print(r.subject_id, r.nights)

To enable editable install, set INSTALL_PACKAGE=true in .env before building.

Licence

The vendor algorithms bundled in condor_pipeline/algorithms/vendor/ originate from Condor-Instruments/actigraphy-tutorials-sample and are copyright © Condor Instruments. Please refer to their repository for licensing terms before redistribution.

The remaining condor_pipeline wrapper code is copyright © Circadia Lab — Lucas França & Mario Leocadio-Miguel, released under the MIT Licence.

📦 Python Dependencies

Core environment

Package Version Purpose
Python 3.11 Base interpreter
JupyterLab 4.5.6 Notebook interface
notebook 7.5.5 Classic notebook support

Scientific stack

Package Version Purpose
numpy 1.26.4 Numerical computing
scipy 1.14.1 Scientific algorithms
pandas 2.2.2 Tabular data
matplotlib 3.9.2 Plotting
seaborn 0.13.2 Statistical visualisation
scikit-learn 1.5.2 Machine learning
statsmodels 0.14.6 Statistical modelling
plotly 4.11.0 Interactive plots

Chronobiology & sleep

Package Version Purpose
pyActigraphy GitHub (artvalencio) Actigraphy analysis, REST-activity, cosinor, SSA
mne 1.8.0 EEG/MEG processing
yasa 0.6.5 Automatic sleep staging
EntropyHub 2.0 Entropy-based time series methods

pyActigraphy dependencies

Package Version
joblib 1.5.3
lmfit 1.3.4
numba 0.65.1
pyexcel 0.7.4
pyexcel-ods3 0.6.1
pyexcel-xlsx 0.6.1
spm1d 0.4.53
stochastic 0.6.0
lxml 6.1.0

📦 R Dependencies

Base image

Package Purpose
jmgirard/rstudio2u r2u + RStudio Server, ARM64-native, binary apt installs

Included packages

ggplot2 extensions — ggpubr, ggrepel, ggridges, patchwork, cowplot, scales, viridis, RColorBrewer

Stats — lme4, lmerTest, emmeans, MuMIn, effectsize, performance, parameters, see

Bayesian (no-stan / full profiles) — bayesplot, tidybayes, brms*, rstanarm*

Sleep & circadian — GGIR, ActCR, circacompare, cosinor, cosinor2, lunaR**

* full profile only — ** no-stan and full profiles only

👥 Authors

Role Names
Principal Investigators Lucas França, Mario Leocadio-Miguel
Development Lucas França, Mario Leocadio-Miguel

🤝 Related Tools

  • 🌙 SleepDiaries — cross-platform sleep diary app built for research
  • 📋 sleep-questionnaires — validated sleep questionnaire instruments (PSQI, ESS, ISI, MEQ, and more)
  • 🔬 circadia-bio — the Circadia Lab GitHub organisation

📄 Licence

Copyright © Circadia Lab — Lucas França & Mario Leocadio-Miguel

Released under the MIT License.

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages