thanatoz-1 / emotionstimuli

Emotion role labeling made easy with HMM and transformers.

Emotion Stimuli

---

For a detailed documentation of the project, refer our documentations.

Emotion classification in text has wide array of applications which include sentiment tracking targetted towards politicians, movies, products, companies, identifying the emotion behind a newspaper headline etc. With the rapid proliferation of text based information processing and a number of social-media websites, there has been a increasing amount of emotion analysis and information mining for researched on newly available datasets. However, historical works has only been focusing solely on detecting certain emotion ignoring questions such as ‘who feels the emotion? (Experiencer)’, 'towards whom the emotion is directed (Stimulus)?’, 'what provokes the emotion? (Cue)' and 'what is the cause of emotion? (Cause)'. This project has been targeted around the same task using a number of cues for identification of the stated spans. Have a look at the stated sentence below:

Installing the package

If you are running a linux machine with pip installed, then you can install the EmotionStimuli package using pip.

pip install .

In case if you have not installed pip or are facing trouble installing using git, you can install EmotionStimuli package using the provided setup.py

python setup.py install

Using the package

Once the package has been installed, you can call the package as follows for one particular emotion role. In this case, the role is "cause":

from emotion import HMM

hmm = HMM("cause")

The model heavily relies on the structure of Brown dataset and so, we have also added the required respective classes for appropriate conversion which could be imported as follows:

from emotion.utils import Data

# Using the Data class
gne_all = Data(
    filename="data/dataset.json",
    roles=["experiencer", "target", "cue", "cause"],
    corpora=["gne"],
    splits=[0.8, 0.2],
)

gne_all.conv2brown()

The Data class can also be used to create dataset splits which could further be used to create various splits in the datasets for training, validation and testing.

One end to end training of a dataset is provided below for reference.

from emotion import Data, Dataset, HMM, Evaluation

intended_corpus = "gne"
intended_role = "experiencer"

# Load data from input file.
# Only load annotations for the emotion role "experiencer" from the "GNE" corpus.
# Split the data into two subsets, containing 80% and 20% of the total instances respectively (randomly selected).
gne_exp = Data(
    filename="data/dataset.json",
    roles=[intended_role],
    corpora=[intended_corpus],
    splits=[0.8, 0.2],
)

# Convert the loaded annoations to Brown-format.
gne_exp.conv2brown()

# Store the instances of a specific subset in the Dataset object.
# Each instance is stored as an Instance object, featuring attributes for 
# tokens as well as gold and predicted annotations.
train_gne = Dataset(data=gne_exp, splt=0)
test_gne = Dataset(data=gne_exp, splt=1)

# Train the HMM model for the intended emotion role.
model_exp_gne = HMM(intended_role)
model_exp_gne.train(dataset=train_gne)

# Predict the annotations for the intended role using the previously trained model.
model_exp_gne.predictDataset(dataset=test_gne)

# Evaluate the model and save the results.
# A prediction evaluates only to a TP if the Jaccard score of the predicted and
# the gold span is above the threshold of 0.8.
# The parameter beta for calculating the f-score is set to 1.0.
results = Evaluation(dataset=test, role=intended_role, threshold=0.8, beta=1.0)
results.save_eval(eval_name="gne_exp", filename="output.json")

# Additionally, save a detailed documentation of how
# the evaluation was calculated.
results.save_doc(filename="documentation.json")

Overview of our Baseline Framework

Results

Baseline Approach

Detailed documentations

You can find the detailed documentations here.

How to contribute

Please adhere to the following steps in order to contribute to the project. The project uses pep8 styling guidelines for the entire codebase. Apart from that, the code is strictly formatted with black version 21.5b1, please make sure to use the same formatter with your code to get your code accepted.

References

1. Oberländer, Laura Ana Maria and Klinger, Roman; Token Sequence Labeling vs. latest Classification for {E}nglish Emotion Stimulus Detection; Proceedings of the Ninth Joint Conference on Lexical and Computational Semantics, Dec 2020; Association for Computational Linguistics
2. Mohammad, Saif and Zhu, Xiaodan and Martin, Joel; Semantic Role Labeling of Emotions in Tweets; Proceedings of the 5th Workshop on Computational Approaches to Subjectivity, Sentiment and Social Media Analysis; Jun 2014; Association for Computational Linguistics.