Quick Start

Install from PyPI:

pip install moodswing

For spaCy support (optional):

pip install moodswing
python -m spacy download en_core_web_sm

Example: Analyze a Novel

from moodswing import (
    DictionarySentimentAnalyzer,
    Sentencizer,
    DCTTransform,
    prepare_trajectory,
    plot_trajectory,
)
from moodswing.data import load_sample_text

# Load a sample novel
doc_id, text = load_sample_text("madame_bovary")

# Split into sentences
sentences = Sentencizer().split(text)

# Score each sentence
analyzer = DictionarySentimentAnalyzer()
scores = analyzer.sentence_scores(sentences, method="syuzhet")

# Create smoothed trajectory
trajectory = prepare_trajectory(
    scores,
    rolling_window=int(len(scores) * 0.1),
    dct_transform=DCTTransform(low_pass_size=10, output_length=200, scale_range=True)
)

# Plot the emotional arc
plot_trajectory(trajectory, title="Madame Bovary: Sentiment Trajectory")

Features

Four Sentiment Lexicons

• Syuzhet: Optimized for narrative analysis

• AFINN: Includes slang and informal language

• Bing: Binary positive/negative classification

• NRC: Multi-dimensional emotions (joy, fear, anger, etc.) with multilingual support

Two Analysis Approaches

• Dictionary-based: Fast, transparent word lookup

• spaCy-based: Context-aware neural models (handles negation, sarcasm)

Advanced Smoothing

• Rolling mean: Local trend smoothing

• DCT (Discrete Cosine Transform): Reveals overall narrative shape

• Compatible with R’s syuzhet package for reproducible research

Flexible Visualization

• Built-in plotting with customizable colors and components

• Export to pandas DataFrame for seaborn, plotly, or custom plots

• Publication-ready output with figure size/DPI control

Documentation

Full documentation with tutorials, examples, and API reference:

📖 https://browndw.github.io/moodswing/

• Get Started: Complete walkthrough with scholarly background

• Using Sentiment Lexicons: Compare and choose the right dictionary

• Using spaCy: Context-aware analysis with neural models

• Visualization Guide: Custom plotting and styling

• Examples Gallery: Ready-to-use code for common tasks

• Technical Notes: DCT mathematics and R compatibility

• API Reference: Complete function documentation

Citation

If you use this package in your research, please cite:

@software{moodswing2025,
  author = {Brown, David},
  title = {moodswing: Sentiment Trajectory Analysis for Python},
  year = {2025},
  url = {https://github.com/browndw/moodswing}
}

This package is based on Matthew Jockers’ syuzhet R package:

@article{jockers2015syuzhet,
  title={Revealing sentiment and plot arcs with the Syuzhet package},
  author={Jockers, Matthew L},
  year={2015}
}

License

Code licensed under MIT License.

See LICENSE file.