From Correlation to Causation: A Reproducible Framework for Digital Well-Being and Mental-Health Burden

From Correlation to Causation: A Reproducible Framework for Digital Well-Being and Mental-Health Burden Description This repository presents a reproducible, research-grade causal inference framework designed to move beyond correlational analysis toward causal reasoning in the study of digital well-being and mental-health burden. The framework is intended for methodological research, benchmarking, and education, rather than clinical diagnosis or policy deployment. Methods (Framework Construction) The framework is built around a Structural Causal Model (SCM) that explicitly encodes assumed causal relationships among modern lifestyle and environmental factors relevant to mental health. Data are generated synthetically within the pipeline using predefined structural equations that incorporate: bounded and ordinal-like variables (to reflect realistic response behavior), nonlinear effects and interactions, heteroskedastic noise, mediating variables (e.g., rumination, sleep variability), and missingness mechanisms linked to stress and socioeconomic context. Because the data-generating process is known, the framework provides access to true counterfactual outcomes and ground-truth Average Treatment Effects (ATEs). Causal effects are estimated using three complementary estimators: outcome regression (G-formula), inverse probability weighting (IPW), and doubly robust Augmented IPW (AIPW). The pipeline further includes identifiability diagnostics (overlap and positivity checks), sensitivity analysis to unmeasured confounding, distribution-shift robustness tests, and distribution-free uncertainty quantification via split conformal prediction intervals. All analyses are CPU-efficient and fully reproducible. Outputs Each execution produces a complete, auditable causal analysis record, including: causal effect estimates (True ATE, G-formula, IPW, AIPW) saved as Excel tables, overlap and positivity diagnostics, sensitivity curves quantifying robustness to hidden confounding, shift-stability analyses under simulated population and measurement changes, conformal prediction interval statistics and coverage visualizations, run metadata, a model card, and a dataset card documenting assumptions and scope. All outputs are human-readable and designed for inspection, reuse, and extension. Scope This framework is broadly applicable to methodological research on causal inference and ethical machine learning, particularly in domains where real-world data are noisy, biased, or difficult to access. Its scope includes: benchmarking causal estimators under known ground truth, studying identifiability and overlap limitations, analyzing estimator robustness under confounding and distribution shift, evaluating uncertainty quantification methods, supporting reproducible teaching and demonstration of causal concepts, serving as a foundation for extending SCM-based simulation studies. While the motivating domain is digital well-being and mental-health burden, the framework is domain-agnostic and can be adapted to other applied causal research settings by modifying the SCM. Limitations All data are synthetic and do not represent real individuals, populations, or prevalence. The causal structure reflects modeling assumptions rather than empirical truth. Results should therefore be interpreted as methodological demonstrations, not as evidence about real-world mental-health outcomes. Directions for Use Researchers and educators may use this framework to: benchmark and compare causal estimators, explore failure modes due to confounding or lack of overlap, test robustness under realistic data imperfections, teach causal inference concepts with fully reproducible examples, extend the SCM or estimators for new methodological research. This framework is not intended for clinical, diagnostic, or policy decision-making.