| Name | emoticon-fix JSON |
| Version |
0.2.4
JSON |
| download |
| home_page | https://github.com/xga0/emoticon_fix |
| Summary | A lightweight and efficient library for transforming emoticons into their semantic meanings with sentiment analysis capabilities |
| upload_time | 2025-07-20 00:59:42 |
| maintainer | None |
| docs_url | None |
| author | Sean Gao |
| requires_python | >=3.6 |
| license | MIT License
Copyright (c) 2020 Xiangyu Gao
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Emoticon Fix
[](https://pypi.org/project/emoticon-fix/)
[](https://pypi.org/project/emoticon-fix/)
[](https://opensource.org/licenses/MIT)
A lightweight and efficient library for transforming emoticons into their semantic meanings. This is particularly useful for NLP preprocessing where emoticons need to be preserved as meaningful text.
## Table of Contents
- [What are emoticons?](#what-are-emoticons)
- [What are kaomoji?](#what-are-kaomoji)
- [Why transform emoticons to text?](#why-transform-emoticons-to-text)
- [Installation](#installation)
- [Usage](#usage)
- [Sentiment Analysis](#sentiment-analysis)
- [Analytics & Statistics](#analytics--statistics)
- [Data Export](#data-export)
- [Examples](#examples)
- [Contributing](#contributing)
- [Testing](#testing)
- [License](#license)
## What are emoticons?
An emoticon (short for "emotion icon") is a pictorial representation of a facial expression using characters—usually punctuation marks, numbers, and letters—to express a person's feelings or mood. The first ASCII emoticons, `:-)` and `:-(`, were written by Scott Fahlman in 1982, but emoticons actually originated on the PLATO IV computer system in 1972.
## What are kaomoji?
Kaomoji (顔文字) are Japanese emoticons that are read horizontally and are more elaborate than traditional Western emoticons. They often use Unicode characters to create more complex expressions and can represent a wider range of emotions and actions. For example, `(｡♥‿♥｡)` represents being in love, and `(ノ°益°)ノ` shows rage. Unlike Western emoticons that you read by tilting your head sideways, kaomoji are meant to be viewed straight on.
emoticon_fix supports a wide variety of kaomoji, making it particularly useful for processing text from Asian social media or any platform where kaomoji are commonly used.
## Why transform emoticons to text?
When preprocessing text for NLP models, simply removing punctuation can leave emoticons and kaomoji as meaningless characters. For example, `:D` (laugh) would become just `D`, and `(｡♥‿♥｡)` (in love) would be completely lost. This can negatively impact model performance. By transforming emoticons and kaomoji to their textual meanings, we preserve the emotional context in a format that's more meaningful for NLP tasks.
## Installation
```bash
pip install emoticon-fix
```
## Usage
```python
from emoticon_fix import emoticon_fix, remove_emoticons, replace_emoticons
# Basic usage - transform emoticons to their meanings
text = 'Hello :) World :D'
result = emoticon_fix(text)
print(result) # Output: 'Hello Smile World Laugh'
# Remove emoticons completely
stripped_text = remove_emoticons(text)
print(stripped_text) # Output: 'Hello World'
# Replace with NER-friendly tags (customizable format)
ner_text = replace_emoticons(text, tag_format="__EMO_{tag}__")
print(ner_text) # Output: 'Hello __EMO_Smile__ World __EMO_Laugh__'
# Works with multiple emoticons
text = 'I am :-) but sometimes :-( and occasionally :-D'
result = emoticon_fix(text)
print(result) # Output: 'I am Smile but sometimes Sad and occasionally Laugh'
```
### New: Sentiment Analysis
```python
from emoticon_fix import analyze_sentiment, get_sentiment_score, classify_sentiment
# Analyze sentiment of emoticons in text
text = "Having a great day :) :D!"
analysis = analyze_sentiment(text)
print(f"Sentiment: {analysis.classification}") # "Very Positive"
print(f"Score: {analysis.average_score:.3f}") # "0.800"
# Get just the sentiment score (-1.0 to 1.0)
score = get_sentiment_score("Happy :) but sad :(")
print(score) # 0.05 (slightly positive)
# Get sentiment classification
classification = classify_sentiment("Love this (｡♥‿♥｡) so much!")
print(classification) # "Very Positive"
```
### New: Analytics & Statistics
The analytics extension provides comprehensive emoticon usage analysis:
```python
from emoticon_fix import (
get_emoticon_statistics,
create_emotion_profile,
compare_emotion_profiles,
get_emoticon_trends
)
# Get detailed statistics about emoticon usage
text = "Happy :) very :) extremely :D and sometimes sad :("
stats = get_emoticon_statistics(text)
print(f"Total emoticons: {stats.total_emoticons}") # 4
print(f"Unique emoticons: {stats.unique_emoticons}") # 3
print(f"Dominant emotion: {stats.dominant_emotion}") # "Smile"
print(f"Average sentiment: {stats.average_sentiment:.3f}") # 0.525
print(f"Emoticon density: {stats.get_emoticon_density():.1f}%") # per 100 chars
# Get top emoticons and emotions
print("Top emoticons:", stats.get_top_emoticons(3))
print("Top emotions:", stats.get_top_emotions(3))
```
### Emotion Profiling
Create comprehensive emotion profiles for users or text collections:
```python
# Create emotion profile from multiple texts
texts = [
"Having a great day :) :D",
"Feeling sad today :(",
"Mixed emotions :) but also :/ sometimes",
"Super excited! :D :D (｡♥‿♥｡)"
]
profile = create_emotion_profile(texts, "User Profile")
print(f"Profile: {profile.name}")
print(f"Texts analyzed: {profile.texts_analyzed}")
print(f"Total emoticons: {profile.total_emoticons}")
print(f"Overall sentiment: {profile.get_overall_sentiment():.3f}")
print(f"Emotion diversity: {profile.get_emotion_diversity():.3f}")
print(f"Sentiment consistency: {profile.get_sentiment_consistency():.3f}")
# Get dominant emotions across all texts
dominant_emotions = profile.get_dominant_emotions(5)
print("Dominant emotions:", dominant_emotions)
```
### Profile Comparison
Compare emotion patterns between different users or text collections:
```python
# Create multiple profiles
happy_user = create_emotion_profile([
"Great day :D", "So happy :)", "Love this! (｡♥‿♥｡)"
], "Happy User")
sad_user = create_emotion_profile([
"Feeling down :(", "Bad day :(", "Not good :("
], "Sad User")
mixed_user = create_emotion_profile([
"Happy :) but worried :(", "Good :) and bad :(", "Mixed feelings :/ :)"
], "Mixed User")
# Compare profiles
comparison = compare_emotion_profiles([happy_user, sad_user, mixed_user])
print(f"Profiles compared: {comparison['profiles_compared']}")
print("Sentiment range:", comparison['overall_comparison']['sentiment_range'])
print("Diversity range:", comparison['overall_comparison']['diversity_range'])
# Individual profile summaries
for profile in comparison['profile_summaries']:
print(f"{profile['name']}: sentiment={profile['overall_sentiment']:.3f}")
```
### Trend Analysis
Analyze emoticon trends across multiple texts or time periods:
```python
# Analyze trends across multiple texts
texts = [
"Day 1: Excited to start :D",
"Day 2: Going well :)",
"Day 3: Some challenges :/",
"Day 4: Feeling better :)",
"Day 5: Great finish :D :D"
]
labels = [f"Day {i+1}" for i in range(len(texts))]
trends = get_emoticon_trends(texts, labels)
print(f"Total texts analyzed: {trends['total_texts']}")
print("Sentiment trend:", trends['trend_summary']['sentiment_trend'])
print("Average sentiment:", trends['trend_summary']['average_sentiment_across_texts'])
# Most common emotions across all texts
print("Most common emotions:", trends['trend_summary']['most_common_emotions'])
```
## Sentiment Analysis
The sentiment analysis extension provides powerful emotion detection capabilities:
### Features
- **Sentiment Scoring**: Get numerical sentiment scores (-1.0 to 1.0)
- **Classification**: Automatic categorization (Very Positive, Positive, Neutral, Negative, Very Negative)
- **Emotion Extraction**: Extract individual emoticons with their emotions and scores
- **Batch Processing**: Analyze multiple texts efficiently
- **Detailed Analysis**: Get comprehensive sentiment reports
### Advanced Usage
```python
from emoticon_fix import analyze_sentiment, extract_emotions, batch_analyze
# Detailed sentiment analysis
text = "Mixed feelings :) but also :( about this"
analysis = analyze_sentiment(text)
print(analysis.summary())
# Extract individual emotions
emotions = extract_emotions("Happy :) but worried :(")
for emoticon, emotion, score in emotions:
print(f"'{emoticon}' → {emotion} (score: {score:.3f})")
# Batch processing
texts = ["Happy :)", "Sad :(", "Excited :D"]
results = batch_analyze(texts)
```
### Sentiment Scoring System
- **Very Positive (0.8-1.0)**: Love, Very Happy, Excited, Dancing Joy
- **Positive (0.3-0.7)**: Smile, Happy, Wink, Hug, Kiss
- **Neutral (0.0-0.2)**: Neutral, Tongue, Surprised, Confused
- **Negative (-0.2 to -0.7)**: Sad, Crying, Worried, Annoyed
- **Very Negative (-0.8 to -1.0)**: Angry, Rage, Table Flip
## Analytics & Statistics
The analytics extension provides comprehensive emoticon usage analysis capabilities:
### EmoticonStats Features
- **Frequency Analysis**: Count emoticon and emotion occurrences
- **Sentiment Distribution**: Categorize emoticons by sentiment
- **Density Calculation**: Emoticons per 100 characters
- **Position Tracking**: Track emoticon positions in text
- **Top Rankings**: Get most frequent emoticons and emotions
### EmoticonProfile Features
- **Multi-text Analysis**: Aggregate statistics across multiple texts
- **Emotion Diversity**: Measure variety of emotions used
- **Sentiment Consistency**: Measure emotional stability over time
- **Comparative Metrics**: Compare different users or periods
### Advanced Analytics
```python
from emoticon_fix import get_emoticon_statistics, EmoticonProfile
# Detailed emoticon statistics
text = "Super happy :D today! Great mood :) and excited (｡♥‿♥｡) for later!"
stats = get_emoticon_statistics(text)
# Access detailed information
print(f"Emoticon positions: {stats.emoticon_positions}")
print(f"Sentiment distribution: {stats.sentiment_distribution}")
print(f"Top 3 emoticons: {stats.get_top_emoticons(3)}")
print(f"Analysis timestamp: {stats.analysis_timestamp}")
# Create custom profile
profile = EmoticonProfile("Custom Analysis")
profile.add_text("First text :)", "text_1")
profile.add_text("Second text :(", "text_2")
profile.add_text("Third text :D", "text_3")
print(f"Emotion diversity: {profile.get_emotion_diversity():.3f}")
print(f"Sentiment consistency: {profile.get_sentiment_consistency():.3f}")
```
## Data Export
Export analysis results for further processing or visualization:
```python
from emoticon_fix import export_analysis, get_emoticon_statistics, create_emotion_profile
# Export statistics to JSON
text = "Happy :) day with multiple :D emoticons!"
stats = get_emoticon_statistics(text)
# Export to JSON (default format)
json_file = export_analysis(stats, format="json", filename="emoticon_stats.json")
print(f"Exported to: {json_file}")
# Export to CSV
csv_file = export_analysis(stats, format="csv", filename="emoticon_stats.csv")
print(f"Exported to: {csv_file}")
# Export emotion profile
texts = ["Happy :)", "Sad :(", "Excited :D"]
profile = create_emotion_profile(texts, "Sample Profile")
profile_file = export_analysis(profile, format="json", filename="emotion_profile.json")
# Auto-generate filename with timestamp
auto_file = export_analysis(stats) # Creates: emoticon_analysis_YYYYMMDD_HHMMSS.json
```
### Export Formats
**JSON Export**: Complete data structure with all metrics and metadata
```json
{
"total_emoticons": 3,
"unique_emoticons": 2,
"emoticon_density": 12.5,
"emoticon_frequency": {":)": 2, ":D": 1},
"emotion_frequency": {"Smile": 2, "Laugh": 1},
"sentiment_distribution": {"positive": 3, "negative": 0, "neutral": 0},
"average_sentiment": 0.8,
"dominant_emotion": "Smile",
"analysis_timestamp": "2024-01-15T10:30:00"
}
```
**CSV Export**: Structured tabular format for spreadsheet analysis
- Emoticon statistics with frequencies
- Emotion breakdowns
- Sentiment distributions
- Compatible with Excel, Google Sheets, etc.
## Examples
### Basic Example
```python
from emoticon_fix import emoticon_fix
text = 'test :) test :D test'
result = emoticon_fix(text)
print(result) # Output: 'test Smile test Laugh test'
```
### Complex Example with Kaomoji
```python
from emoticon_fix import emoticon_fix
text = 'Feeling (｡♥‿♥｡) today! When things go wrong ┗(＾0＾)┓ keep dancing!'
result = emoticon_fix(text)
print(result) # Output: 'Feeling In Love today! When things go wrong Dancing Joy keep dancing!'
```
### Mixed Emoticons Example
```python
from emoticon_fix import emoticon_fix
text = 'Western :) meets Eastern (◕‿◕✿) style!'
result = emoticon_fix(text)
print(result) # Output: 'Western Smile meets Eastern Sweet Smile style!'
```
### Removing Emoticons Example
```python
from emoticon_fix import remove_emoticons
text = 'This message :D contains some (｡♥‿♥｡) emoticons that need to be removed!'
result = remove_emoticons(text)
print(result) # Output: 'This message contains some emoticons that need to be removed!'
```
### NER-Friendly Tagging Example
```python
from emoticon_fix import replace_emoticons
# Default format: __EMO_{tag}__
text = 'Happy customers :) are returning customers!'
result = replace_emoticons(text)
print(result) # Output: 'Happy customers __EMO_Smile__ are returning customers!'
# Custom format
text = 'User feedback: Product was great :D but shipping was slow :('
result = replace_emoticons(text, tag_format="<EMOTION type='{tag}'>")
print(result) # Output: 'User feedback: Product was great <EMOTION type='Laugh'> but shipping was slow <EMOTION type='Sad'>'
```
### Social Media Analysis Example
```python
from emoticon_fix import create_emotion_profile, compare_emotion_profiles, export_analysis
# Analyze social media posts from different users
user1_posts = [
"Amazing product! :D Love it!",
"Great customer service :)",
"Highly recommended! (｡♥‿♥｡)"
]
user2_posts = [
"Product was okay :/",
"Shipping was slow :(",
"Could be better... :/"
]
user3_posts = [
"Mixed experience :) good product but :( bad delivery",
"Happy with purchase :) but upset about delay :(",
"Overall satisfied :) despite issues :/"
]
# Create emotion profiles
user1_profile = create_emotion_profile(user1_posts, "Satisfied Customer")
user2_profile = create_emotion_profile(user2_posts, "Dissatisfied Customer")
user3_profile = create_emotion_profile(user3_posts, "Mixed Customer")
# Compare profiles
comparison = compare_emotion_profiles([user1_profile, user2_profile, user3_profile])
# Export results
export_analysis(comparison, format="json", filename="customer_sentiment_analysis.json")
print("Customer sentiment analysis completed!")
print(f"Satisfied customer sentiment: {user1_profile.get_overall_sentiment():.3f}")
print(f"Dissatisfied customer sentiment: {user2_profile.get_overall_sentiment():.3f}")
print(f"Mixed customer sentiment: {user3_profile.get_overall_sentiment():.3f}")
```
### Time Series Analysis Example
```python
from emoticon_fix import get_emoticon_trends, export_analysis
# Analyze emotional progression over time
weekly_posts = [
"Week 1: Starting new job :) excited!",
"Week 2: Learning lots :D challenging but fun!",
"Week 3: Feeling overwhelmed :( too much work",
"Week 4: Getting better :) finding my rhythm",
"Week 5: Confident now :D loving the work!",
"Week 6: Stress again :( big project deadline",
"Week 7: Relief! :D Project completed successfully!",
"Week 8: Balanced now :) happy with progress"
]
week_labels = [f"Week {i+1}" for i in range(len(weekly_posts))]
trends = get_emoticon_trends(weekly_posts, week_labels)
# Export trend analysis
export_analysis(trends, format="json", filename="emotional_journey.json")
print("Emotional journey analysis:")
sentiment_trend = trends['trend_summary']['sentiment_trend']
for i, sentiment in enumerate(sentiment_trend):
print(f"Week {i+1}: {sentiment:.3f}")
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Testing
The package includes a comprehensive test suite. To run the tests:
```bash
pip install -e ".[dev]"
pytest
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/xga0/emoticon_fix",
"name": "emoticon-fix",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Sean Gao",
"author_email": "Sean Gao <seangaoxy@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/31/8e/328a297bf5bc5479da9ff6dbb54af120cb437b993d3816b34f4e1e425c48/emoticon_fix-0.2.4.tar.gz",
"platform": null,
"description": "# Emoticon Fix\n\n[](https://pypi.org/project/emoticon-fix/)\n[](https://pypi.org/project/emoticon-fix/)\n[](https://opensource.org/licenses/MIT)\n\nA lightweight and efficient library for transforming emoticons into their semantic meanings. This is particularly useful for NLP preprocessing where emoticons need to be preserved as meaningful text.\n\n## Table of Contents\n\n- [What are emoticons?](#what-are-emoticons)\n- [What are kaomoji?](#what-are-kaomoji)\n- [Why transform emoticons to text?](#why-transform-emoticons-to-text)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Sentiment Analysis](#sentiment-analysis)\n- [Analytics & Statistics](#analytics--statistics)\n- [Data Export](#data-export)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [Testing](#testing)\n- [License](#license)\n\n## What are emoticons?\n\nAn emoticon (short for \"emotion icon\") is a pictorial representation of a facial expression using characters\u2014usually punctuation marks, numbers, and letters\u2014to express a person's feelings or mood. The first ASCII emoticons, `:-)` and `:-(`, were written by Scott Fahlman in 1982, but emoticons actually originated on the PLATO IV computer system in 1972.\n\n## What are kaomoji?\n\nKaomoji (\u9854\u6587\u5b57) are Japanese emoticons that are read horizontally and are more elaborate than traditional Western emoticons. They often use Unicode characters to create more complex expressions and can represent a wider range of emotions and actions. For example, `(\uff61\u2665\u203f\u2665\uff61)` represents being in love, and `(\u30ce\u00b0\u76ca\u00b0)\u30ce` shows rage. Unlike Western emoticons that you read by tilting your head sideways, kaomoji are meant to be viewed straight on.\n\nemoticon_fix supports a wide variety of kaomoji, making it particularly useful for processing text from Asian social media or any platform where kaomoji are commonly used.\n\n## Why transform emoticons to text?\n\nWhen preprocessing text for NLP models, simply removing punctuation can leave emoticons and kaomoji as meaningless characters. For example, `:D` (laugh) would become just `D`, and `(\uff61\u2665\u203f\u2665\uff61)` (in love) would be completely lost. This can negatively impact model performance. By transforming emoticons and kaomoji to their textual meanings, we preserve the emotional context in a format that's more meaningful for NLP tasks.\n\n## Installation\n\n```bash\npip install emoticon-fix\n```\n\n## Usage\n\n```python\nfrom emoticon_fix import emoticon_fix, remove_emoticons, replace_emoticons\n\n# Basic usage - transform emoticons to their meanings\ntext = 'Hello :) World :D'\nresult = emoticon_fix(text)\nprint(result) # Output: 'Hello Smile World Laugh'\n\n# Remove emoticons completely\nstripped_text = remove_emoticons(text)\nprint(stripped_text) # Output: 'Hello World'\n\n# Replace with NER-friendly tags (customizable format)\nner_text = replace_emoticons(text, tag_format=\"__EMO_{tag}__\")\nprint(ner_text) # Output: 'Hello __EMO_Smile__ World __EMO_Laugh__'\n\n# Works with multiple emoticons\ntext = 'I am :-) but sometimes :-( and occasionally :-D'\nresult = emoticon_fix(text)\nprint(result) # Output: 'I am Smile but sometimes Sad and occasionally Laugh'\n```\n\n### New: Sentiment Analysis\n\n```python\nfrom emoticon_fix import analyze_sentiment, get_sentiment_score, classify_sentiment\n\n# Analyze sentiment of emoticons in text\ntext = \"Having a great day :) :D!\"\nanalysis = analyze_sentiment(text)\nprint(f\"Sentiment: {analysis.classification}\") # \"Very Positive\"\nprint(f\"Score: {analysis.average_score:.3f}\") # \"0.800\"\n\n# Get just the sentiment score (-1.0 to 1.0)\nscore = get_sentiment_score(\"Happy :) but sad :(\")\nprint(score) # 0.05 (slightly positive)\n\n# Get sentiment classification\nclassification = classify_sentiment(\"Love this (\uff61\u2665\u203f\u2665\uff61) so much!\")\nprint(classification) # \"Very Positive\"\n```\n\n### New: Analytics & Statistics\n\nThe analytics extension provides comprehensive emoticon usage analysis:\n\n```python\nfrom emoticon_fix import (\n get_emoticon_statistics, \n create_emotion_profile, \n compare_emotion_profiles,\n get_emoticon_trends\n)\n\n# Get detailed statistics about emoticon usage\ntext = \"Happy :) very :) extremely :D and sometimes sad :(\"\nstats = get_emoticon_statistics(text)\n\nprint(f\"Total emoticons: {stats.total_emoticons}\") # 4\nprint(f\"Unique emoticons: {stats.unique_emoticons}\") # 3\nprint(f\"Dominant emotion: {stats.dominant_emotion}\") # \"Smile\"\nprint(f\"Average sentiment: {stats.average_sentiment:.3f}\") # 0.525\nprint(f\"Emoticon density: {stats.get_emoticon_density():.1f}%\") # per 100 chars\n\n# Get top emoticons and emotions\nprint(\"Top emoticons:\", stats.get_top_emoticons(3))\nprint(\"Top emotions:\", stats.get_top_emotions(3))\n```\n\n### Emotion Profiling\n\nCreate comprehensive emotion profiles for users or text collections:\n\n```python\n# Create emotion profile from multiple texts\ntexts = [\n \"Having a great day :) :D\",\n \"Feeling sad today :(\",\n \"Mixed emotions :) but also :/ sometimes\",\n \"Super excited! :D :D (\uff61\u2665\u203f\u2665\uff61)\"\n]\n\nprofile = create_emotion_profile(texts, \"User Profile\")\n\nprint(f\"Profile: {profile.name}\")\nprint(f\"Texts analyzed: {profile.texts_analyzed}\")\nprint(f\"Total emoticons: {profile.total_emoticons}\")\nprint(f\"Overall sentiment: {profile.get_overall_sentiment():.3f}\")\nprint(f\"Emotion diversity: {profile.get_emotion_diversity():.3f}\")\nprint(f\"Sentiment consistency: {profile.get_sentiment_consistency():.3f}\")\n\n# Get dominant emotions across all texts\ndominant_emotions = profile.get_dominant_emotions(5)\nprint(\"Dominant emotions:\", dominant_emotions)\n```\n\n### Profile Comparison\n\nCompare emotion patterns between different users or text collections:\n\n```python\n# Create multiple profiles\nhappy_user = create_emotion_profile([\n \"Great day :D\", \"So happy :)\", \"Love this! (\uff61\u2665\u203f\u2665\uff61)\"\n], \"Happy User\")\n\nsad_user = create_emotion_profile([\n \"Feeling down :(\", \"Bad day :(\", \"Not good :(\"\n], \"Sad User\")\n\nmixed_user = create_emotion_profile([\n \"Happy :) but worried :(\", \"Good :) and bad :(\", \"Mixed feelings :/ :)\"\n], \"Mixed User\")\n\n# Compare profiles\ncomparison = compare_emotion_profiles([happy_user, sad_user, mixed_user])\n\nprint(f\"Profiles compared: {comparison['profiles_compared']}\")\nprint(\"Sentiment range:\", comparison['overall_comparison']['sentiment_range'])\nprint(\"Diversity range:\", comparison['overall_comparison']['diversity_range'])\n\n# Individual profile summaries\nfor profile in comparison['profile_summaries']:\n print(f\"{profile['name']}: sentiment={profile['overall_sentiment']:.3f}\")\n```\n\n### Trend Analysis\n\nAnalyze emoticon trends across multiple texts or time periods:\n\n```python\n# Analyze trends across multiple texts\ntexts = [\n \"Day 1: Excited to start :D\",\n \"Day 2: Going well :)\",\n \"Day 3: Some challenges :/\",\n \"Day 4: Feeling better :)\",\n \"Day 5: Great finish :D :D\"\n]\n\nlabels = [f\"Day {i+1}\" for i in range(len(texts))]\ntrends = get_emoticon_trends(texts, labels)\n\nprint(f\"Total texts analyzed: {trends['total_texts']}\")\nprint(\"Sentiment trend:\", trends['trend_summary']['sentiment_trend'])\nprint(\"Average sentiment:\", trends['trend_summary']['average_sentiment_across_texts'])\n\n# Most common emotions across all texts\nprint(\"Most common emotions:\", trends['trend_summary']['most_common_emotions'])\n```\n\n## Sentiment Analysis\n\nThe sentiment analysis extension provides powerful emotion detection capabilities:\n\n### Features\n\n- **Sentiment Scoring**: Get numerical sentiment scores (-1.0 to 1.0)\n- **Classification**: Automatic categorization (Very Positive, Positive, Neutral, Negative, Very Negative)\n- **Emotion Extraction**: Extract individual emoticons with their emotions and scores\n- **Batch Processing**: Analyze multiple texts efficiently\n- **Detailed Analysis**: Get comprehensive sentiment reports\n\n### Advanced Usage\n\n```python\nfrom emoticon_fix import analyze_sentiment, extract_emotions, batch_analyze\n\n# Detailed sentiment analysis\ntext = \"Mixed feelings :) but also :( about this\"\nanalysis = analyze_sentiment(text)\nprint(analysis.summary())\n\n# Extract individual emotions\nemotions = extract_emotions(\"Happy :) but worried :(\")\nfor emoticon, emotion, score in emotions:\n print(f\"'{emoticon}' \u2192 {emotion} (score: {score:.3f})\")\n\n# Batch processing\ntexts = [\"Happy :)\", \"Sad :(\", \"Excited :D\"]\nresults = batch_analyze(texts)\n```\n\n### Sentiment Scoring System\n\n- **Very Positive (0.8-1.0)**: Love, Very Happy, Excited, Dancing Joy\n- **Positive (0.3-0.7)**: Smile, Happy, Wink, Hug, Kiss\n- **Neutral (0.0-0.2)**: Neutral, Tongue, Surprised, Confused\n- **Negative (-0.2 to -0.7)**: Sad, Crying, Worried, Annoyed\n- **Very Negative (-0.8 to -1.0)**: Angry, Rage, Table Flip\n\n## Analytics & Statistics\n\nThe analytics extension provides comprehensive emoticon usage analysis capabilities:\n\n### EmoticonStats Features\n\n- **Frequency Analysis**: Count emoticon and emotion occurrences\n- **Sentiment Distribution**: Categorize emoticons by sentiment\n- **Density Calculation**: Emoticons per 100 characters\n- **Position Tracking**: Track emoticon positions in text\n- **Top Rankings**: Get most frequent emoticons and emotions\n\n### EmoticonProfile Features\n\n- **Multi-text Analysis**: Aggregate statistics across multiple texts\n- **Emotion Diversity**: Measure variety of emotions used\n- **Sentiment Consistency**: Measure emotional stability over time\n- **Comparative Metrics**: Compare different users or periods\n\n### Advanced Analytics\n\n```python\nfrom emoticon_fix import get_emoticon_statistics, EmoticonProfile\n\n# Detailed emoticon statistics\ntext = \"Super happy :D today! Great mood :) and excited (\uff61\u2665\u203f\u2665\uff61) for later!\"\nstats = get_emoticon_statistics(text)\n\n# Access detailed information\nprint(f\"Emoticon positions: {stats.emoticon_positions}\")\nprint(f\"Sentiment distribution: {stats.sentiment_distribution}\")\nprint(f\"Top 3 emoticons: {stats.get_top_emoticons(3)}\")\nprint(f\"Analysis timestamp: {stats.analysis_timestamp}\")\n\n# Create custom profile\nprofile = EmoticonProfile(\"Custom Analysis\")\nprofile.add_text(\"First text :)\", \"text_1\")\nprofile.add_text(\"Second text :(\", \"text_2\")\nprofile.add_text(\"Third text :D\", \"text_3\")\n\nprint(f\"Emotion diversity: {profile.get_emotion_diversity():.3f}\")\nprint(f\"Sentiment consistency: {profile.get_sentiment_consistency():.3f}\")\n```\n\n## Data Export\n\nExport analysis results for further processing or visualization:\n\n```python\nfrom emoticon_fix import export_analysis, get_emoticon_statistics, create_emotion_profile\n\n# Export statistics to JSON\ntext = \"Happy :) day with multiple :D emoticons!\"\nstats = get_emoticon_statistics(text)\n\n# Export to JSON (default format)\njson_file = export_analysis(stats, format=\"json\", filename=\"emoticon_stats.json\")\nprint(f\"Exported to: {json_file}\")\n\n# Export to CSV\ncsv_file = export_analysis(stats, format=\"csv\", filename=\"emoticon_stats.csv\")\nprint(f\"Exported to: {csv_file}\")\n\n# Export emotion profile\ntexts = [\"Happy :)\", \"Sad :(\", \"Excited :D\"]\nprofile = create_emotion_profile(texts, \"Sample Profile\")\nprofile_file = export_analysis(profile, format=\"json\", filename=\"emotion_profile.json\")\n\n# Auto-generate filename with timestamp\nauto_file = export_analysis(stats) # Creates: emoticon_analysis_YYYYMMDD_HHMMSS.json\n```\n\n### Export Formats\n\n**JSON Export**: Complete data structure with all metrics and metadata\n```json\n{\n \"total_emoticons\": 3,\n \"unique_emoticons\": 2,\n \"emoticon_density\": 12.5,\n \"emoticon_frequency\": {\":)\": 2, \":D\": 1},\n \"emotion_frequency\": {\"Smile\": 2, \"Laugh\": 1},\n \"sentiment_distribution\": {\"positive\": 3, \"negative\": 0, \"neutral\": 0},\n \"average_sentiment\": 0.8,\n \"dominant_emotion\": \"Smile\",\n \"analysis_timestamp\": \"2024-01-15T10:30:00\"\n}\n```\n\n**CSV Export**: Structured tabular format for spreadsheet analysis\n- Emoticon statistics with frequencies\n- Emotion breakdowns\n- Sentiment distributions\n- Compatible with Excel, Google Sheets, etc.\n\n## Examples\n\n### Basic Example\n```python\nfrom emoticon_fix import emoticon_fix\n\ntext = 'test :) test :D test'\nresult = emoticon_fix(text)\nprint(result) # Output: 'test Smile test Laugh test'\n```\n\n### Complex Example with Kaomoji\n```python\nfrom emoticon_fix import emoticon_fix\n\ntext = 'Feeling (\uff61\u2665\u203f\u2665\uff61) today! When things go wrong \u2517(\uff3e0\uff3e)\u2513 keep dancing!'\nresult = emoticon_fix(text)\nprint(result) # Output: 'Feeling In Love today! When things go wrong Dancing Joy keep dancing!'\n```\n\n### Mixed Emoticons Example\n```python\nfrom emoticon_fix import emoticon_fix\n\ntext = 'Western :) meets Eastern (\u25d5\u203f\u25d5\u273f) style!'\nresult = emoticon_fix(text)\nprint(result) # Output: 'Western Smile meets Eastern Sweet Smile style!'\n```\n\n### Removing Emoticons Example\n```python\nfrom emoticon_fix import remove_emoticons\n\ntext = 'This message :D contains some (\uff61\u2665\u203f\u2665\uff61) emoticons that need to be removed!'\nresult = remove_emoticons(text)\nprint(result) # Output: 'This message contains some emoticons that need to be removed!'\n```\n\n### NER-Friendly Tagging Example\n```python\nfrom emoticon_fix import replace_emoticons\n\n# Default format: __EMO_{tag}__\ntext = 'Happy customers :) are returning customers!'\nresult = replace_emoticons(text)\nprint(result) # Output: 'Happy customers __EMO_Smile__ are returning customers!'\n\n# Custom format\ntext = 'User feedback: Product was great :D but shipping was slow :('\nresult = replace_emoticons(text, tag_format=\"<EMOTION type='{tag}'>\")\nprint(result) # Output: 'User feedback: Product was great <EMOTION type='Laugh'> but shipping was slow <EMOTION type='Sad'>'\n```\n\n### Social Media Analysis Example\n```python\nfrom emoticon_fix import create_emotion_profile, compare_emotion_profiles, export_analysis\n\n# Analyze social media posts from different users\nuser1_posts = [\n \"Amazing product! :D Love it!\",\n \"Great customer service :)\",\n \"Highly recommended! (\uff61\u2665\u203f\u2665\uff61)\"\n]\n\nuser2_posts = [\n \"Product was okay :/\",\n \"Shipping was slow :(\",\n \"Could be better... :/\"\n]\n\nuser3_posts = [\n \"Mixed experience :) good product but :( bad delivery\",\n \"Happy with purchase :) but upset about delay :(\",\n \"Overall satisfied :) despite issues :/\"\n]\n\n# Create emotion profiles\nuser1_profile = create_emotion_profile(user1_posts, \"Satisfied Customer\")\nuser2_profile = create_emotion_profile(user2_posts, \"Dissatisfied Customer\")\nuser3_profile = create_emotion_profile(user3_posts, \"Mixed Customer\")\n\n# Compare profiles\ncomparison = compare_emotion_profiles([user1_profile, user2_profile, user3_profile])\n\n# Export results\nexport_analysis(comparison, format=\"json\", filename=\"customer_sentiment_analysis.json\")\n\nprint(\"Customer sentiment analysis completed!\")\nprint(f\"Satisfied customer sentiment: {user1_profile.get_overall_sentiment():.3f}\")\nprint(f\"Dissatisfied customer sentiment: {user2_profile.get_overall_sentiment():.3f}\")\nprint(f\"Mixed customer sentiment: {user3_profile.get_overall_sentiment():.3f}\")\n```\n\n### Time Series Analysis Example\n```python\nfrom emoticon_fix import get_emoticon_trends, export_analysis\n\n# Analyze emotional progression over time\nweekly_posts = [\n \"Week 1: Starting new job :) excited!\",\n \"Week 2: Learning lots :D challenging but fun!\",\n \"Week 3: Feeling overwhelmed :( too much work\",\n \"Week 4: Getting better :) finding my rhythm\",\n \"Week 5: Confident now :D loving the work!\",\n \"Week 6: Stress again :( big project deadline\",\n \"Week 7: Relief! :D Project completed successfully!\",\n \"Week 8: Balanced now :) happy with progress\"\n]\n\nweek_labels = [f\"Week {i+1}\" for i in range(len(weekly_posts))]\ntrends = get_emoticon_trends(weekly_posts, week_labels)\n\n# Export trend analysis\nexport_analysis(trends, format=\"json\", filename=\"emotional_journey.json\")\n\nprint(\"Emotional journey analysis:\")\nsentiment_trend = trends['trend_summary']['sentiment_trend']\nfor i, sentiment in enumerate(sentiment_trend):\n print(f\"Week {i+1}: {sentiment:.3f}\")\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Testing\n\nThe package includes a comprehensive test suite. To run the tests:\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2020 Xiangyu Gao\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A lightweight and efficient library for transforming emoticons into their semantic meanings with sentiment analysis capabilities",
"version": "0.2.4",
"project_urls": {
"Bug Tracker": "https://github.com/xga0/emoticon_fix/issues",
"Documentation": "https://github.com/xga0/emoticon_fix#readme",
"Homepage": "https://github.com/xga0/emoticon_fix",
"Repository": "https://github.com/xga0/emoticon_fix"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "78c54bec21f1636bd90bff21cf360ee60642d7f08ef13291209c043c8de9b911",
"md5": "29febd45fd5e71972dd37e7822ecacd3",
"sha256": "9ed843bc75cf6665ce0395bf50be4da06d5eceff95c1266d34d18a0ec30880b5"
},
"downloads": -1,
"filename": "emoticon_fix-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29febd45fd5e71972dd37e7822ecacd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 20780,
"upload_time": "2025-07-20T00:59:41",
"upload_time_iso_8601": "2025-07-20T00:59:41.357267Z",
"url": "https://files.pythonhosted.org/packages/78/c5/4bec21f1636bd90bff21cf360ee60642d7f08ef13291209c043c8de9b911/emoticon_fix-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "318e328a297bf5bc5479da9ff6dbb54af120cb437b993d3816b34f4e1e425c48",
"md5": "291c1bbd7a0e3e774bf0ad84b3eae29b",
"sha256": "255f0dec6176cf52693193309d0a63f1ffec03c525a8c4751b42bc976259c0a5"
},
"downloads": -1,
"filename": "emoticon_fix-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "291c1bbd7a0e3e774bf0ad84b3eae29b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 34425,
"upload_time": "2025-07-20T00:59:42",
"upload_time_iso_8601": "2025-07-20T00:59:42.521741Z",
"url": "https://files.pythonhosted.org/packages/31/8e/328a297bf5bc5479da9ff6dbb54af120cb437b993d3816b34f4e1e425c48/emoticon_fix-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 00:59:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xga0",
"github_project": "emoticon_fix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "emoticon-fix"
}
