Update README.md

README.md

@@ -1,83 +1,93 @@
 ---
-title: Cultural Exposure Risk Model
-emoji: 🧭
+title: CEAR – Cultural Exposure & Algorithmic Risk Analyzer
+emoji: 📡
 colorFrom: blue
-colorTo: green
+colorTo: purple
 sdk: gradio
-sdk_version: 6.0.2
+sdk_version: 4.0.0
 app_file: app.py
-pinned: false
+license: mit
 ---
-# Cultural Exposure & Algorithmic Risk (CEAR) Baseline v1.0
 
-## Model Description
+# CEAR – Cultural Exposure & Algorithmic Risk Analyzer
 
-The **Cultural Exposure & Algorithmic Risk (CEAR) Model** is an **analytic, rule-based scoring system** designed to help users and researchers interpret social media usage in terms of its potential impact on cultural awareness and algorithmic vulnerability.
+CEAR is an **analytic, rule-based model** and interactive Gradio app that helps you reason about your social media habits along three axes:
 
-This version is a V1 Baseline: it is **deterministic** (theory-driven by fixed rules and weights) and does not rely on supervised machine learning or proprietary user data.
+- **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  
 
-### 🎯 Key Outputs
+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.
 
-1.  **Cultural Connectedness Score (C-Score):** Estimates exposure to viral and trending content, modeled with diminishing returns on time.
-2.  **Algorithmic Risk Score (A-Risk):** Quantifies vulnerability incurred from concentrated time on high-intensity, opaque algorithmic feeds.
-3.  **Platform Diversity Index (D-Index):** Measures the concentration/spread of usage across platforms (using $1/\text{HHI}$).
-4.  **Cultural Efficiency:** Per-platform estimates of C-Score gained per minute spent.
+The live app runs here:  
+> `https://huggingface.co/spaces/<your-username>/CEAR`
 
-## ⚙️ Analytic Basis & Scoring Logic
-
-The model is defined by transparent assumptions encoded in the Python code (`cear_model.py`) and the platform weights (`platform_weights.json`).
-
-### Core Formulas
-
-The key to the C-Score is the **Diminishing Returns Function** ($f_{DR}$), which prevents the C-Score from increasing linearly with time, acknowledging that the first hour is likely more valuable than the tenth.
-
-$$f_{DR}(\text{Min}) = \log_{10}(\text{Min} + 1)$$
-
-The final scores are calculated as:
+---
 
-$$C_{Score} = \sum_{i} \left[ W_{C,i} \times f_{DR}(\text{Min}_i) \right]$$
+## 👤 What the app does
 
-$$A_{Risk} = \sum_{i} \left[ W_{A,i} \times \text{Min}_i \right]$$
+Given your **weekly screen time per platform**, a **per-platform variety rating**, and two **global self-reports** (satisfaction and FOMO), CEAR:
 
-*(Where $W_{C}$ is the Trend Density Weight and $W_{A}$ is the Algorithmic Risk Weight, defined in `platform_weights.json`.)*
+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.
 
-## 🚀 Deployment & Usage (Hugging Face Space)
+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.
 
-This repository contains the core logic (`cear_model.py`) and the application interface (`app.py`) for a Hugging Face Space.
+---
 
-### Model Integration (The Engine)
+## 🧮 Model description
 
-The core logic can be imported and run in any environment:
+### Inputs
 
-```python
-import pandas as pd
-from cear_model import CEARModel
+The app currently supports 7 platform buckets:
 
-# Example Input Data
-user_data = pd.DataFrame([
-    {'platform_name': 'TikTok', 'minutes_per_week': 450},
-    {'platform_name': 'YouTube', 'minutes_per_week': 200},
-    {'platform_name': 'Reddit', 'minutes_per_week': 50},
-])
+- TikTok  
+- Instagram  
+- YouTube  
+- Twitter / X  
+- Reddit  
+- Facebook  
+- Other (anything else you use)
 
-model = CEARModel()
-results = model.calculate_scores(user_data)
-# {'C_Score': 3.75, 'A_Risk': 565.0, ...}
+For each platform, you provide:
 
-# Application Interface (The App - app.py)
+- `minutes_per_week` (number)  
+- `variety_score` (slider, 0–10)
 
-The app.py script uses the Gradio library to create an interactive web interface. It handles:
+Global self-report sliders:
 
-    Collecting user input via a table component.
+- `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?”
 
-    Calling the CEARModel.calculate_scores() method.
+### Input rules and validation
 
-    Generating a qualitative natural language summary based on the quadrant of the C-Score and A-Risk (e.g., "High C, Low A").
+- **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.
 
-⚠️ Limitations and Ethical Considerations
+This keeps the math honest: variety only matters where you actually spend time.
 
-1. Theoretical, Not Validated: The scores are based on fixed, theoretical assumptions about platform design. They are not calibrated against real-world user survey data or outcomes (e.g., actual cultural literacy, actual regret). Scores are relative estimates only.
+### Internals – how the scores are computed
 
-2. No Content Analysis: The model only uses time and platform. It cannot distinguish between a productive hour watching educational content and an unproductive hour scrolling low-quality content.
+Platform weights live in `platform_weights.json` and look like:
 
-3. Future Work: This deterministic model serves as a foundation. Future versions are intended to use the same input schema to train supervised machine learning models that directly predict outcomes (e.g., predicting user-reported "felt caught up" or "post-scroll regret").
+```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}
+}