Update README_space.md

README_space.md

@@ -1,126 +1,133 @@
-# 🧬 Health Intelligence Platform
-
-Interactive Streamlit app for exploring digital wellbeing and mental health risk as a live, data-driven system — from population trends to individual what-if scenarios.
-
-This Space runs directly in the browser. No real user records are loaded; the app generates its own population data at runtime for safe experimentation.
-
----
-
-## 📌 What this app does
-
-The Health Intelligence Platform lets you:
-
-- Monitor digital wellbeing and mental health risk at population level  
-- Explore behavioural patterns (screen time, sleep, stress, social usage, activity)  
-- Run interactive what-if scenarios on a single profile  
-- Generate clinical-style summaries for high-risk cohorts  
-
-Use it as a tool to think about risk, behaviour, and intervention design — **not** as a clinical decision system.
-
----
-
-## 🧭 How to use this Space
-
-The app is organised into several tabs:
-
-### 1. Executive Dashboard
-
-High-level overview of the current cohort:
-
-- Core KPIs: active users, high-risk share, model AUC, behavioural averages  
-- Risk score distribution with a configurable threshold slider in the sidebar  
-- Time trends for screen time, stress, wellbeing, sleep, engagement, and high-risk counts  
-- Demographic views by age group, gender, location, occupation  
-
-### 2. Risk Analytics
-
-Deeper look at the risk engine:
-
-- Correlation heatmap for key drivers (screen time, sleep, stress, anxiety, depression, wellbeing, mood, energy, social support, loneliness, risk score)  
-- Risk distributions by segment (Low / Moderate / High)  
-- Confusion matrix and ROC curve with AUC  
-- Conceptual feature importance and focused scatter plots (screen vs sleep, stress vs wellbeing)  
-
-### 3. Behavioural Insights
-
-Digital habits and lifestyle patterns:
-
-- 24-hour curves for screen time, notifications, stress, and energy  
-- App usage mix (social, work/study, gaming, entertainment, other)  
-- Digital interaction metrics across risk segments (unlocks, notifications)  
-- Physical vs digital balance and quick health indicators (sleep deficit, high stress, inactivity)  
-
-### 4. Scenario Simulator
-
-Interactive what-if engine for a single profile:
-
-- Adjust digital, health, physical, and social variables using sliders  
-- See risk score, risk segment, intervention flag, and population percentile update in real time  
-- Compare the scenario to population averages and view a radar profile  
-- Apply pre-defined intervention bundles (digital reset, sleep protocol, holistic plan) with generated recommendations  
-
-### 5. Clinical Reports
-
-Structured view of the highest-risk users:
-
-- Ranked list of top-risk users with demographics and key indicators  
-- One-click CSV export of the high-risk cohort  
-- Summary tables for risk segments, mental health metrics, and behavioural metrics  
-
-Use the sidebar to:
-
-- Set the risk threshold  
-- Filter by risk segment, age group, gender, occupation  
-- Filter by screen time and stress ranges  
-- Toggle AI insights and analytics, and export data (CSV / JSON)  
-
----
-
-## 🧠 Data & Risk Engine
-
-The app builds a rich, internally generated dataset that includes:
-
-- **Demographics:** `age`, `age_group`, `gender`, `location`, `occupation`  
-- **Digital behaviour:** `screen_hours`, `phone_unlocks`, `notifications`, `social_minutes`, `gaming_minutes`, `work_minutes`  
-- **Lifestyle & health:** `exercise_minutes`, `outdoor_time`, `steps_daily`, `bmi`, `heart_rate`  
-- **Mental health:** `stress`, `anxiety`, `depression`, `focus`, `wellbeing`, `mood`, `energy`  
-- **Social context:** `social_support`, `loneliness`  
-- **Engagement:** `last_active`, `engagement_score`  
-
-Risk is computed using a logistic risk function over weighted combinations of:
-
-- Digital exposure and intensity  
-- Stress, anxiety, depression, wellbeing, mood, energy  
-- Sleep, activity, outdoor time  
-- Social support and loneliness  
-
-From this, the app derives:
-
-- `risk_score` in (0, 1)  
-- `high_risk` label  
-- `risk_segment ∈ {Low, Moderate, High}`  
-
-The emphasis is on interpretability and controllable experimentation in digital wellbeing analytics. It does not replace professional clinical judgement.
-
----
-
-## 🧩 Tech Stack
-
-- **Python**  
-- **Streamlit** (app framework)  
-- **NumPy** (numerical computations)  
-- **pandas** (data manipulation)  
-- **Plotly** (interactive charts)  
-- **scikit-learn metrics** (AUC, PR, Brier score, ROC, confusion matrix)  
-
----
-
-## 🖥 Run locally 
-
-If you want to run the same app outside Hugging Face Spaces:
-
-```bash
-git clone https://github.com/tarekmasryo/health-intelligence-platform.git
-cd health-intelligence-platform
-pip install -r requirements.txt
-streamlit run app.py
+
+
+# 🧬 Health Intelligence Platform
+
+Interactive Streamlit app for exploring digital wellbeing and mental health risk as a live, data-driven system — from population trends to individual what-if scenarios.
+
+This Space runs directly in the browser. No real user records are loaded; the app generates its own population data at runtime for safe experimentation.
+
+[![Streamlit](https://img.shields.io/badge/Powered%20by-Streamlit-FF4B4B)](https://streamlit.io/)\
+[![Data License: CC BY-NC 4.0](https://img.shields.io/badge/Data%20License-CC%20BY--NC%204.0-lightgrey.svg)](DATA_LICENSE)\
+[![Made with ❤️ by Tarek Masryo](https://img.shields.io/badge/Made%20by-Tarek%20Masryo-blue)](https://github.com/tarekmasryo)
+
+
+---
+
+## 📌 What this app does
+
+The Health Intelligence Platform lets you:
+
+- Monitor digital wellbeing and mental health risk at population level  
+- Explore behavioural patterns (screen time, sleep, stress, social usage, activity)  
+- Run interactive what-if scenarios on a single profile  
+- Generate clinical-style summaries for high-risk cohorts  
+
+Use it as a tool to think about risk, behaviour, and intervention design — **not** as a clinical decision system.
+
+---
+
+## 🧭 How to use this Space
+
+The app is organised into several tabs:
+
+### 1. Executive Dashboard
+
+High-level overview of the current cohort:
+
+- Core KPIs: active users, high-risk share, model AUC, behavioural averages  
+- Risk score distribution with a configurable threshold slider in the sidebar  
+- Time trends for screen time, stress, wellbeing, sleep, engagement, and high-risk counts  
+- Demographic views by age group, gender, location, occupation  
+
+### 2. Risk Analytics
+
+Deeper look at the risk engine:
+
+- Correlation heatmap for key drivers (screen time, sleep, stress, anxiety, depression, wellbeing, mood, energy, social support, loneliness, risk score)  
+- Risk distributions by segment (Low / Moderate / High)  
+- Confusion matrix and ROC curve with AUC  
+- Conceptual feature importance and focused scatter plots (screen vs sleep, stress vs wellbeing)  
+
+### 3. Behavioural Insights
+
+Digital habits and lifestyle patterns:
+
+- 24-hour curves for screen time, notifications, stress, and energy  
+- App usage mix (social, work/study, gaming, entertainment, other)  
+- Digital interaction metrics across risk segments (unlocks, notifications)  
+- Physical vs digital balance and quick health indicators (sleep deficit, high stress, inactivity)  
+
+### 4. Scenario Simulator
+
+Interactive what-if engine for a single profile:
+
+- Adjust digital, health, physical, and social variables using sliders  
+- See risk score, risk segment, intervention flag, and population percentile update in real time  
+- Compare the scenario to population averages and view a radar profile  
+- Apply pre-defined intervention bundles (digital reset, sleep protocol, holistic plan) with generated recommendations  
+
+### 5. Clinical Reports
+
+Structured view of the highest-risk users:
+
+- Ranked list of top-risk users with demographics and key indicators  
+- One-click CSV export of the high-risk cohort  
+- Summary tables for risk segments, mental health metrics, and behavioural metrics  
+
+Use the sidebar to:
+
+- Set the risk threshold  
+- Filter by risk segment, age group, gender, occupation  
+- Filter by screen time and stress ranges  
+- Toggle AI insights and analytics, and export data (CSV / JSON)  
+
+---
+
+## 🧠 Data & Risk Engine
+
+The app builds a rich, internally generated dataset that includes:
+
+- **Demographics:** `age`, `age_group`, `gender`, `location`, `occupation`  
+- **Digital behaviour:** `screen_hours`, `phone_unlocks`, `notifications`, `social_minutes`, `gaming_minutes`, `work_minutes`  
+- **Lifestyle & health:** `exercise_minutes`, `outdoor_time`, `steps_daily`, `bmi`, `heart_rate`  
+- **Mental health:** `stress`, `anxiety`, `depression`, `focus`, `wellbeing`, `mood`, `energy`  
+- **Social context:** `social_support`, `loneliness`  
+- **Engagement:** `last_active`, `engagement_score`  
+
+Risk is computed using a logistic risk function over weighted combinations of:
+
+- Digital exposure and intensity  
+- Stress, anxiety, depression, wellbeing, mood, energy  
+- Sleep, activity, outdoor time  
+- Social support and loneliness  
+
+From this, the app derives:
+
+- `risk_score` in (0, 1)  
+- `high_risk` label  
+- `risk_segment ∈ {Low, Moderate, High}`  
+
+The emphasis is on interpretability and controllable experimentation in digital wellbeing analytics. It does not replace professional clinical judgement.
+
+---
+
+## 🧩 Tech Stack
+
+- **Python**  
+- **Streamlit** (app framework)  
+- **NumPy** (numerical computations)  
+- **pandas** (data manipulation)  
+- **Plotly** (interactive charts)  
+- **scikit-learn metrics** (AUC, PR, Brier score, ROC, confusion matrix)  
+
+---
+
+## 🖥 Run locally 
+
+If you want to run the same app outside Hugging Face Spaces:
+
+```bash
+git clone https://github.com/tarekmasryo/health-intelligence-platform.git
+cd health-intelligence-platform
+pip install -r requirements.txt
+streamlit run app.py