Update README.md

README.md

@@ -11,83 +11,242 @@ license: mit
 
 # CEAR – Cultural Exposure & Algorithmic Risk Analyzer
 
-CEAR is an **analytic, rule-based model** and interactive Gradio app that helps you reason about your social media habits along three axes:
+CEAR is a transparent, rule-based model and Hugging Face Space that helps users understand their social media habits through three interpretable metrics:
 
-- **Cultural Connectedness (C-Score)** – how much “trend exposure” your habits plausibly give you  
-- **Algorithmic Risk (A-Risk)** – how much raw attention you hand over to algorithmic feeds  
-- **Diversity Index (D-Index)** – how many platforms you meaningfully use, adjusted for concentration  
+* **Cultural Connectedness (C-Score)** – approximate trend exposure
+* **Algorithmic Risk (A-Risk)** – attention concentration in algorithm-driven feeds
+* **Diversity Index (D-Index)** – distribution of time across platforms
 
-This is **not** a predictive deep learning model. It is a transparent scoring scheme designed to surface patterns in how you allocate attention across platforms.
+The project combines an analytic scoring engine with a clean Gradio interface. It does not use machine learning but functions as an interpretable behavioral analysis model.
 
-The live app runs here:  
-> `https://huggingface.co/spaces/<your-username>/CEAR`
+---
+
+## 🚀 Live Demo
+
+Use CEAR directly in your browser:
+
+**Hugging Face Space:** `https://huggingface.co/spaces/<your-username>/CEAR`
+
+---
+
+## 📦 Project Structure
+
+```
+├── app.py                   # Gradio interface and interpretation logic
+├── cear_model.py           # Core scoring engine (C/A/D + efficiency)
+├── platform_weights.json   # Hand-tuned theoretical platform weights
+├── requirements.txt        # Dependencies
+└── README.md               # This file
+```
+
+---
+
+## 🎯 Purpose
+
+CEAR serves two goals:
+
+1. Provide an **interpretable framework** for analyzing social media behavior.
+2. Demonstrate a **fully-documented model card**, Gradio deployment, and rule-based transform suitable for academic or instructional settings.
+
+It is ideal for:
+
+* Students learning model documentation
+* Researchers exploring rule-based analytics
+* Users who want insight into their social media patterns
+
+---
+
+## 📥 Inputs
+
+CEAR accepts values for **7 platform buckets**:
+
+* TikTok
+* Instagram
+* YouTube
+* Twitter/X
+* Reddit
+* Facebook
+* Other
+
+For each platform, the user inputs:
+
+* **Minutes per week**
+* **Variety score** (0–10)
+
+Global self-reports:
+
+* **Feed satisfaction** (0–10)
+* **FOMO / Out-of-the-loop feeling** (0–10)
+
+### Input Validation Rules
+
+* Platforms with **0 minutes** are excluded from calculations.
+* Variety > 0 while minutes = 0 triggers a **warning** and is ignored.
+* Negative values are treated as zero.
+
+---
+
+## 🧮 Model Logic
+
+CEAR is a rule-based model driven by theoretical platform weights.
+
+### Platform Weights
+
+Each platform has:
+
+* `W_C` – Cultural Connectedness Weight
+* `W_A` – Algorithmic Risk Weight
+
+Defined in `platform_weights.json`.
+
+### Score Calculations
+
+#### 1. **C-Score (Cultural Connectedness)**
+
+Uses a log transform to encode diminishing returns:
+
+```
+C_contrib = W_C * log10(minutes + 1)
+```
+
+#### 2. **A-Risk (Algorithmic Risk)**
+
+Linear with respect to time:
+
+```
+A_contrib = W_A * minutes
+```
+
+#### 3. **D-Index (Platform Diversity)**
+
+Based on the inverse Herfindahl index:
+
+```
+s_i = minutes_i / total_minutes
+D_Index = 1 / sum(s_i^2)
+```
+
+#### 4. **Per-Platform Cultural Efficiency (0–100)**
+
+```
+eff_raw = C_contrib / minutes
+normalized = eff_raw / max(eff_raw) * 100
+```
+
+#### 5. **Average Variety (Weighted)**
+
+```
+Avg_Variety = mean(variety_score, weighted by minutes)
+```
+
+### Interpretation Logic
+
+* Satisfaction and FOMO do **not** influence the numeric scores.
+* Instead, they shape the **narrative summary**.
+
+---
+
+## 🧩 Output Sections
+
+The app produces three final outputs:
+
+### 1. **CEAR Analysis Summary**
+
+Includes:
+
+* C-Score
+* A-Risk
+* D-Index
+* Average Variety
+* Self-report reflections
+* Warnings for invalid input patterns
+
+### 2. **Interpretation Narrative**
+
+A human-readable explanation linking:
+
+* Platform mix
+* Variety
+* Satisfaction
+* FOMO
+* Risk and connectedness profiles
+
+### 3. **Platform Efficiency Breakdown**
+
+Both as:
+
+* A ranked markdown list (easy to read)
+* A numeric DataFrame (for analysis)
 
 ---
 
