Statistical Modelling · Bayesian Inference · Causal Inference · LLM Integration
Most productivity tools tell you what you did. This system tells you why your output varies — using causal inference, not correlation.
This is a research-grade, end-to-end data science project that identifies the causal drivers of knowledge-worker productivity through a rigorous statistical pipeline. It goes far beyond dashboards and regression — it builds a full causal model with:
- A Directed Acyclic Graph (DAG) specifying the causal structure, including stress, caffeine, and motivation as first-class nodes
- Double/Debiased ML (Chernozhukov et al., 2018) to estimate causal effects without parametric model bias
- Mediation analysis decomposing total effects into direct and indirect pathways
- Bayesian hierarchical modelling with informative, literature-calibrated priors for full uncertainty quantification
- Counterfactual simulation implementing Pearl's do-operator across the full structural causal model
- A research-primed LLM layer that narrates every finding using only verified peer-reviewed concepts
Every component is anchored in published behavioral science, econometrics, and Bayesian statistics. No fabricated citations. No generic advice.
# Clone and install
git clone https://github.com/your-username/causal-productivity-intelligence.git
cd causal-productivity-intelligence
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Run the full pipeline (approx. 27 seconds without Bayesian MCMC)
python run_all.py --skip-bayes
# Launch the interactive dashboard
cp .env.example .env # add your ANTHROPIC_API_KEY
streamlit run app.pyEvery modelling decision is grounded in peer-reviewed research.
| Finding | Source | Implementation |
|---|---|---|
| Sleep deprivation at 6h/night equals 2 nights total loss | Van Dongen et al. (2003, SLEEP) | Non-linear sleep_performance_curve() |
| Sleep and circadian phase interact multiplicatively | Dijk & Czeisler (1995, J Neuroscience) | sleep × start_hour interaction term |
| Deep/deliberate work requires elite cognitive resources | Ericsson et al. (1993, Psych Review) | task_type × sleep interaction |
| Post-lunch dip is a genuine circadian phenomenon | Monk (2005, Occup Env Medicine) | circadian_alertness() trough at 14:00 |
| Caffeine 6h before bed reduces sleep by ~1 hour | Drake et al. (2013, J Clin Sleep Med) | caffeine_sleep_disruption() |
| Motivation mediates sleep → work performance | Deci & Ryan (2000); Baard et al. (2004) | Mediation analysis; motivation as DAG node |
| Stress elevates cortisol, impairing memory consolidation | Cohen et al. (1983); Salleh (2008) | Stress as hub confounder/mediator |
| Breaks aligned to 90-min ultradian rhythm optimise output | Kleitman BRAC; Lorist et al. (2005) | fatigue_curve() with break moderation |
| Backdoor criterion identifies adjustment sets | Pearl (2009, Causality) | DAG specification + adjustment sets |
| Neyman-orthogonal estimation avoids regularisation bias | Chernozhukov et al. (2018, Econometrica) | Double ML with GradientBoosting nuisance |
| Sensitivity to unmeasured confounders is quantifiable | Rosenbaum (2002) | Gamma-bounds sensitivity analysis |
| Posterior predictive checks validate model adequacy | Gelman et al. (2013, BDA3) | PPC with 100 posterior draws |
causal-productivity-intelligence/
│
├── src/
│ ├── data_generation.py Research-grounded synthetic DGP (v2 enriched DAG)
│ ├── regression_model.py OLS with interaction effects, HC3 SEs, AMEs
│ ├── causal_analysis.py DAG · IPW · Double ML · Mediation · Sensitivity
│ ├── bayesian_model.py PyMC / MH-MCMC · Posteriors · PPC
│ ├── simulation.py Counterfactual engine (Pearl do-operator)
│ └── llm_insights.py Research-primed LLM narration (Anthropic API)
│
├── notebooks/
│ └── exploration.ipynb 32-cell EDA · 9 sections · 14 publication-quality plots
│
├── data/
│ ├── productivity_data.csv Generated dataset (1,200 observations, 19 variables)
│ └── outputs/ 24 model output plots + posterior summaries
│
├── .github/
│ └── workflows/ci.yml GitHub Actions: lint · test · notebook execution
│
├── app.py Streamlit dashboard (4 tabs, fully interactive)
├── run_all.py Master pipeline runner with --skip-bayes flag
├── pyproject.toml Package metadata, Black/isort/pytest config
├── requirements.txt
├── .env.example
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE
[chronotype] ─────────────────────────────────────────────────────┐
│ │
day_of_week ──► stress_level ──► caffeine_intake ────────────────►│
│ │ ▼
screen_time ─────────┘ caffeine_hour ──► sleep_hours ──► productivity_score
│ │ ▲
└────────────────────────► motivation_score ──┤
│ │
task_type ───────────┘
Identification challenges introduced by the enriched DAG:
motivation_scoreandtask_typeare mediators — conditioning on them when estimating the sleep effect blocks the indirect path and underestimates the total effect[chronotype]is an unmeasured confounder — we quantify sensitivity to it via Rosenbaum Gamma-boundscaffeine_intakesits in a cross-day feedback loop — treated as a within-day observed variable with adjustment
| Predictor | β | 95% CI | p |
|---|---|---|---|
| Sleep hours (centered at 7h) | +1.47 | [+1.10, +1.80] | < 0.001 |
| Deep work (vs shallow) | +7.16 | [+6.46, +7.85] | < 0.001 |
| Deep × Sleep interaction | +2.31 | [+1.70, +2.91] | < 0.001 |
| Log hours worked | −1.11 | [−1.68, −0.55] | < 0.001 |
| Screen time (normalised) | −1.36 | [−2.71, 0.00] | 0.050 |
R² = 0.436, Adj. R² = 0.429, HC3 robust standard errors
| Estimand | θ̂ | 95% CI | p |
|---|---|---|---|
| Total Effect of sleep (1 hr) | +1.89 pts | [+1.52, +2.27] | < 0.001 |
| Direct Effect (excl. motivation) | +1.66 pts | [+1.32, +2.00] | < 0.001 |
| Indirect via motivation (NIE) | +0.56 pts | [+0.34, +0.80] | < 0.001 |
Proportion mediated through motivation (SDT pathway): 26.6%
| Parameter | Posterior Mean | 95% CrI | P(β > 0) |
|---|---|---|---|
| beta_sleep_hours | +2.58 | [+2.24, +2.83] | 100% |
| beta_task_deep | +4.33 | [+4.03, +4.71] | 100% |
| beta_deep×sleep | +1.01 | [+0.82, +1.25] | 100% |
| beta_start_hour | −2.05 | [−2.37, −1.76] | 0% |
MH-MCMC: 15,000 iterations, burn-in = 33%, acceptance rate 36% (textbook optimal)
| Intervention | Δ Productivity | 90% CI |
|---|---|---|
| Sleep +1h → 7h | +3.5 pts | [+2.9, +4.0] |
| Sleep +2h → 8h | +6.9 pts | [+5.8, +8.0] |
| Switch to deep work | +5.2 pts | [+3.5, +6.9] |
| Move coffee to 9AM | +0.0 pts | (next-day effect) |
| Full behavioural package | +17.3 pts | [+15.2, +19.5] |
Four interactive tabs:
| Tab | Content |
|---|---|
| 📊 Profile & Prediction | Sidebar sliders → real-time prediction with predictive distribution and 3 dose-response curves |
| 🔮 Counterfactual Planner | Build custom interventions → causal lift with 90% uncertainty bands |
| 📈 Statistical Deep Dive | Data explorer · correlation matrix · enriched DAG · Bayesian posteriors |
| 🤖 AI Research Insights | Generate research-backed narration from 5 insight templates |
notebooks/exploration.ipynb — 32 cells, fully executed, 9 annotated sections. Every finding is linked to the modelling decision it informs.
To open:
jupyter notebook notebooks/exploration.ipynb- Synthetic data — the DGP reflects literature but real data will contain unmeasured confounders, measurement error, and more complex feedback loops
- SUTVA — consecutive-day fatigue accumulation may violate the Stable Unit Treatment Value Assumption
- Single circadian curve — chronotype heterogeneity (larks vs owls) is partially captured by the latent
[chronotype]variable but not fully modelled - Rosenbaum Gamma = 1.25 — a moderate sensitivity result; real chronotype data would strengthen identification considerably
- LLM knowledge base — the insight layer is limited to 12 pre-loaded research concepts; do not treat outputs as clinical advice
- Population scope — findings are calibrated for knowledge workers; different optimal profiles likely exist for other work types
Python 3.10 or higher required.
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# For Bayesian inference with PyMC (optional, falls back to scipy MH)
pip install pymc arviz
# For LLM insights
cp .env.example .env
# Add: ANTHROPIC_API_KEY=sk-ant-...# Full pipeline
python run_all.py
# Skip MCMC (faster)
python run_all.py --skip-bayes
# Individual modules
python src/data_generation.py
python src/regression_model.py
python src/causal_analysis.py
python src/bayesian_model.py
python src/simulation.py
# Dashboard
streamlit run app.py
# Tests
pytest tests/ -vPlease read CONTRIBUTING.md first. Key areas of interest:
- Real-world data connectors (Oura Ring, Toggl, RescueTime APIs)
- Instrumental variable estimation (IV using weather/commute as instruments)
- Causal Forest (Wager & Athey, 2018) for continuous CATE estimation
- PyMC v5 hierarchical model with individual-level random effects
- Chronotype-stratified analysis using MEQ scores
- Baard et al. (2004). Journal of Applied Psychology, 89(4), 781.
- Chernozhukov et al. (2018). Double/debiased ML. Econometrica, 86(3), 451-475.
- Cohen, Kamarck & Mermelstein (1983). J Health and Social Behavior, 24(4), 385.
- Deci & Ryan (2000). Self-determination theory. Psychological Inquiry, 11(4), 227-268.
- Dijk & Czeisler (1995). Journal of Neuroscience, 15(5), 3526-3538.
- Drake et al. (2013). Journal of Clinical Sleep Medicine, 9(11), 1195-1200.
- Ericsson, Krampe & Tesch-Römer (1993). Psychological Review, 100(3), 363-406.
- Gelman et al. (2013). Bayesian Data Analysis (3rd ed.). CRC Press.
- Kleitman (1982). Basic rest-activity cycle. Experientia, 38, 1509-1513.
- Lieberman et al. (2002). Psychopharmacology, 164(3), 250-261.
- Lorist et al. (2005). Neuropsychologia, 43(9), 1400-1412.
- MacKinnon & White (1985). Journal of Econometrics, 29(3), 305-325.
- Monk (2005). Occupational and Environmental Medicine, 62(1), 1-8.
- Newport (2016). Deep Work. Grand Central Publishing.
- Pearl (2009). Causality: Models, Reasoning and Inference. Cambridge University Press.
- Preacher & Hayes (2008). Behavior Research Methods, 40(3), 879-891.
- Rosenbaum (2002). Observational Studies (2nd ed.). Springer.
- Rubin (1974). Journal of Educational Psychology, 66(5), 688-701.
- Salleh (2008). AMSJ, 3(2), 9-15.
- Van Dongen et al. (2003). SLEEP, 26(2), 117-126.
- Walker (2017). Why We Sleep. Scribner.
MIT License. See LICENSE for details.
Built with statistical rigour. Interpreted with care.