Merge pull request #25 from deframer/sentiment-labels

Sentiment labels

Author: egandro

docs/assets/screenshots/portal/apollo-news_sentiments.png

@@ -10,3 +10,18 @@
 Wir verwenden einen VAD/VAC (Dimensional) und BE5 (Diskret) Ansatz zur Erkennung von Stimmungen und Emotionen in Texten. Dabei nutzen wir die Sentiment-Werte von [MEmoLon](https://github.com/JULIELab/MEmoLon), einem Emotionslexikon für über 90 Sprachen. Das **VAD**-Modell (Valenz, Arousal/Erregung, Dominanz) bewertet die allgemeine Stimmung auf einer Skala von 1-9 in den Bereichen Valenz (Polarität/Angenehmheit), Arousal (Aktivierung/Erregung) und Dominanz (wahrgenommene Kontrolle). Das **BE5**-Modell misst die Intensität der diskreten Emotionen – Freude, Wut, Traurigkeit, Angst und Ekel – auf einer Skala von 1-5.
 
 Es gibt grundlegende wissenschaftliche Erkenntnisse, die diese Methodik stützen: fMRT-Experimente zeigen, dass das Lesen bestimmter Wörter tatsächlich messbare emotionale Reaktionen im Gehirn hervorrufen kann. Weitere Details zu dieser Theorie finden Sie in dieser [Dissertation](https://edoc.ub.uni-muenchen.de/18933/1/Danner_Sandro_C.pdf).
+
+## Interpretation der Sentiments
+
+Die numerischen Rohwerte der VAD- und BE5-Modelle werden in verständliche Beschreibungen übersetzt. Diese heuristische Interpretationsebene wandelt kontinuierliche Vektoren in ein kompaktes Set von acht regelbasierten Labels um:
+
+1. **Kernzustand (Core State)**: Erfasst die globale VAD-Konfiguration und den allgemeinen affektiven Zustand (z. B. *zuversichtlich positiv*).
+2. **Hauptemotion (Primary Emotion)**: Identifiziert den stärksten diskreten Emotionskanal (z. B. *Freude*).
+3. **Sekundäremotion (Secondary Emotion)**: Erhält die zweitstärkste Emotion, um gemischte oder vielschichtige Zustände abzubilden.
+4. **Interpretation**: Die einfache Zusammenfassung, die den VAD-Zustand und das Emotionsprofil kombiniert (z. B. *Freude, Zuversicht und Sicherheit*).
+5. **Spannung (Tension Label)**: Trennt Aktivierung/Spannung von allgemeiner Positivität oder Negativität basierend auf dem Arousal.
+6. **Kontrolle (Control Label)**: Macht die Dominanz-Dimension explizit und verfolgt Handlungsfähigkeit, Macht und Verletzlichkeit.
+7. **Stimmung (Mood Label)**: Eine vereinfachte Polaritätslesart, die allein auf der Valenz basiert (z. B. *positiver Grundton*).
+8. **Klarheit (Clarity Label)**: Gibt an, wie deutlich eine Emotion die anderen dominiert (klar, gemischt oder mehrdeutig).
+
+Eine detaillierte technische Aufschlüsselung der Schwellenwerte und Mapping-Regeln finden Sie im [Sentiment README](https://github.com/deframer/news-deframer/blob/main/frontend/shared/sentiments/README.md).

docs/assets/screenshots/portal/nypost_sentiments.png

@@ -10,3 +10,18 @@
 We use a VAD/VAC (Dimensional) and BE5 (Discrete) approach to detect sentiments and emotions in texts, leveraging sentiment scores from [MEmoLon](https://github.com/JULIELab/MEmoLon), an emotion lexicon for 90+ languages. The **VAD** (Valence, Arousal, Dominance) model evaluates overall mood on a 1-9 scale across Valence (polarity/pleasantness), Arousal (activation/excitement), and Dominance (perceived control). The **BE5** model measures the intensity of discrete emotions—Joy, Anger, Sadness, Fear, and Disgust—on a 1-5 scale.
 
 There is fundamental science supporting this methodology: fMRT experiments demonstrate that reading specific words can indeed induce measurable emotional responses in the brain. For more details on this theory, refer to this [PhD thesis](https://edoc.ub.uni-muenchen.de/18933/1/Danner_Sandro_C.pdf).
+
+## Sentiment Interpretation
+
+The raw numeric scores from the VAD and BE5 models are mapped to plain English descriptions to make them easier to understand. This heuristic interpretation layer converts continuous affect vectors into a compact set of eight rule-based labels:
+
+1. **Core State**: Captures the global VAD configuration and broad affective state (e.g., *confident positive*).
+2. **Primary Emotion**: Identifies the strongest discrete emotion channel (e.g., *joy*).
+3. **Secondary Emotion**: Preserves the second strongest discrete emotion to account for mixed or layered states.
+4. **Interpretation**: The main semantic reading combining the VAD state and discrete emotion profile (e.g., *joy, confidence, and security*).
+5. **Tension Label**: Separates activation/tension from general positivity or negativity based on arousal.
+6. **Control Label**: Makes the dominance dimension explicit, tracking agency, power, and vulnerability.
+7. **Mood Label**: A simplified polarity reading based on valence alone (e.g., *positive tone*).
+8. **Clarity Label**: Indicates how sharply one emotion dominates the others (clear, mixed, or ambiguous).
+
+For a detailed technical breakdown of the thresholds and mapping rules, please refer to the [Sentiment README](https://github.com/deframer/news-deframer/blob/main/frontend/shared/sentiments/README.md).