Word cloud generators

Word cloud creation

Utilities for creating a word cloud.

create_wordcloud(word_dict, mask_path=None, background_color=None, width=400, height=300, **kwargs)[source]

Takes a word dict and returns a generated word cloud object.

Parameters:

  • word_dict (dict) – words and their frequencies

  • mask_path (str or None) – The path of the mask file

  • background_color (str or None) – If None, transparent background.

  • width (int) – width in pixels.

  • height (int) – height in pixels.

  • kwargs (kwargs) – Any other parameters WordCloud accepts, overrides default values where relevant.

Returns:

The generated cloud. (Use .to_file to save it out as an image.)

Return type:

WordCloud

Raises:

ValueError – An empty dictionary was passed

load_and_resize_mask(mask_path, width=None, height=None)[source]

Load a mask image and resize it according to given dimensions.

The image is resized maintaining aspect ratio if only width or height is provided.

Returns None if no mask_path.

Parameters:

  • mask_path (str) – The path to the mask image file.

  • width (int, optional) – The desired width of the resized image. If only width is provided, the image is scaled to maintain its original aspect ratio. Defaults to None.

  • height (int, optional) – The desired height of the resized image. If only height is provided, the image is scaled to maintain its original aspect ratio. Defaults to None.

Returns:

The loaded and processed mask image as a numpy array with binary values (0 or 255).

Return type:

numpy.ndarray

word_cloud_to_svg(wc)[source]

Return a WordCould as an SVG string.

Parameters:

wc (WordCloud) – the word cloud object.

Returns:

The svg for the word cloud.

Return type:

str

create_wordcloud

create_wordcloud(word_dict, mask_path=None, background_color=None, width=400, height=300, **kwargs)[source]

Takes a word dict and returns a generated word cloud object.

Parameters:

  • word_dict (dict) – words and their frequencies

  • mask_path (str or None) – The path of the mask file

  • background_color (str or None) – If None, transparent background.

  • width (int) – width in pixels.

  • height (int) – height in pixels.

  • kwargs (kwargs) – Any other parameters WordCloud accepts, overrides default values where relevant.

Returns:

The generated cloud. (Use .to_file to save it out as an image.)

Return type:

WordCloud

Raises:

ValueError – An empty dictionary was passed

Create a word cloud from a dictionary of word frequencies.

Parameters:

  • word_dict (dict) - Dictionary mapping words to their frequencies

  • mask_path (str or None) - Path to mask image for shaped clouds

  • background_color (str or None) - Background color (None for transparent)

  • width (int) - Width in pixels (default: 400)

  • height (int) - Height in pixels (default: 300)

  • kwargs - Additional parameters passed to WordCloud

Returns:

  • WordCloud - Generated word cloud object

Raises:

  • ValueError - If word_dict is empty

  • HedFileError - If font or mask path is invalid

Examples:

Basic word cloud:

from hedvis import create_wordcloud

word_freq = {"Event": 10, "Action": 5, "Sensory": 8}
wc = create_wordcloud(word_freq, width=800, height=600)
wc.to_file("wordcloud.png")

With mask image:

wc = create_wordcloud(
    word_freq,
    mask_path="brain_mask.png",
    background_color="white"
)

word_cloud_to_svg

word_cloud_to_svg(wc)[source]

Return a WordCould as an SVG string.

Parameters:

wc (WordCloud) – the word cloud object.

Returns:

The svg for the word cloud.

Return type:

str

Convert a WordCloud object to SVG string format.

Parameters:

  • wc (WordCloud) - The word cloud object to convert

Returns:

  • str - SVG representation as string

Example:

from hedvis import create_wordcloud, word_cloud_to_svg

wc = create_wordcloud(word_freq)
svg_string = word_cloud_to_svg(wc)

with open("output.svg", "w") as f:
    f.write(svg_string)

load_and_resize_mask

load_and_resize_mask(mask_path, width=None, height=None)[source]

Load a mask image and resize it according to given dimensions.

The image is resized maintaining aspect ratio if only width or height is provided.

Returns None if no mask_path.

Parameters:

  • mask_path (str) – The path to the mask image file.

  • width (int, optional) – The desired width of the resized image. If only width is provided, the image is scaled to maintain its original aspect ratio. Defaults to None.

  • height (int, optional) – The desired height of the resized image. If only height is provided, the image is scaled to maintain its original aspect ratio. Defaults to None.

Returns:

The loaded and processed mask image as a numpy array with binary values (0 or 255).

Return type:

numpy.ndarray

Load and resize a mask image for word cloud generation.

Parameters:

  • mask_path (str) - Path to mask image

  • width (int, optional) - Target width

  • height (int, optional) - Target height

Returns:

  • numpy.ndarray - Processed mask image as binary array

Word cloud utilities

Support utilities for word cloud generation.

Color Functions

default_color_func(word, font_size, position, orientation, random_state=None, **kwargs)

Update the current color fraction and wrap around if necessary.

Default color function for word clouds using matplotlib colormaps.

generate_contour_svg(wc, width, height)[source]

Generate an SVG contour mask based on a word cloud object and dimensions.

Parameters:

  • wc (WordCloud) – The word cloud object.

  • width (int) – SVG image width in pixels.

  • height (int) – SVG image height in pixels.

Returns:

SVG point list for the contour mask, or empty string if not generated.

Return type:

str

Generate SVG contour overlay for masked word clouds.

class ColormapColorFunc(colormap='nipy_spectral', color_range=(0.0, 0.5), color_step_range=(0.15, 0.25))[source]

Bases: object

Represents a colormap.

color_func(word, font_size, position, orientation, random_state=None, **kwargs)[source]

Update the current color fraction and wrap around if necessary.

default_color_func(word, font_size, position, orientation, random_state=None, **kwargs)

Update the current color fraction and wrap around if necessary.

generate_contour_svg(wc, width, height)[source]

Generate an SVG contour mask based on a word cloud object and dimensions.

Parameters:

  • wc (WordCloud) – The word cloud object.

  • width (int) – SVG image width in pixels.

  • height (int) – SVG image height in pixels.

Returns:

SVG point list for the contour mask, or empty string if not generated.

Return type:

str

random_color_darker(random_state=None)[source]

Random color generation function.

Parameters:

random_state (Random or None) – Previous state of random generation for next color generation.

Returns:

Represents a hue, saturation, and lightness.

Return type:

str