Theory-Constrained Machine Learning for Symptom-Level Mental-Health Modeling

Title Theory-Constrained Machine Learning for Symptom-Level Mental-Health Modeling Introduction This repository presents a reproducible, research-grade modeling framework for analyzing mental-health symptom severity using interpretable and theory-constrained machine-learning methods. The project addresses a central limitation in applied mental-health ML: unconstrained predictive models can achieve strong performance while violating basic psychological assumptions and obscuring failure modes. To mitigate this, the framework integrates psychometric theory directly into the learning objective. Rather than treating questionnaire responses as arbitrary features, the model operates at the symptom-item level using validated clinical instruments (PHQ-9, GAD-7, PCL-5) and explicitly enforces monotonic behavior, ensuring that higher symptom endorsement cannot reduce predicted severity. The emphasis is on transparent optimization, interpretability, stability, and reproducibility, not on clinical diagnosis or deployment. Methods Model Construction The core task is regression from item-level symptom responses to a continuous severity index. The model minimizes squared-error loss subject to monotonic inequality constraints, such that predicted severity is non-decreasing with respect to each symptom item. These constraints explicitly encode psychological theory into the hypothesis space and prevent counter-theoretical model behavior. The learning algorithm uses gradient-boosted decision trees with monotonic constraints applied to all symptom-item features. This approach preserves nonlinear expressiveness while maintaining interpretability and theoretical validity. Training is CPU-efficient, avoiding deep learning architectures, GPU dependence, or large hyperparameter searches. Evaluation Strategy To ensure reliability and avoid single-run artifacts, the framework includes: repeated training across multiple random seeds, performance evaluation using RMSE, MAE, and R², benchmarking against regularized linear baselines, residual diagnostics and predicted-versus-true comparisons. Interpretability and Constraint Auditing Interpretability is treated as a measurable property rather than an assumption. The pipeline computes: gain-based feature importance, permutation importance independently for each seed, explicit monotonicity audits, where each symptom item is varied counterfactually while holding others fixed to quantify constraint-violation rates. Psychometric and Data Diagnostics To maintain measurement awareness, the framework includes: internal consistency checks via Cronbach’s alpha for PHQ-9, GAD-7, and PCL-5, dataset profiling and summary statistics, run metadata documenting configuration and execution context. All experiments are saved as versioned, self-contained run artifacts. Outputs Each execution produces a complete, auditable modeling record, including: per-seed performance metrics (RMSE, MAE, R²), stability visualization via RMSE-across-seeds plots, trained model files for each seed, feature-importance and permutation-importance tables and figures, monotonicity audit reports documenting constraint adherence, residual distribution and predicted-versus-true diagnostic plots, data-profile summaries and run metadata. These outputs collectively demonstrate that the constrained model is stable across runs, interpretable at the symptom level, and consistent with theoretical expectations, while maintaining competitive predictive performance relative to unconstrained baselines. Scope This artifact is intended for methodological research, benchmarking, and education in interpretable machine learning and computational mental-health research. It is suitable for: studying the effects of theoretical constraints on ML behavior, evaluating interpretability and stability in symptom-level models, supporting reproducible demonstrations of ethical modeling practices. The framework is not designed for real-world deployment or clinical use. Limitations All modeling results depend on the structure of the input data and the assumptions encoded by the constraints. The framework does not claim causal interpretation, diagnostic validity, or generalizability to real clinical populations. Results should be interpreted as methodological demonstrations, not empirical evidence about mental-health prevalence or individual outcomes. Ethics This project is explicitly non-diagnostic and non-clinical. It does not provide treatment recommendations or individual-level mental-health predictions. Ethical safeguards include: avoidance of black-box modeling, explicit constraint enforcement aligned with theory, transparent reporting of assumptions and limitations, full reproducibility of results. The framework is intended for responsible research and educational use only.