wordcloud

docs/wordcloud-usage.md

@@ -0,0 +1,85 @@
+# 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 JPMCSurvey, 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 = JPMCSurvey(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`.