# pyemotionwheel
`pyemotionwheel` is a Python library that provides a programmatic interface to an emotion wheel, a simple psychological tool for identifying and articulating emotions.
The library models an emotion wheel as a hierarchical tree structure, with primary emotions at its core and more nuanced secondary and tertiary emotions branching out.
This tool can be especially beneficial in therapeutic settings, educational environments, and personal development for enhancing emotional intelligence.
## Why does pyemotionwheel exist?
In the realm of psychology, identifying and articulating emotions is an essential step towards understanding and managing them effectively.
**My bond with the emotion wheel is also _deeply personal._**
Surviving a near-fatal car accident at 13 years old, combined with growing up in a broken home, led to my emotions shutting down to cope with the trauma and ensuing family turmoil.
Two decades later, I began to unlock those surpressed emotions.
**The emotion wheel, a seemingly simple tool, proved crucial for me to identify and express my feelings, enhancing my emotional literacy.**
As a developer, I felt called to create an open source implementaiton of the emotion wheel that myself and other programmers can utilize in their own projects.
## Installation
You can install `pyemotionwheel` and its dependencies using `pip`:
```shell
$ pip install pyemotionwheel anytree
```
The only dependency is [anytree](https://anytree.readthedocs.io/en/latest/), a simple, lightweight implementation of a [Tree](https://en.wikipedia.org/wiki/Tree_(data_structure)) data structure. Since an emotion wheel is effectively just a hierarchical representation of emotions, a Tree data structure can naturally be used.
## Usage
Here's how to utilize each of the public methods in the `EmotionWheel` class, along with a few common use patterns.
### Instantiate the emotion wheel
Instantiate an instance of the emotion wheel, then show the tree structure:
```python
>> > from pyemotionwheel import BasicEmotionWheel
>> > wheel = BasicEmotionWheel()
>> > print(wheel)
root
├── Anger
│ ├── Rage
│ │ ├── Hate
│ │ └── Hostile
│ ├── Exasperated
│ │ ├── Agitated
│ │ └── Frustrated
│ ├── Irritable
│ │ ├── Annoyed
│ │ └── Aggravated
│ ├── Envy
│ │ ├── Resentful
│ │ └── Jealous
│ └── Disgust
│ ├── Contempt
│ └── Revolted
├── Sadness
│ ├── Suffering
│ │ ├── Agony
│ │ └── Hurt
│ ├── Despondent
│ │ ├── Depression
│ │ └── Sorrow
│ ├── Disappointed
│ │ ├── Dismayed
│ │ └── Displeased
│ ├── Shameful
│ │ ├── Regretful
│ │ └── Guilty
│ ├── Neglected
│ │ ├── Isolated
│ │ └── Lonely
│ └── Despair
│ ├── Grief
│ └── Powerless
├── Surprise
│ ├── Stunned
│ │ ├── Shocked
│ │ └── Dismayed
│ ├── Confused
│ │ ├── Disillusioned
│ │ └── Perplexed
│ ├── Amazed
│ │ ├── Astonished
│ │ └── Awe - struck
│ ├── Overcome
│ │ ├── Speechless
│ │ └── Astounded
│ └── Moved
│ ├── Stimulated
│ └── Touched
├── Joy
│ ├── Content
│ │ ├── Pleased
│ │ └── Satisfied
│ ├── Happy
│ │ ├── Amused
│ │ └── Delighted
│ ├── Cheerful
│ │ ├── Jovial
│ │ └── Blissful
│ ├── Proud
│ │ ├── Triumphant
│ │ └── Illustrious
│ ├── Optimistic
│ │ ├── Eager
│ │ └── Hopeful
│ ├── Enthusiastic
│ │ ├── Excited
│ │ └── Zeal
│ ├── Elation
│ │ ├── Euphoric
│ │ └── Jubilation
│ └── Enthralled
│ ├── Enchanted
│ └── Rapture
├── Love
│ ├── Affectionate
│ │ ├── Fondness
│ │ └── Romantic
│ ├── Longing
│ │ ├── Sentimental
│ │ └── Attracted
│ ├── Desire
│ │ ├── Passion
│ │ └── Infatuation
│ ├── Tenderness
│ │ ├── Caring
│ │ └── Compassionate
│ └── Peaceful
│ ├── Relieved
│ └── Satisfied
└── Fear
├── Sacred
│ ├── Frightened
│ └── Helpless
├── Terror
│ ├── Panic
│ └── Hysterical
├── Insecure
│ ├── Inferior
│ └── Inadequate
├── Nervous
│ ├── Worried
│ └── Anxious
└── Horror
├── Mortified
└── Dread
```
### All emotions
To get _all_ emotions present in the tree, ignoring any hierachical structure:
```python
>>> wheel.all_emotions()
(EmotionNode(name='Anger'),
EmotionNode(name='Rage'),
EmotionNode(name='Hate'),
EmotionNode(name='Hostile'),
EmotionNode(name='Exasperated'),
EmotionNode(name='Agitated'),
EmotionNode(name='Frustrated'),
EmotionNode(name='Irritable'),
EmotionNode(name='Annoyed'),
...
```
### Primary emotions
Retrieve all primary emotions (i.e., first level of the wheel):
```python
>>> wheel.primary_emotions()
(EmotionNode(name='Anger'),
EmotionNode(name='Sadness'),
EmotionNode(name='Surprise'),
EmotionNode(name='Joy'),
EmotionNode(name='Love'),
EmotionNode(name='Fear'))
```
### Secondary emotions
Retrieve all secondary eotions (i.e., second level of the wheel):
```python
>>> wheel.secondary_emotions()
(EmotionNode(name='Rage'),
EmotionNode(name='Exasperated'),
EmotionNode(name='Irritable'),
EmotionNode(name='Envy'),
EmotionNode(name='Disgust'),
EmotionNode(name='Suffering'),
...
```
### Tertiary emotions
Retrieve all tertiery emotions (i.e., third and final level of the wheel):
```python
>>> wheel.tertiary_emotions()
(EmotionNode(name='Hate'),
EmotionNode(name='Hostile'),
EmotionNode(name='Agitated'),
EmotionNode(name='Frustrated'),
EmotionNode(name='Annoyed'),
...
```
### Find a specific emotion
You can lookup a specific emotion in the wheel by supplying the `name` of the emotion:
```python
>>> wheel.find_emotion("excited")
EmotionNode(name='Excited')
```
### Get the path of an EmotionNode back to the root
We can better understand the composition of an emotion by tracing it back to its root:
```python
>>> compassionate = wheel.find_emotion("Compassionate")
>>> compassionate.path[::-1]
(EmotionNode(name='Compassionate'),
EmotionNode(name='Tenderness'),
EmotionNode(name='Love'),
EmotionNode(name='root'))
```
The tertiary emotion, _"Compassionate"_, consists of _"Tenderness"_ as the secondary emotion, and finally _"Love"_ as the primary emotion.
### Get all children of an EmotionNode
To understand how a parent emotion can be decomposed into its potential child emotions, we can inspect the `children` of a given `EmotionNode`:
```python
>>> nervous = wheel.find_emotion("Nervous")
>>> nervous.children
(EmotionNode(name='Worried'), EmotionNode(name='Anxious'))
```
The _"Nervous"_ secondary emotion has two associated tertiary emotions: _"Worried"_ and _"Anxious"_.
## Future work
- Create a sunburst-like visualization for the `BasicEmotionWheel` class. Something similar to [plotly's implementation](https://plotly.com/python/sunburst-charts/) would be great, but maybe use matplotlib instead?
- Implement a `PlutchikEmotionWheel` class, based on the work of [Robert Plutchik](https://en.wikipedia.org/wiki/Robert_Plutchik). [@alfonsosemeraro](https://github.com/alfonsosemeraro) has a [fantastic implementation](https://github.com/alfonsosemeraro/pyplutchik) that can likely be extended for my particular uses.
## License
`pyemotionwheel` is released under the MIT License. This means it is free to use, modify, and distribute, including for commercial use, provided the license and copyright notice are preserved.
Raw data
{
"_id": null,
"home_page": "https://github.com/jrosebr1/pyemotionwheel",
"name": "pyemotionwheel",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "emotion wheel,psychological tool,emotion identification,emotional intelligence,therapeutic tool,education,personal development,emotional articulation,emotional literacy,emotional hierarchy",
"author": "Adrian Rosebrock",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/21/8b/bd2fa1358ed6066f40e7721e58bd3463cd39dde4c6c40e946753791467ff/pyemotionwheel-0.1.0.tar.gz",
"platform": null,
"description": "# pyemotionwheel\n\n\n\n`pyemotionwheel` is a Python library that provides a programmatic interface to an emotion wheel, a simple psychological tool for identifying and articulating emotions.\n\nThe library models an emotion wheel as a hierarchical tree structure, with primary emotions at its core and more nuanced secondary and tertiary emotions branching out.\n\nThis tool can be especially beneficial in therapeutic settings, educational environments, and personal development for enhancing emotional intelligence.\n\n## Why does pyemotionwheel exist?\n\nIn the realm of psychology, identifying and articulating emotions is an essential step towards understanding and managing them effectively.\n\n**My bond with the emotion wheel is also _deeply personal._**\n\nSurviving a near-fatal car accident at 13 years old, combined with growing up in a broken home, led to my emotions shutting down to cope with the trauma and ensuing family turmoil.\n\nTwo decades later, I began to unlock those surpressed emotions.\n\n**The emotion wheel, a seemingly simple tool, proved crucial for me to identify and express my feelings, enhancing my emotional literacy.**\n\nAs a developer, I felt called to create an open source implementaiton of the emotion wheel that myself and other programmers can utilize in their own projects.\n\n## Installation\n\nYou can install `pyemotionwheel` and its dependencies using `pip`:\n\n```shell\n$ pip install pyemotionwheel anytree\n```\n\nThe only dependency is [anytree](https://anytree.readthedocs.io/en/latest/), a simple, lightweight implementation of a [Tree](https://en.wikipedia.org/wiki/Tree_(data_structure)) data structure. Since an emotion wheel is effectively just a hierarchical representation of emotions, a Tree data structure can naturally be used.\n\n## Usage\n\nHere's how to utilize each of the public methods in the `EmotionWheel` class, along with a few common use patterns.\n\n### Instantiate the emotion wheel\n\nInstantiate an instance of the emotion wheel, then show the tree structure:\n\n```python\n>> > from pyemotionwheel import BasicEmotionWheel\n>> > wheel = BasicEmotionWheel()\n>> > print(wheel)\nroot\n\u251c\u2500\u2500 Anger\n\u2502 \u251c\u2500\u2500 Rage\n\u2502 \u2502 \u251c\u2500\u2500 Hate\n\u2502 \u2502 \u2514\u2500\u2500 Hostile\n\u2502 \u251c\u2500\u2500 Exasperated\n\u2502 \u2502 \u251c\u2500\u2500 Agitated\n\u2502 \u2502 \u2514\u2500\u2500 Frustrated\n\u2502 \u251c\u2500\u2500 Irritable\n\u2502 \u2502 \u251c\u2500\u2500 Annoyed\n\u2502 \u2502 \u2514\u2500\u2500 Aggravated\n\u2502 \u251c\u2500\u2500 Envy\n\u2502 \u2502 \u251c\u2500\u2500 Resentful\n\u2502 \u2502 \u2514\u2500\u2500 Jealous\n\u2502 \u2514\u2500\u2500 Disgust\n\u2502 \u251c\u2500\u2500 Contempt\n\u2502 \u2514\u2500\u2500 Revolted\n\u251c\u2500\u2500 Sadness\n\u2502 \u251c\u2500\u2500 Suffering\n\u2502 \u2502 \u251c\u2500\u2500 Agony\n\u2502 \u2502 \u2514\u2500\u2500 Hurt\n\u2502 \u251c\u2500\u2500 Despondent\n\u2502 \u2502 \u251c\u2500\u2500 Depression\n\u2502 \u2502 \u2514\u2500\u2500 Sorrow\n\u2502 \u251c\u2500\u2500 Disappointed\n\u2502 \u2502 \u251c\u2500\u2500 Dismayed\n\u2502 \u2502 \u2514\u2500\u2500 Displeased\n\u2502 \u251c\u2500\u2500 Shameful\n\u2502 \u2502 \u251c\u2500\u2500 Regretful\n\u2502 \u2502 \u2514\u2500\u2500 Guilty\n\u2502 \u251c\u2500\u2500 Neglected\n\u2502 \u2502 \u251c\u2500\u2500 Isolated\n\u2502 \u2502 \u2514\u2500\u2500 Lonely\n\u2502 \u2514\u2500\u2500 Despair\n\u2502 \u251c\u2500\u2500 Grief\n\u2502 \u2514\u2500\u2500 Powerless\n\u251c\u2500\u2500 Surprise\n\u2502 \u251c\u2500\u2500 Stunned\n\u2502 \u2502 \u251c\u2500\u2500 Shocked\n\u2502 \u2502 \u2514\u2500\u2500 Dismayed\n\u2502 \u251c\u2500\u2500 Confused\n\u2502 \u2502 \u251c\u2500\u2500 Disillusioned\n\u2502 \u2502 \u2514\u2500\u2500 Perplexed\n\u2502 \u251c\u2500\u2500 Amazed\n\u2502 \u2502 \u251c\u2500\u2500 Astonished\n\u2502 \u2502 \u2514\u2500\u2500 Awe - struck\n\u2502 \u251c\u2500\u2500 Overcome\n\u2502 \u2502 \u251c\u2500\u2500 Speechless\n\u2502 \u2502 \u2514\u2500\u2500 Astounded\n\u2502 \u2514\u2500\u2500 Moved\n\u2502 \u251c\u2500\u2500 Stimulated\n\u2502 \u2514\u2500\u2500 Touched\n\u251c\u2500\u2500 Joy\n\u2502 \u251c\u2500\u2500 Content\n\u2502 \u2502 \u251c\u2500\u2500 Pleased\n\u2502 \u2502 \u2514\u2500\u2500 Satisfied\n\u2502 \u251c\u2500\u2500 Happy\n\u2502 \u2502 \u251c\u2500\u2500 Amused\n\u2502 \u2502 \u2514\u2500\u2500 Delighted\n\u2502 \u251c\u2500\u2500 Cheerful\n\u2502 \u2502 \u251c\u2500\u2500 Jovial\n\u2502 \u2502 \u2514\u2500\u2500 Blissful\n\u2502 \u251c\u2500\u2500 Proud\n\u2502 \u2502 \u251c\u2500\u2500 Triumphant\n\u2502 \u2502 \u2514\u2500\u2500 Illustrious\n\u2502 \u251c\u2500\u2500 Optimistic\n\u2502 \u2502 \u251c\u2500\u2500 Eager\n\u2502 \u2502 \u2514\u2500\u2500 Hopeful\n\u2502 \u251c\u2500\u2500 Enthusiastic\n\u2502 \u2502 \u251c\u2500\u2500 Excited\n\u2502 \u2502 \u2514\u2500\u2500 Zeal\n\u2502 \u251c\u2500\u2500 Elation\n\u2502 \u2502 \u251c\u2500\u2500 Euphoric\n\u2502 \u2502 \u2514\u2500\u2500 Jubilation\n\u2502 \u2514\u2500\u2500 Enthralled\n\u2502 \u251c\u2500\u2500 Enchanted\n\u2502 \u2514\u2500\u2500 Rapture\n\u251c\u2500\u2500 Love\n\u2502 \u251c\u2500\u2500 Affectionate\n\u2502 \u2502 \u251c\u2500\u2500 Fondness\n\u2502 \u2502 \u2514\u2500\u2500 Romantic\n\u2502 \u251c\u2500\u2500 Longing\n\u2502 \u2502 \u251c\u2500\u2500 Sentimental\n\u2502 \u2502 \u2514\u2500\u2500 Attracted\n\u2502 \u251c\u2500\u2500 Desire\n\u2502 \u2502 \u251c\u2500\u2500 Passion\n\u2502 \u2502 \u2514\u2500\u2500 Infatuation\n\u2502 \u251c\u2500\u2500 Tenderness\n\u2502 \u2502 \u251c\u2500\u2500 Caring\n\u2502 \u2502 \u2514\u2500\u2500 Compassionate\n\u2502 \u2514\u2500\u2500 Peaceful\n\u2502 \u251c\u2500\u2500 Relieved\n\u2502 \u2514\u2500\u2500 Satisfied\n\u2514\u2500\u2500 Fear\n\u251c\u2500\u2500 Sacred\n\u2502 \u251c\u2500\u2500 Frightened\n\u2502 \u2514\u2500\u2500 Helpless\n\u251c\u2500\u2500 Terror\n\u2502 \u251c\u2500\u2500 Panic\n\u2502 \u2514\u2500\u2500 Hysterical\n\u251c\u2500\u2500 Insecure\n\u2502 \u251c\u2500\u2500 Inferior\n\u2502 \u2514\u2500\u2500 Inadequate\n\u251c\u2500\u2500 Nervous\n\u2502 \u251c\u2500\u2500 Worried\n\u2502 \u2514\u2500\u2500 Anxious\n\u2514\u2500\u2500 Horror\n\u251c\u2500\u2500 Mortified\n\u2514\u2500\u2500 Dread\n```\n\n### All emotions\n\nTo get _all_ emotions present in the tree, ignoring any hierachical structure:\n\n```python\n>>> wheel.all_emotions()\n(EmotionNode(name='Anger'),\n EmotionNode(name='Rage'),\n EmotionNode(name='Hate'),\n EmotionNode(name='Hostile'),\n EmotionNode(name='Exasperated'),\n EmotionNode(name='Agitated'),\n EmotionNode(name='Frustrated'),\n EmotionNode(name='Irritable'),\n EmotionNode(name='Annoyed'),\n...\n```\n\n### Primary emotions\n\nRetrieve all primary emotions (i.e., first level of the wheel):\n\n```python\n>>> wheel.primary_emotions()\n(EmotionNode(name='Anger'),\n EmotionNode(name='Sadness'),\n EmotionNode(name='Surprise'),\n EmotionNode(name='Joy'),\n EmotionNode(name='Love'),\n EmotionNode(name='Fear'))\n```\n\n### Secondary emotions\n\nRetrieve all secondary eotions (i.e., second level of the wheel):\n\n```python\n>>> wheel.secondary_emotions()\n(EmotionNode(name='Rage'),\n EmotionNode(name='Exasperated'),\n EmotionNode(name='Irritable'),\n EmotionNode(name='Envy'),\n EmotionNode(name='Disgust'),\n EmotionNode(name='Suffering'),\n...\n```\n\n### Tertiary emotions\n\nRetrieve all tertiery emotions (i.e., third and final level of the wheel):\n\n```python\n>>> wheel.tertiary_emotions()\n(EmotionNode(name='Hate'),\n EmotionNode(name='Hostile'),\n EmotionNode(name='Agitated'),\n EmotionNode(name='Frustrated'),\n EmotionNode(name='Annoyed'),\n...\n```\n\n### Find a specific emotion\n\nYou can lookup a specific emotion in the wheel by supplying the `name` of the emotion:\n\n```python\n>>> wheel.find_emotion(\"excited\")\nEmotionNode(name='Excited')\n```\n\n### Get the path of an EmotionNode back to the root\n\nWe can better understand the composition of an emotion by tracing it back to its root:\n\n```python\n>>> compassionate = wheel.find_emotion(\"Compassionate\")\n>>> compassionate.path[::-1]\n(EmotionNode(name='Compassionate'),\n EmotionNode(name='Tenderness'),\n EmotionNode(name='Love'),\n EmotionNode(name='root'))\n```\n\nThe tertiary emotion, _\"Compassionate\"_, consists of _\"Tenderness\"_ as the secondary emotion, and finally _\"Love\"_ as the primary emotion.\n\n### Get all children of an EmotionNode\n\nTo understand how a parent emotion can be decomposed into its potential child emotions, we can inspect the `children` of a given `EmotionNode`:\n\n```python\n>>> nervous = wheel.find_emotion(\"Nervous\")\n>>> nervous.children\n(EmotionNode(name='Worried'), EmotionNode(name='Anxious'))\n```\n\nThe _\"Nervous\"_ secondary emotion has two associated tertiary emotions: _\"Worried\"_ and _\"Anxious\"_.\n\n## Future work\n\n- Create a sunburst-like visualization for the `BasicEmotionWheel` class. Something similar to [plotly's implementation](https://plotly.com/python/sunburst-charts/) would be great, but maybe use matplotlib instead?\n- Implement a `PlutchikEmotionWheel` class, based on the work of [Robert Plutchik](https://en.wikipedia.org/wiki/Robert_Plutchik). [@alfonsosemeraro](https://github.com/alfonsosemeraro) has a [fantastic implementation](https://github.com/alfonsosemeraro/pyplutchik) that can likely be extended for my particular uses.\n\n## License\n\n`pyemotionwheel` is released under the MIT License. This means it is free to use, modify, and distribute, including for commercial use, provided the license and copyright notice are preserved.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python library providing a programmatic interface to an emotion wheel, a simple psychological tool for identifying and articulating emotions.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/jrosebr1/pyemotionwheel#README",
"Homepage": "https://github.com/jrosebr1/pyemotionwheel",
"Source": "https://github.com/jrosebr1/pyemotionwheel",
"Tracker": "https://github.com/jrosebr1/pyemotionwheel/issues"
},
"split_keywords": [
"emotion wheel",
"psychological tool",
"emotion identification",
"emotional intelligence",
"therapeutic tool",
"education",
"personal development",
"emotional articulation",
"emotional literacy",
"emotional hierarchy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "218bbd2fa1358ed6066f40e7721e58bd3463cd39dde4c6c40e946753791467ff",
"md5": "21c4906c67090a3a5221efbab637350e",
"sha256": "f0b0468152da240ae4c442db381132b127c3e0e7fb8f2101dd27f40d05dc5356"
},
"downloads": -1,
"filename": "pyemotionwheel-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "21c4906c67090a3a5221efbab637350e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11068,
"upload_time": "2023-11-06T22:04:55",
"upload_time_iso_8601": "2023-11-06T22:04:55.228431Z",
"url": "https://files.pythonhosted.org/packages/21/8b/bd2fa1358ed6066f40e7721e58bd3463cd39dde4c6c40e946753791467ff/pyemotionwheel-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 22:04:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jrosebr1",
"github_project": "pyemotionwheel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pyemotionwheel"
}
JSON
