emotion-algebra

A Python library for representing, reasoning about, and computing with emotion. It builds on the parts of affective science that replicate, and it is honest about the parts that do not.

from emotion_algebra import prototype, dominant

anger = prototype("anger")   # unpleasant, aroused, and IN CONTROL
fear  = prototype("fear")    # unpleasant, aroused, and NOT

dominant(anger.blend(fear, 0.5))
# 'distress'

Most emotion libraries would tell you that blend is neutrality: that anger and fear, being "opposites", cancel out. They do not, and this library does not say they do. Understanding why is most of what this library is about.

Install

pip install emotion-algebra

Requires Python 3.10+.

The 60-second version

An emotion is a point in a five-coordinate space:

from emotion_algebra import AffectState

AffectState(
    positivity=0.8,        # how good it feels          [0, 1]
    negativity=0.6,        # how bad it feels           [0, 1]   (yes, both at once)
    potency=0.3,           # how in-control you feel    [-1, 1]
    arousal=0.7,           # how activated you are      [0, 1]
    unpredictability=0.2,  # how unexpected it is       [0, 1]
)

Two things about that are unusual, and both are deliberate.

Positivity and negativity are separate. People genuinely feel good and bad at the same time. The classic case is graduation day. A single "valence" number cannot represent that. Two channels can.

graduation = AffectState(positivity=0.8, negativity=0.6, arousal=0.7)
graduation.valence      # +0.2  -- "mildly happy", says a one-axis model
graduation.ambivalence  #  0.6  -- what the one-axis model destroyed

Potency is the axis nobody ships. Anger and fear are both unpleasant and both highly aroused, so valence and arousal cannot tell them apart. What separates them is your sense of control. Anger is what you feel when something is wrong and you can act. Fear is what you feel when you can't.

That single axis is why this library exists, and it's the one thing you should take away.

What you can do with it

Name a feeling, with honest uncertainty

Emotion names are labels over regions, not coordinates. So the answer to "what emotion is this?" is a distribution, not a word.

from emotion_algebra import prototype, label, dominant, entropy

mixed = prototype("rage").blend(prototype("terror"), 0.5)

label(mixed, top_k=3)
# {'distress': 0.66, 'distraction': 0.19, 'apprehension': 0.15}

entropy(mixed)   # 3.91 bits -- it sits BETWEEN names, and says so
dominant(mixed)  # 'distress'   (the convenient answer; throws away the rest)

Work out what someone will do

Motivational direction tracks potency, not pleasantness. This is why "negative = avoid" sentiment systems get anger wrong: anger is unpleasant and approach-motivated.

from emotion_algebra import dominant_tendency

dominant_tendency(prototype("anger"))    # 'antagonism'  -- move against it
dominant_tendency(prototype("fear"))     # 'avoidance'   -- move away
dominant_tendency(prototype("sadness"))  # 'withdrawal'  -- give up
dominant_tendency(prototype("joy"))      # 'affiliation' -- draw close

Trust the direction. Prefer the distribution. "Anger approaches while being unpleasant" holds up well. It survives 100% of perturbations of every guessed coefficient in the library. But which mode wins the argmax does not hold up as well: anger → antagonism holds in only 55%, fear → avoidance in 52%, because approach and antagonism are neighboring readings of the same drive. Use action_readiness() (the full distribution) when the answer matters, and treat dominant_tendency() as the convenience it is. See the robustness report.

Go from an event to an emotion

Emotions are not triggered by events. They are triggered by your appraisal of events, and the appraisal checks map almost one-to-one onto the core's axes.

from emotion_algebra import Appraisal
from emotion_algebra.appraisal import appraisal_to_affect

# One obstructing event. Vary NOTHING but whether you can cope.
fight  = Appraisal(goal_relevance=0.9, goal_congruence=0.0, coping_potential=0.9)
flight = Appraisal(goal_relevance=0.9, goal_congruence=0.0, coping_potential=0.1)

dominant(appraisal_to_affect(fight))    # 'rage'
dominant(appraisal_to_affect(flight))   # 'fear'

Same event. Same unpleasantness. Coping decides whether you fight or flee.

Build an agent that has moods

Emotion decays toward a set point, not toward zero. "No emotion" is not a state anything is ever in. Resting is a mildly positive, calm, mildly-in-control place. That is why a creature at rest explores rather than freezing.

from emotion_algebra import SET_POINT, at_rest, relax, drive, ORIGIN

at_rest(ORIGIN)      # False -- the coordinate origin is NOT rest
at_rest(SET_POINT)   # True

