README.md

---
title: CEAR – Cultural Exposure & Algorithmic Risk Analyzer
emoji: 📡
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.1.0
app_file: app.py
license: mit
---

# CEAR – Cultural Exposure & Algorithmic Risk Analyzer

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)** – approximate trend exposure
* **Algorithmic Risk (A-Risk)** – attention concentration in algorithm-driven feeds
* **Diversity Index (D-Index)** – distribution of time 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.

---

## 🚀 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)

---

## 🧪 Validation

Since CEAR is deterministic, validation focuses on correctness:

* 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.

---

## ⚠️ 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**.

---

## 🔧 Running Locally

You can run the app locally:

```bash
pip install -r requirements.txt
python app.py
```

Or import the model:

```python
from cear_model import CEARModel
import pandas as pd

model = CEARModel()
df = pd.DataFrame([
    {"platform_name": "tiktok", "minutes_per_week": 300, "variety_score": 4},
])
print(model.calculate_scores(df, satisfaction=6, fomo=4))
```

---

## 📜 License

MIT License

---

## 🙌 Acknowledgments

This project was built to demonstrate:

* Transparent model design
* Clear model documentation
* Proper Hugging Face Space structure
* User-oriented interpretability

Feel free to fork and extend with:

* Empirical weights
* Trend detection
* Behavioral clustering
* Recommendation strategies

CEAR v1.0 is a foundation for deeper exploration into how we relate to algorithmic feeds.