Heatmap Series

The heatmap method on a Figure adds a heatmap series, which is simply a 2D grid visualization where each cell's color encodes a numeric value. Heatmaps are useful for correlation matrices, density plots, spectral data, and more generally any quantity defined over a 2D grid.

note

When a figure contains a heatmap series and no visual_map has been explicitly set, a default visual_map is automatically added with the viridis color scale.

Method Overloads

Signature	Description
bar(points [, options])	Pass a list of points [[x[0],y[0],z[0]],[x[1],y[1],z[1]], ...] and optionally options.
heatmap(options)	Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes.

Quick examples

var points_1 = []
var points_2 = []
var points_3 = []
for (var i = 0; i < 3; ++i) {
    if (i == 0 ){
        for (var j = 0; j < 5; ++j) {
            points_1.push_back([i, j, (i + 1) * (j + 1)])
        }
    }
    if (i == 1 ){
        for (var j = 0; j < 5; ++j) {
            points_2.push_back([i, j, (i + 1) * (j + 1)])
        }
    }
    if (i == 2 ){
        for (var j = 0; j < 5; ++j) {
            points_3.push_back([i, j, (i + 1) * (j + 1)])
        }
    }
}

Figure()
    .heatmap(points_1)
    .heatmap(points_2, [
            "name": "named_points",
            "border_color": "#333",
            "border_width": 2,
            "border_type": "dashed"])
    .heatmap(["data": points_3])
    .title("Basic Heatmap")
    .save("./figures/ex_heatmap_basic")

General Methods

Option	Type	Description
name	string	Series name shown in legend and tooltip.

Quick examples

var points = []
for (var i = 0; i < 4; ++i) {
    for (var j = 0; j < 4; ++j) {
        points.push_back([i, j, (i + 1) * (j + 1)])
    }
}

Figure()
    .heatmap(points, ["name": "Series"])
    .legend()
    .save("./figures/ex_heatmap_general")

item_style(options)

Controls the visual style of each heatmap cell (cartesian only).

Option	Type	Description
border_color	Color	Sets the color of the cell’s border line. Accepts named colors, HEX, RGB, or RGBA values.
border_width	number	Defines the thickness of the cell border in pixels. Higher values produce thicker borders.
border_type	string or list	Specifies the border style. Can be a preset style such as "solid", "dashed", or "dotted", or a custom dash pattern defined as a numeric array.
border_dash_offset	number	Controls where the dash pattern starts along the border. Useful for adjusting dashed border alignment.
border_cap	string	Determines the shape of the ends of dashed or stroked borders. Common values include "butt", "round", and "square".
border_join	string	Controls how two border segments join at corners. Options include "miter", "round", and "bevel".
border_miter_limit	number	Sets the maximum allowed length of miter joins before they are converted to bevel joins. Prevents sharp corner spikes.
border_radius	number or list	Rounds the corners of the cell. A single value applies to all corners, while a list allows per-corner control.
shadow_blur	number	Defines the blur radius of the cell’s shadow. Larger values create softer, more diffused shadows.
shadow_color	Color	Sets the color of the shadow. Supports transparency for subtle effects.
shadow_offset_x	number	Moves the shadow horizontally. Positive values shift right; negative values shift left.
shadow_offset_y	number	Moves the shadow vertically. Positive values shift downward; negative values shift upward.
opacity	number	Controls overall cell transparency. Ranges from 0 (fully transparent) to 1 (fully opaque).

Quick examples

var points = []
for (var i = 0; i < 3; ++i) {
    for (var j = 0; j < 3; ++j) {
        points.push_back([i, j, (i + 1) * (j + 1)])
    }
}

Figure()
    .heatmap(points, [
        "name": "Custom Cell Style",
        "item_style": [
            "border_color": "#333",
            "border_width": 2,
            "border_type": "dashed",          // "solid" | "dashed" | "dotted" | [dashPattern]
            "border_dash_offset": 2,
            "border_cap": "round",            // "butt" | "round" | "square"
            "border_join": "round",           // "miter" | "round" | "bevel"
            "border_miter_limit": 10,
            "border_radius": 4,   
            "shadow_blur": 6,
            "shadow_color": "rgba(163, 30, 30, 0.93)",
            "shadow_offset_x": 2,
            "shadow_offset_y": 2,
            "opacity": 1.0
        ]
    ])
    .save("./figures/ex_heatmap_item_style")

label(options)

Labels displayed inside each heatmap cell (cartesian only).

Option	Type	Description
show	boolean	Controls whether the labels are visible in the cells.
position	string or list	Specifies the position of the label within the cell (e.g., "inside", "top", "center").
distance	number	Adjusts the distance of the label from its default position.
rotate	number	Defines the rotation angle of the label, in degrees.
color	color	Sets the color of the label text (e.g., hex, RGB, or named color).
font_size	number	Specifies the size of the label's font, in pixels or points.
font_weight	string or number	Determines the weight of the font (e.g., "normal", "bold", or numeric values like 400, 700).
font_family	string	Defines the font family used for the label text (e.g., "Arial", "Courier New").
font_style	string	Specifies the style of the font (e.g., "normal", "italic", "oblique").
align	string	Controls the horizontal alignment of the label text (e.g., "left", "center", "right").
vertical_align	string	Controls the vertical alignment of the label text (e.g., "top", "middle", "bottom").
background_color	string or map	Defines the background color of the label. Can accept a solid color or a gradient.
border_color	color	Sets the color of the label's border.
border_width	number	Defines the thickness of the label's border.
border_radius	number	Specifies the radius of the label's corners, creating rounded edges.
padding	number or list	Sets the padding around the label text. A list allows custom padding for each side (e.g., [top, right, bottom, left]).
overflow	string	Specifies how to handle label text overflow (e.g., "none", "truncate", "break").
ellipsis	string	Defines the string to display when label text overflows (typically used with "truncate", e.g., "...").