# Recovery is a trajectory, not a switch:
#   terror -> fear -> apprehension -> acceptance
relax(prototype("terror"), dt=900, half_life=300)

drive(prototype("terror"))   # what must change to get home again
# {'negativity': -0.51, 'potency': +1.05, 'arousal': -0.47, ...}

drive() is the restoring force, the thing a needs-driven agent minimizes. A need deficit is a displacement from the set point, and the emotion is the felt signal of it.

Read the neurochemistry

from emotion_algebra import NeuroState

# Same threat. Only the coping chemistry differs.
NeuroState(noradrenaline=.95, cortisol=.95, dopamine=.15).to_affect()   # potency -0.77 -> fear
NeuroState(noradrenaline=.90, dopamine=.85, testosterone=.9).to_affect() # potency +0.86 -> approach

Neuromodulators are mapped to computational roles: dopamine as reward-prediction error, noradrenaline as unexpected uncertainty, not to emotion names. That is what makes it testable.

Convert to whatever your other tools speak

from emotion_algebra import convert, fidelity, explain_loss

convert(prototype("anger"), "core", "pad")    # (-0.62, 0.62, 0.60)
convert((-0.6, 0.8, 0.6), "pad", "core")      # -> AffectState

fidelity("hourglass", "pad")                  # Fidelity.HEURISTIC
print(explain_loss("circumplex", "core"))
# potency and unpredictability. This is why the circumplex cannot tell
# anger from fear: they differ on potency, and it has no potency axis.

Every model converts to every other. Every conversion tells you what it destroys. A conversion that loses information is fine. One that loses it silently is not.

The library grades its own claims

This is the feature we're proudest of, and we don't know of another library that has it.

Affective science does not speak with one voice. Some of the models in here are replicated across cultures and meta-analyses. One was published in a journal that did not practice external peer review. A library that presents them all in the same typeface is lying by omission.

So every construct carries a grade and its citation, in code:

from emotion_algebra import evidence

evidence.grade_of("circumplex")          # Grade.ESTABLISHED
evidence.grade_of("grid")                # Grade.SUPPORTED
evidence.grade_of("valence.bipolarity")  # Grade.CONTESTED   <- both readings shipped
evidence.grade_of("lovheim.cube")        # Grade.SPECULATIVE
evidence.grade_of("plutchik.antipodal")  # Grade.METAPHOR

print(evidence.report())                 # the whole table, with citations

If you think a grade is wrong, the citation is right there to argue with.

Is it still an algebra?

Yes, a better-specified one than it used to be.

The old claim was "vector space with negation": emotions add, scale, and every emotion has an opposite. That claim is false. It is what produced (rage + terror)/2 == calm.

What is actually true:

• (S, blend) is a barycentric algebra, a convex space. By Stone's theorem its models are exactly the convex subsets of vector spaces, so no rigor is lost. It just says precisely which subset. Closure comes free. Blending never needs clamping.
• (S, d) is a metric space.
• {relax_t} is a contraction semigroup, so by the Banach fixed-point theorem the set point is its unique attractor. Every state converges to rest, exponentially, from anywhere. That is a theorem, not a preference.

The supported operations are mixture, intensification, decay, and distance. There is no __neg__, __sub__, __add__ or __mul__, and tests assert their absence.

Sadness is not "minus joy." It has its own pull: withdraw, seek help. That is not "negative approach."

Full laws, with the ones that don't hold: docs/core-laws.md

Many models, honestly mapped

This library does not implement an emotion model. It implements several, each faithfully, to its own author's specification, grades them by evidence, and maps between them.

So if you came for joy + trust == love and -anger == fear, they're here, and they work:

from emotion_algebra.emotions import get_emotion
from emotion_algebra.feelings import get_feeling_from_emotions

anger = get_emotion("anger")
anger + 1                                   # rage
-anger                                      # fear   (Plutchik's "opposite")
get_feeling_from_emotions("joy", "trust")   # 'love'

That arithmetic is correct for Plutchik's model. Plutchik's model is not correct about people. Anger and fear are neighbors, not opposites. Both things are true, and the library tells you both: the wheel is graded METAPHOR, and the core has no __neg__.

Use the wheel to talk. Use the core to compute. Convert between them with a map that says what it costs.

docs/models.md has the full catalog.

Documentation

New here? Read them in this order.

Validation

The claims above are tested, and the tests are in the repo, including the ones that went against us.

Scripts in scripts/validate/. The honest limits of each are written into the script that produces it.

License

Apache-2.0.