WORDCLOUD

Overview

The WORDCLOUD function generates a word cloud visualization from text data, where words are displayed with sizes proportional to their frequency or importance. This implementation uses the word_cloud Python library created by Andreas Mueller, which provides an efficient algorithm for text visualization.

Unlike traditional word cloud generators, this library employs integral images for collision detection, allowing it to efficiently fill all available space while preventing word overlap. The algorithm sorts words by frequency, then iteratively places them on the canvas using an integral image data structure that enables constant-time queries for available rectangular regions. When a word cannot fit at its ideal size, the font is reduced until space is found, while preserving the frequency-based ranking order.

The function accepts text as a 2D list (typical Excel range format), processes it into a single corpus, and renders the visualization using Matplotlib with customizable parameters including max_words (default 100), background_color (default “white”), and colormap (default “viridis” for word colors). The output is returned as a base64-encoded PNG image string that can be displayed directly in Excel or other applications.

For more technical details, see the WordCloud documentation and the original blog post describing the algorithm.

This example function is provided as-is without any representation of accuracy.

Excel Usage

=WORDCLOUD(text, max_words, background_color, colormap)

• text (list[list], required): 2D list of text strings to generate the word cloud from
• max_words (int, optional, default: null): Maximum number of words to display in the cloud
• background_color (str, optional, default: null): Background color name (e.g., “white”, “black”)
• colormap (str, optional, default: null): Matplotlib colormap name for word colors (e.g., “viridis”, “plasma”)

Returns (object): Matplotlib Figure object (standard Python) or PNG image as base64 string (Pyodide).

Examples

Example 1: Demo case 1

Inputs:

text	max_words	background_color	colormap
Great service	10	white	viridis
Fast delivery
Excellent support

Excel formula:

=WORDCLOUD({"Great service";"Fast delivery";"Excellent support"}, 10, "white", "viridis")

Expected output:

"chart"

Example 2: Demo case 2

Inputs:

text	max_words	background_color	colormap
Easy to use	8	black	plasma
User friendly interface
Easy to use

Excel formula:

=WORDCLOUD({"Easy to use";"User friendly interface";"Easy to use"}, 8, "black", "plasma")

Expected output:

"chart"

Example 3: Demo case 3

Inputs:

text	max_words
Simple	5

Excel formula:

=WORDCLOUD({"Simple"}, 5)

Expected output:

"chart"

Example 4: Demo case 4

Inputs:

text	max_words	background_color	colormap
A B C D E F G H I J	10	white	inferno

Excel formula:

=WORDCLOUD({"A B C D E F G H I J"}, 10, "white", "inferno")

Expected output:

"chart"

Python Code

import sys
import matplotlib
IS_PYODIDE = sys.platform == "emscripten"
if IS_PYODIDE:
    matplotlib.use('Agg')
import base64
from io import BytesIO
from wordcloud import WordCloud
import matplotlib.pyplot as plt

def wordcloud(text, max_words=None, background_color=None, colormap=None):
    """
    Generates a word cloud image from provided text data and returns a PNG image as a base64 string.

    This example function is provided as-is without any representation of accuracy.

    Args:
        text (list[list]): 2D list of text strings to generate the word cloud from
        max_words (int, optional): Maximum number of words to display in the cloud Default is None.
        background_color (str, optional): Background color name (e.g., "white", "black") Default is None.
        colormap (str, optional): Matplotlib colormap name for word colors (e.g., "viridis", "plasma") Default is None.

    Returns:
        object: Matplotlib Figure object (standard Python) or PNG image as base64 string (Pyodide).
    """
    def to2d(x):
        return [[x]] if not isinstance(x, list) else x

    text = to2d(text)
    if not isinstance(text, list) or not all(isinstance(row, list) for row in text):
        return "Invalid input: text must be a 2D list of strings."
    flat_text = []
    for row in text:
        for cell in row:
            if not isinstance(cell, str):
                return "Invalid input: all elements in text must be strings."
            flat_text.append(cell)
    joined_text = " ".join(flat_text)
    if not joined_text.strip():
        return "Invalid input: text is empty."
    if max_words is None:
        max_words = 100
    else:
        try:
            max_words = int(max_words)
        except Exception:
            return "Invalid input: max_words must be a number."
    if background_color is None:
        background_color = "white"
    if colormap is None:
        colormap = "viridis"
    try:
        wc = WordCloud(width=800, height=400, max_words=max_words, background_color=background_color, colormap=colormap)
        wc.generate(joined_text)
        fig, ax = plt.subplots(figsize=(8, 4))
        ax.imshow(wc, interpolation='bilinear')
        ax.axis('off')
        plt.tight_layout()

        if IS_PYODIDE:
            buf = BytesIO()
            plt.savefig(buf, format='png', bbox_inches='tight', pad_inches=0)
            plt.close(fig)
            buf.seek(0)
            img_base64 = base64.b64encode(buf.read()).decode('utf-8')
            return f"data:image/png;base64,{img_base64}"
        else:
            return fig
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator