haam.haam_wordcloud module

HAAM Word Cloud Module

Generate word clouds for PC poles (high and low) with customized coloring.

class haam.haam_wordcloud.PCWordCloudGenerator(topic_analyzer, analysis_results=None, criterion=None, human_judgment=None, ai_judgment=None)

Bases: object

Generate word clouds for principal component poles.

Methods

create_all_pc_wordclouds([pc_indices, k, ...])	Create word clouds for all specified PCs.
create_pc_wordclouds(pc_idx[, k, max_words, ...])	Create word clouds for high and low poles of a specific PC.
create_top_pcs_wordcloud_grid(pc_indices[, ...])	Create a grid visualization of word clouds for top PCs.

__init__(topic_analyzer, analysis_results=None, criterion=None, human_judgment=None, ai_judgment=None)

Initialize word cloud generator.

Parameters:

• topic_analyzer (TopicAnalyzer) – TopicAnalyzer instance with computed topics and PC associations

• analysis_results (dict, optional) – HAAM analysis results containing model coefficients for validity coloring

• criterion (array-like, optional) – Ground truth values (X) for direct validity measurement

• human_judgment (array-like, optional) – Human judgment values (HU) for direct validity measurement

• ai_judgment (array-like, optional) – AI judgment values (AI) for direct validity measurement

create_pc_wordclouds(pc_idx: int, k: int = 10, max_words: int = 100, figsize: Tuple[int, int] = (10, 5), output_dir: str | None = None, display: bool = True, color_mode: str = 'pole') → Tuple[Figure, str, str]

Create word clouds for high and low poles of a specific PC.

Parameters:

• pc_idx (int) – PC index (0-based)

• k (int) – Number of topics to include from each pole

• max_words (int) – Maximum words to display in word cloud

• figsize (Tuple[int, int]) – Figure size (width, height) for each subplot

• output_dir (str, optional) – Directory to save output files

• display (bool) – Whether to display the plots

• color_mode (str, optional) –

  ‘pole’ (default): Red for high pole, blue for low pole ‘validity’: Color based on X/HU/AI agreement:

  • Dark red: consensus high (all in top quartile)

  • Light red: any high signal (at least one in top quartile)

  • Dark blue: consensus low (all in bottom quartile)

  • Light blue: any low signal (at least one in bottom quartile)

  • Dark grey: opposing signals (mix of high and low)

  • Light grey: all in middle quartiles

Returns:

Figure object, high pole output path, low pole output path

Return type:

Tuple[plt.Figure, str, str]

create_all_pc_wordclouds(pc_indices: List[int] | None = None, k: int = 10, max_words: int = 100, figsize: Tuple[int, int] = (10, 5), output_dir: str = './wordclouds', display: bool = False, color_mode: str = 'pole') → Dict[int, Tuple[str, str]]

Create word clouds for all specified PCs.

Parameters:

• pc_indices (List[int], optional) – List of PC indices. If None, uses all available PCs

• k (int) – Number of topics to include from each pole

• max_words (int) – Maximum words to display in word cloud

• figsize (Tuple[int, int]) – Figure size for each subplot

• output_dir (str) – Directory to save output files

• display (bool) – Whether to display each plot

• color_mode (str) – ‘pole’ or ‘validity’ coloring mode

Returns:

Dictionary mapping PC index to (high_path, low_path)

Return type:

Dict[int, Tuple[str, str]]

create_top_pcs_wordcloud_grid(pc_indices: List[int], k: int = 10, max_words: int = 50, output_file: str | None = None, display: bool = True, color_mode: str = 'pole') → Figure

Create a grid visualization of word clouds for top PCs.

Parameters:

• pc_indices (List[int]) – List of PC indices to visualize (max 9 for 3x3 grid)

• k (int) – Number of topics to include from each pole

• max_words (int) – Maximum words per word cloud

• output_file (str, optional) – Path to save the grid visualization

• display (bool) – Whether to display the plot

• color_mode (str) – ‘pole’ (default): Red for high pole, blue for low pole ‘validity’: Color based on X/HU/AI agreement

Returns:

Figure object

Return type:

plt.Figure