var points1 = []
var points2 = []
var points3 = []
for (var i = 0; i < 3; ++i) {
    for (var j = 0; j < 3; ++j) {
        points1.push_back([i, j, (i + 1) * (j + 1)])
        points2.push_back([i, j + 4, (i + 1) * (j + 1)])
        points3.push_back([i, j + 8, (i + 1) * (j + 1)])
    }
}

Figure()
    .heatmap(points1, [
        "name": "Bold Labels",
        "label": [
            "show": true,
            "position": "inside",              // Label position within the cell
            "distance": 5,                     // Distance from default position
            "rotate": 0,                       // Rotation angle in degrees
            "color": "#000",                   // Text color
            "font_size": 12,                   // Font size
            "font_weight": "bold",             // Font weight
            "font_family": "Arial",            // Font family
            "font_style": "normal",            // Font style
            "align": "center",                 // Horizontal alignment
            "vertical_align": "middle",        // Vertical alignment
            "background_color": "#FFF",        // Label background color
            "border_color": "#333",            // Label border color
            "border_width": 1,                 // Label border width
            "border_radius": 4,                // Label border radius
            "padding": 4,                      // Label padding
            "overflow": "none",                // Overflow handling (none, truncate, break)
            "ellipsis": "..."                  // Ellipsis string for truncation
        ]
    ])
    .heatmap(points2, [
        "name": "Styled Labels",
        "label": [
            "show": true,
            "position": "inside",              // Label position within the cell
            "distance": 5,                     // Distance from default position
            "rotate": 0,                       // Rotation angle in degrees
            "color": "#FFF",                   // Text color
            "font_size": 11,                   // Font size
            "font_weight": "normal",           // Font weight
            "font_style": "italic",            // Font style
            "font_family": "Courier New",      // Font family
            "align": "center",                 // Horizontal alignment
            "vertical_align": "middle",        // Vertical alignment
            "background_color": "#333",        // Label background color
            "border_color": "#666",            // Label border color
            "border_width": 1,                 // Label border width
            "border_radius": 2,                // Label border radius
            "padding": 2,                      // Label padding
            "overflow": "none",                // Overflow handling
            "ellipsis": "..."                  // Ellipsis string
        ]
    ])
    .heatmap(points3, [
        "name": "Rotated Labels",
        "label": [
            "show": true,
            "position": "inside",              // Label position within the cell
            "distance": 5,                     // Distance from default position
            "rotate": 45,                      // Rotation angle in degrees
            "color": "#333",                   // Text color
            "font_size": 10,                   // Font size
            "font_weight": "normal",           // Font weight
            "font_family": "Verdana",          // Font family
            "font_style": "normal",            // Font style
            "align": "center",                 // Horizontal alignment
            "vertical_align": "middle",        // Vertical alignment
            "background_color": "#FFF",        // Label background color
            "border_color": "#999",            // Label border color
            "border_width": 1,                 // Label border width
            "border_radius": 3,                // Label border radius
            "padding": 4,                      // Label padding
            "overflow": "none",                // Overflow handling
            "ellipsis": "..."                  // Ellipsis string
        ]
    ])
    .save("./figures/ex_heatmap_label")

visual_map(options)

The visual_map method in Figure is key to controlling how data values are represented visually, especially when using heatmaps. It allows you to map numerical data to a color range, so high and low values are easily distinguishable. If you don’t explicitly define a visual_map, a default mapping is applied automatically. The input parameters, passed through an aleph map are summarized in the table below.

Option	Type	Description
min	number	Minimum value mapped to the first color in the range.
max	number	Maximum value mapped to the last color in the range.
orient	string	Direction of the visual map: 'horizontal' or 'vertical'.
left	string	Horizontal position of the visual map (e.g., 'center', 'left').
bottom	string	Vertical position of the visual map (e.g., '5%', 'top').

var points = []
for (var i = 0; i < 5; ++i) {
    for (var j = 0; j < 5; ++j) {
        points.push_back([i, j, (i + 1) * (j + 1)]) // Fill with values 1-25
    }
}

Figure()
    .heatmap(points)
    .visual_map([  // Define the color range based on data values
        "min": 0,  // Minimum value mapped to the first color in the range
        "max": 25, // Maximum value mapped to the last color in the range
        "orient": "horizontal",  // Display the color range horizontally
        "left": "center",  // Center the visual map horizontally
        "bottom": "5%"  // Position it 5% from the bottom of the container
    ])
    .save("./figures/ex_heatmap_with_vmap")

---