Word cloud generators

Word cloud creation

Utilities for creating a word cloud.

hedvis.generators.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

hedvis.generators.word_cloud.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

hedvis.generators.word_cloud.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

create_wordcloud

hedvis.generators.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

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

hedvis.generators.word_cloud.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

hedvis.generators.word_cloud.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

hedvis.generators.word_cloud_util.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.

hedvis.generators.word_cloud_util.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.

hedvis.generators.word_cloud_util.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

hedvis.generators.word_cloud_util.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

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

Bases: object

Represents a colormap.

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

Initialize a word cloud color generator.

Parameters:

  • colormap (str, optional) – The name of the matplotlib colormap to use for generating colors. Defaults to ‘nipy_spectral’.

  • color_range (tuple of float, optional) – A tuple containing the minimum and maximum values to use from the colormap. Defaults to (0.0, 0.5).

  • color_step_range (tuple of float, optional) – A tuple containing the minimum and maximum values to step through the colormap. Defaults to (0.15, 0.25). This is the speed at which it goes through the range chosen. .25 means it will go through 1/4 of the range each pick.

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

Update the current color fraction and wrap around if necessary.

hedvis.generators.word_cloud_util.default_color_func(word, font_size, position, orientation, random_state=None, **kwargs)

Update the current color fraction and wrap around if necessary.