emo

emo Emoji Sentiment Analyzer

emo is a zero-dependency, high-performance Rust CLI tool that analyzes text and text files for emoji usage, weighted sentiment scores, non-neutral intensity, emotional polarization, and timeline progression based on the research-backed Emoji Sentiment Ranking 1.0 dataset.

Installation

cargo install emoji-sentiment

When to Use

Use the emo CLI when you need to:

1. Analyze Text Sentiment: Calculate quantitative weighted sentiment scores (-1.0 to +1.0) and non-neutral intensity (0.0 to 1.0) for any text or file.
2. Detect Emotional Polarization: Evaluate whether text contains conflicting positive and negative emotions (Polarization Index: 0.0 to 1.0).
3. Track Sentiment Shift over Time/Paragraphs: Track emotional trends (Warming Up 📈, Cooling Down 📉, Fluctuating 🌊) across 4-quarter timeline, paragraphs (--by-paragraph), or lines (--by-line).
4. Multi-File Benchmark: Compare sentiment metrics across multiple text files side-by-side.
5. Extract Structured Data: Produce formatted JSON (--json) for automated pipelines, agent decisions, or database storage.

---

Command Usage Examples

1. Basic Text Sentiment Analysis (via stdin)

echo "Rust is awesome! 🎉🚀 But debugging can be tricky 😭" | emo

2. File or Directory Analysis

# Analyze a single file
emo path/to/document.txt

# Analyze an entire directory (recursively scans all text files and generates benchmark)
emo path/to/logs_directory/

3. Multi-File Benchmark Comparison

When given multiple files, emo automatically outputs a side-by-side comparative table before the aggregated summary:

emo log1.txt log2.txt log3.txt

4. Segmented Analysis (Paragraphs or Lines)

# Analyze sentiment arc paragraph by paragraph (\n\n)
emo --by-paragraph article.md

# Analyze sentiment arc line by line (\n)
emo --by-line chat_log.txt

5. Programmatic JSON Output (for Agents & Pipelines)

emo --json feedback.txt

6. Concise One-Line Summary Output

emo --summary comment.txt

---

JSON Output Schema & Key Metrics

When running emo --json, the resulting JSON object contains the following key fields:

{
  "total_chars": 84,
  "total_words": 15,
  "total_emojis": 5,
  "unique_emojis": 5,
  "matched_emojis_count": 5,
  "unmatched_emojis_count": 0,
  "overall_score": 0.345,
  "overall_intensity": 0.742,
  "positive_count": 3,
  "neutral_count": 0,
  "negative_count": 2,
  "density_per_1000_chars": 59.52,
  "density_per_100_words": 33.33,
  "style_level": "Heavy Emoji / Social",
  "entropy": 2.322,
  "diversity_ratio": 1.0,
  "polarization_index": 0.96,
  "polarization_status": "Highly Polarized 🔥❄️",
  "volatility_std_dev": 0.412,
  "volatility_status": "High Volatility / Emotional Swing 🌊",
  "ambiguity_index": 0.0,
  "ambiguity_status": "Direct & Explicit 🎯",
  "position_bias": {
    "avg_position": 0.45,
    "front_pct": 40.0,
    "mid_pct": 40.0,
    "end_pct": 20.0,
    "bias_status": "Balanced Placement"
  },
  "slang_analysis": {
    "total_slang_count": 3,
    "slang_density_per_100_words": 20.0,
    "sarcasm_index": 85.0,
    "sarcasm_status": "High Sarcasm / Irony Alert 🎭",
    "elongation_count": 1,
    "hybrid_score": 0.525,
    "top_slang": [
      {
        "term": "笑死",
        "count": 1,
        "sentiment_score": 0.8,
        "sarcasm_weight": 0.2,
        "meaning": "extremely funny"
      }
    ]
  },
  "block_stats": [
    {
      "block_name": "Emoticons",
      "count": 2,
      "percentage": 40.0,
      "avg_score": 0.292
    }
  ],
  "progression": {
    "segments": [
      {
        "label": "Q1 (Beginning)",
        "score": 0.709,
        "intensity": 0.799,
        "emoji_count": 2
      }
    ],
    "trend_status": "Cooling Down 📉 (Positive → Negative)"
  },
  "top_used": [
    {
      "emoji": "🎉",
      "name": "PARTY POPPER",
      "count": 1,
      "score": 0.74,
      "intensity": 0.816,
      "in_dataset": true
    }
  ]
}

---

Score Range & Interpretation Guide

---

Dataset References & Community Standards

While emo relies on Emoji Sentiment Ranking 1.0 for compiled zero-dependency runtime evaluation, the following datasets are standard references in the NLP research community:

• Emoji Sentiment Ranking 1.0 (Built-in): 751 annotated emojis with polarity scores (-1.0 to +1.0). (Novak et al., 2015)
• TweetEval / SemEval-2018 Task 2: Contextual emoji prediction benchmark across 20 classes. (Barbieri et al., 2018)
• DeepMoji: 1.2B Twitter corpus across 64 emoji labels for transfer learning and sarcasm detection. (Felbo et al., EMNLP 2017)
• EmojiNet: Multi-sense emoji knowledge base linking 2,300+ emojis to BabelNet synsets. (Knoesis Institute)
• Google GoEmotions: 58k Reddit comments across 27 fine-grained emotions mapped 1-to-1 to emojis. (Google Research, 2020)
• Social Media Slang & Emoji Corpus: ~14k UGC texts with slang, elongated words, and explicit sarcasm labels. (Kaggle)