SCATTER_3D

Excel Usage

=SCATTER_3D(data, title, xlabel, ylabel, zlabel, color_map, marker, legend)
  • data (list[list], required): Input data (X, Y, Z).
  • 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.
  • zlabel (str, optional, default: null): Label for Z-axis.
  • color_map (str, optional, default: “viridis”): Color map for points.
  • marker (str, optional, default: “o”): Marker style.
  • legend (str, optional, default: “false”): Show legend.

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

Examples

Example 1: Basic 3D scatter plot

Inputs:

data
1 2 3
2 3 4
3 4 5
4 5 6

Excel formula:

=SCATTER_3D({1,2,3;2,3,4;3,4,5;4,5,6})

Expected output:

"chart"

Example 2: 3D scatter with labels

Inputs:

data title xlabel ylabel zlabel
1 1 1 Scatter Plot X Y Z
2 4 2
3 9 3
4 16 4

Excel formula:

=SCATTER_3D({1,1,1;2,4,2;3,9,3;4,16,4}, "Scatter Plot", "X", "Y", "Z")

Expected output:

"chart"

Example 3: Using plasma colormap

Inputs:

data color_map
0 0 1 plasma
1 1 2
2 2 3
3 3 4
4 4 5

Excel formula:

=SCATTER_3D({0,0,1;1,1,2;2,2,3;3,3,4;4,4,5}, "plasma")

Expected output:

"chart"

Example 4: Using square markers

Inputs:

data marker legend
1 2 1 s true
2 3 2
3 4 3
4 5 4

Excel formula:

=SCATTER_3D({1,2,1;2,3,2;3,4,3;4,5,4}, "s", "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
from mpl_toolkits.mplot3d import Axes3D
import io
import base64
import numpy as np

def scatter_3d(data, title=None, xlabel=None, ylabel=None, zlabel=None, color_map='viridis', marker='o', legend='false'):
    """
    Create a 3D scatter plot.

    See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html#matplotlib.axes.Axes.scatter

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

    Args:
        data (list[list]): Input data (X, Y, Z).
        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.
        zlabel (str, optional): Label for Z-axis. Default is None.
        color_map (str, optional): Color map for points. Valid options: Viridis, Plasma, Inferno, Magma, Cividis. Default is 'viridis'.
        marker (str, optional): Marker style. Valid options: None, Point, Pixel, Circle, Square, Triangle Down, Triangle Up. Default is 'o'.
        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

    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"

        # Flatten and validate data
        flat_data = []
        for row in data:
            for val in row:
                try:
                    flat_data.append(float(val))
                except (TypeError, ValueError):
                    return f"Error: Non-numeric value found: {val}"

        if len(flat_data) < 3:
            return "Error: Need at least 3 values for X, Y, Z coordinates"

        # Parse data into columns
        num_rows = len(data)
        num_cols = len(data[0]) if num_rows > 0 else 0

        if num_cols < 3:
            return "Error: Need at least 3 columns for X, Y, Z coordinates"

        # Extract X, Y, Z columns
        x_vals = [float(data[i][0]) for i in range(num_rows)]
        y_vals = [float(data[i][1]) for i in range(num_rows)]
        z_vals = [float(data[i][2]) for i in range(num_rows)]

        # Create figure
        fig = plt.figure(figsize=(10, 7))
        ax = fig.add_subplot(111, projection='3d')

        # Create scatter plot
        scatter = ax.scatter(x_vals, y_vals, z_vals, c=z_vals, cmap=color_map, marker=marker, s=50)

        # Set labels
        if title:
            ax.set_title(title)
        if xlabel:
            ax.set_xlabel(xlabel)
        if ylabel:
            ax.set_ylabel(ylabel)
        if zlabel:
            ax.set_zlabel(zlabel)

        # Add legend if requested
        if legend == "true":
            plt.colorbar(scatter, ax=ax, label='Z value')

        # 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