Examples & Applications

Practical examples showing poisson-topicmodels in action.

The examples/ directory in the repository contains complete, runnable examples.

Example Scripts

01_getting_started.py

Basic workflow: load data, train model, interpret results.

Level: Beginner Time: ~5 minutes

Topics: - Creating synthetic data - Training PF model - Extracting and displaying topics - Basic interpretation

02_spf_keywords.py

Guided topic discovery with keyword priors.

Level: Intermediate Time: ~10 minutes

Topics: - Defining seed words - Training SPF model - Seed strength parameter - Comparing with unsupervised PF

03_cpf_covariates.py

Modeling topic variation by document metadata.

Level: Intermediate Time: ~10 minutes

Topics: - Document covariates - Training CPF model - Analyzing covariate effects - Interpretation

04_advanced_cspf.py

Combining seeds and covariates.

Level: Advanced Time: ~15 minutes

Topics: - Complex model setup - Multiple features - Advanced analysis

Running Examples

From command line:

cd examples
python 01_getting_started.py
python 02_spf_keywords.py
# etc.

In Jupyter (recommended):

cd examples
jupyter notebook run_topicmodels.ipynb

Example Notebooks

run_topicmodels.ipynb

Interactive notebook covering:

  • Data preparation

  • Model training

  • Visualization

  • All model types

  • Interpretation techniques

Open with Jupyter:

jupyter notebook examples/run_topicmodels.ipynb

Use this for learning and experimentation!

Custom Examples

Want to create your own example?

Checklist:

  1. Clear problem statement

  2. Realistic data

  3. Step-by-step code

  4. Results interpretation

  5. Key insights highlighted

Template:

"""
Example: [Clear title describing what it does]

This example demonstrates:
- Point 1
- Point 2
- Point 3
"""

import numpy as np
from poisson_topicmodels import [Model]

# 1. Data preparation
# ... load/create data

# 2. Model setup
model = [Model](...)

# 3. Training
model.train_step(...)

# 4. Analysis
model.summary()
top_words = model.return_top_words_per_topic(n=10)

# 5. Interpretation
# ... discuss findings

Applications

Real-world use cases where poisson-topicmodels excels:

Political Analysis

Ideal for legislative or political discourse analysis.

Topics: - Bill text analysis - Speech topic discovery - Ideal point estimation (TBIP) - Political polarization measurement

Social Media Analysis

Understand trending topics and discourse.

Topics: - Tweet topic discovery - Hashtag grouping - User position estimation (TBIP) - Discourse evolution

Academic Research

Explore research literature and trends.

Topics: - Paper topic discovery - Literature reviews - Research trend analysis - Cross-discipline connections

Business & Marketing

Customer and product insights from text.

Topics: - Customer review analysis - Product feedback grouping - Sentiment-topic combinations - Market trend discovery

News & Media

Content understanding and organization.

Topics: - News story classification - Event detection - Editorial stance analysis - Content trends

Computational Social Science

Complex human behavior through language.

Topics: - Cultural evolution - Identity discourse - Value mapping - Belief structure

Using Examples as Templates

Each example uses a standard pattern you can adapt:

# 1. Load/create data (copy from example)
counts = load_counts()
vocab = load_vocab()

# 2. Initialize model (adapt parameters)
model = PF(counts=counts, vocab=vocab, num_topics=20, batch_size=32)

# 3. Train (tune hyperparameters)
params = model.train_step(num_steps=200, lr=0.01, random_seed=42)

# 4. Analyze (customize based on task)
model.summary()
top_words = model.return_top_words_per_topic(n=10)
# ... more analysis

Next Steps

  • Run an example: Start with 01_getting_started.py

  • Try in notebook: Open run_topicmodels.ipynb

  • Create your own: Adapt template for your problem

  • Learn more: See Fundamentals for theory

  • Solve problems: Check How-To Guides for recipes

Contributing Examples

Want to share an example?

Process:

  1. Create a clear, documented script or notebook

  2. Include comments explaining each step

  3. Use realistic data (or explain synthetic data generation)

  4. Test that it runs without errors

  5. Submit as pull request to examples/

See Contributing Guide for contribution guidelines.

File Organization

examples/
├── 01_getting_started.py       # Beginner
├── 02_spf_keywords.py          # Intermediate
├── 03_cpf_covariates.py        # Intermediate
├── 04_advanced_cspf.py         # Advanced
├── run_topicmodels.ipynb       # Interactive
└── README.md                   # This file

Quick Reference

Script

Level

Duration

01_getting_started

Beginner

5 min

02_spf_keywords

Intermediate

10 min

03_cpf_covariates

Intermediate

10 min

04_advanced_cspf

Advanced

15 min

run_topicmodels

Interactive

Variable

Support

  • Issues with examples? Open GitHub issue

  • Have an example idea? Suggest in discussions

  • Want to contribute? See contribution guide