HISTOGRAM

Excel Usage

=HISTOGRAM(data, title, xlabel, ylabel, stat_color, bins, density, cumulative, grid, legend)

• data (list[list], required): Input data.
• title (str, optional, default: null): Chart title.
• xlabel (str, optional, default: null): Label for X-axis.
• ylabel (str, optional, default: null): Label for Y-axis.
• stat_color (str, optional, default: null): Bar color.
• bins (int, optional, default: 10): Number of bins.
• density (str, optional, default: “false”): Probability density.
• cumulative (str, optional, default: “false”): Cumulative distribution.
• grid (str, optional, default: “true”): Show grid lines.
• legend (str, optional, default: “false”): Show legend.

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

Examples

Example 1: Basic histogram with single column

Inputs:

data
1
2
2
3
3
3
4
4
5

Excel formula:

=HISTOGRAM({1;2;2;3;3;3;4;4;5})

Expected output:

"chart"

Example 2: Histogram with multiple columns

Inputs:

data
1	10
2	20
3	30
4	40
5	50

Excel formula:

=HISTOGRAM({1,10;2,20;3,30;4,40;5,50})

Expected output:

"chart"

Example 3: Histogram with custom labels and bins

Inputs:

data	title	xlabel	ylabel	bins
1.5	Test Histogram	Value	Frequency	5
2.3
3.1
4.8
5.2
6.7
7.1

Excel formula:

=HISTOGRAM({1.5;2.3;3.1;4.8;5.2;6.7;7.1}, "Test Histogram", "Value", "Frequency", 5)

Expected output:

"chart"

Example 4: Density and cumulative histogram

Inputs:

data	density	cumulative
1	true	true
2
3
4
5
6
7
8
9
10

Excel formula:

=HISTOGRAM({1;2;3;4;5;6;7;8;9;10}, "true", "true")

Expected output:

"chart"

Python Code

import sys
import matplotlib
IS_PYODIDE = sys.platform == "emscripten"
if IS_PYODIDE:
    matplotlib.use('Agg')
import matplotlib.pyplot as plt
import io
import base64
import numpy as np

def histogram(data, title=None, xlabel=None, ylabel=None, stat_color=None, bins=10, density='false', cumulative='false', grid='true', legend='false'):
    """
    Create a frequency distribution histogram from data.

    See: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html

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

    Args:
        data (list[list]): Input data.
        title (str, optional): Chart title. Default is None.
        xlabel (str, optional): Label for X-axis. Default is None.
        ylabel (str, optional): Label for Y-axis. Default is None.
        stat_color (str, optional): Bar color. Valid options: Blue, Green, Red, Cyan, Magenta, Yellow, Black, White. Default is None.
        bins (int, optional): Number of bins. Default is 10.
        density (str, optional): Probability density. Valid options: True, False. Default is 'false'.
        cumulative (str, optional): Cumulative distribution. Valid options: True, False. Default is 'false'.
        grid (str, optional): Show grid lines. Valid options: True, False. Default is 'true'.
        legend (str, optional): Show legend. Valid options: True, False. Default is 'false'.

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

    def str_to_bool(s):
        return s.lower() == "true" if isinstance(s, str) else bool(s)

    try:
        data = to2d(data)

        if not isinstance(data, list) or not all(isinstance(row, list) for row in data):
            return "Error: Invalid input - data must be a 2D list"

        # Extract numeric columns
        cols = []
        max_rows = max(len(row) for row in data) if data else 0

        for col_idx in range(max_rows):
            col_data = []
            for row in data:
                if col_idx < len(row):
                    val = row[col_idx]
                    try:
                        col_data.append(float(val))
                    except (TypeError, ValueError):
                        continue
            if col_data:
                cols.append(col_data)

        if not cols:
            return "Error: No valid numeric data found"

        # Create plot
        fig, ax = plt.subplots(figsize=(8, 6))

        # Plot histogram for each column
        for i, col in enumerate(cols):
            color = stat_color if stat_color else None
            ax.hist(col, bins=bins, density=str_to_bool(density), 
                   cumulative=str_to_bool(cumulative), alpha=0.7, 
                   color=color, label=f'Column {i+1}' if len(cols) > 1 else None)

        if title:
            ax.set_title(title)
        if xlabel:
            ax.set_xlabel(xlabel)
        if ylabel:
            ax.set_ylabel(ylabel)

        if str_to_bool(grid):
            ax.grid(True, alpha=0.3)

        if str_to_bool(legend) and len(cols) > 1:
            ax.legend()

        plt.tight_layout()

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

Online Calculator