# Word Cloud for Personality Traits - Usage Example

This example shows how to use the `create_traits_wordcloud` function to visualize the most prominent personality traits from survey data.

## Basic Usage in Jupyter/Marimo Notebook

```python
from utils import QualtricsSurvey, create_traits_wordcloud
from pathlib import Path

# Load your survey data
RESULTS_FILE = "data/exports/1-23-26/JPMC_Chase Brand Personality_Quant Round 1_January 23, 2026_Labels.csv"
QSF_FILE = "data/19-dec_V1_quant_incl_shani_comments.qsf"

S = QualtricsSurvey(RESULTS_FILE, QSF_FILE)
data = S.load_data()

# Get Top 3 Traits data
top3_traits = S.get_top_3_traits(data)[0]

# Create and display word cloud
fig = create_traits_wordcloud(
    data=top3_traits,
    column='Top_3_Traits',
    title="Most Prominent Personality Traits",
    fig_save_dir='figures',  # Will save to figures/All_Respondents/
    filter_slug='All_Respondents'
)

# Display in notebook
fig  # or plt.show()
```

## With Active Filters

If you're using the survey filter methods, you can pass the filter slug:

```python
# Apply filters
S.set_filter_consumer(['Early Professional', 'Established Professional'])
filtered_data = S.get_filtered_data()

# Get traits from filtered data
top3_traits = S.get_top_3_traits(filtered_data)[0]

# Get the filter slug for directory naming
filter_slug = S._get_filter_slug()

# Create word cloud with filtered data
fig = create_traits_wordcloud(
    data=top3_traits,
    column='Top_3_Traits',
    title="Most Prominent Personality Traits<br>(Early & Established Professionals)",
    fig_save_dir='figures',
    filter_slug=filter_slug  # e.g., 'Cons-Early_Professional_Established_Professional'
)

fig
```

## Function Parameters

- **data**: Polars DataFrame or LazyFrame with trait data
- **column**: Column name containing comma-separated traits (default: 'Top_3_Traits')
- **title**: Title for the word cloud
- **width**: Width in pixels (default: 1600)
- **height**: Height in pixels (default: 800)
- **background_color**: Background color (default: 'white')
- **fig_save_dir**: Directory to save PNG (default: None - doesn't save)
- **filter_slug**: Subdirectory name for filtered results (default: 'All_Respondents')

## Colors

The word cloud uses colors from `theme.py`:
- PRIMARY: #0077B6 (Medium Blue)
- RANK_1: #004C6D (Dark Blue)
- RANK_2: #008493 (Teal)
- RANK_3: #5AAE95 (Sea Green)

## Output

- **Returns**: matplotlib Figure object for display in notebooks
- **Saves**: PNG file to `{fig_save_dir}/{filter_slug}/{sanitized_title}.png` at 300 DPI

The saved files follow the same naming convention as plots in `plots.py`.