-## 👤 What the app does
+## 🧪 Validation
 
-Given your **weekly screen time per platform**, a **per-platform variety rating**, and two **global self-reports** (satisfaction and FOMO), CEAR:
+Since CEAR is deterministic, validation focuses on correctness:
 
-1. Builds a structured profile of your social media usage.  
-2. Computes three core scores:
-   - **C-Score** – log-scaled, weight-adjusted trend exposure  
-   - **A-Risk** – linear, weight-adjusted attention risk  
-   - **D-Index** – inverse Herfindahl index over your time share  
-3. Ranks platforms by **Cultural Efficiency** (0–100):  
-   > “How much cultural exposure you get per minute” relative to your own most efficient platform.  
-4. Generates a **plain-language interpretation** tying all of this back to your satisfaction and FOMO.
+* Unit tests confirm expected behavior for high-concentration vs balanced usage.
+* Manual tests confirm variety weighting, reset logic, and warnings.
+* The scoring formulas are transparent and reproducible.
 
-It does **not** claim to tell you what is “objectively healthy” or what you “must” do. It gives you a structured mirror to look at your own media diet.
+---
+
+## ⚠️ Limitations
+
+CEAR is **not** a predictive model.
+
+* It does not infer real cultural exposure.
+* It cannot evaluate actual content.
+* Weights reflect reasonable theoretical assumptions, not empirical fitting.
+* It does not diagnose mental health or prescribe usage patterns.
+
+The model is best used for **reflection**, **education**, and **exploration**.
 
 ---
 
-## 🧮 Model description
+## 🔧 Running Locally
 
-### Inputs
+You can run the app locally:
 
-The app currently supports 7 platform buckets:
+```bash
+pip install -r requirements.txt
+python app.py
+```
 
-- TikTok  
-- Instagram  
-- YouTube  
-- Twitter / X  
-- Reddit  
-- Facebook  
-- Other (anything else you use)
+Or import the model:
 
-For each platform, you provide:
+```python
+from cear_model import CEARModel
+import pandas as pd
 
-- `minutes_per_week` (number)  
-- `variety_score` (slider, 0–10)
+model = CEARModel()
+df = pd.DataFrame([
+    {"platform_name": "tiktok", "minutes_per_week": 300, "variety_score": 4},
+])
+print(model.calculate_scores(df, satisfaction=6, fomo=4))
+```
 
-Global self-report sliders:
+---
+
+## 📜 License
 
-- `feed_satisfaction` (0–10) – “How happy are you with your feed overall?”  
-- `fomo_level` (0–10) – “How out of the loop do you feel about online culture?”
+MIT License
+
+---
 
-### Input rules and validation
+## 🙌 Acknowledgments
 
-- **Minutes must be ≥ 0.** Negative values are treated as 0.  
-- If `minutes_per_week == 0` for a platform:
-  - That platform is **excluded** from the model calculations.  
-  - Its variety value is **ignored**.  
-- If you set `variety_score > 0` while `minutes_per_week == 0`:
-  - The app **ignores** that variety score.
-  - You get a ⚠️ **warning line** listing affected platforms in the summary.
+This project was built to demonstrate:
 
-This keeps the math honest: variety only matters where you actually spend time.
+* Transparent model design
+* Clear model documentation
+* Proper Hugging Face Space structure
+* User-oriented interpretability
 
-### Internals – how the scores are computed
+Feel free to fork and extend with:
 
-Platform weights live in `platform_weights.json` and look like:
+* Empirical weights
+* Trend detection
+* Behavioral clustering
+* Recommendation strategies
 
-```json
-{
-  "tiktok":   {"W_C": 0.95, "W_A": 0.90},
-  "instagram":{"W_C": 0.85, "W_A": 0.85},
-  "youtube":  {"W_C": 0.70, "W_A": 0.75},
-  "twitter":  {"W_C": 0.80, "W_A": 0.70},
-  "facebook": {"W_C": 0.50, "W_A": 0.60},
-  "reddit":   {"W_C": 0.60, "W_A": 0.40},
-  "other":    {"W_C": 0.10, "W_A": 0.20}
-}
+CEAR v1.0 is a foundation for deeper exploration into how we relate to algorithmic feeds.