`pcolormesh`

fn def pcolormesh(x_edges: List[Float64], y_edges: List[Float64], z: List[List[Float64]], theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", subtitle: String = "", x_title: String = "", y_title: String = "") -> Chart[Pcolormesh]

Display a 2D array over cell boundaries you supply: imshow() for a grid whose rows and columns are not evenly spaced.

Mark.PCOLORMESH: an image over 1D coordinate arrays. The array is the same as imshow()’s; what changes is that each cell’s extent comes from x_edges/y_edges rather than from its index, so a log-spaced frequency axis, unequal time bins, or a grid that was never regular in the first place lands where it belongs instead of being stretched into evenly spaced columns.

The edges bound the cells, so there is one more of each than the array has columns and rows – len(x_edges) == cols + 1, len(y_edges) == rows + 1. Both must be strictly increasing.

Row 0 is at the bottom, unlike imshow(). y_edges[0] is a position on a real axis, not a scanline, so the axis counts upward the way every other continuous mark’s does.

Cells are flat colors and the color scale is the theme’s, exactly as in imshow() – see that docstring for why Theme(color_ramp=...) matters here.

Only 1D edges are supported: a fully curvilinear mesh would need a quad per cell rather than a rect, which is a different drawing path.

Example:

from std.math import exp, sin

from dataviz import pcolormesh
from dataviz.core.colormaps import magma
from dataviz import save
from dataviz import Theme

def main() raises:
    # Weather balloons are farther apart downrange and report at
    # uneven altitude bands, so each cell keeps its measured extent.
    var x_edges: List[Float64] = [
        0, 3, 7, 12, 18, 25, 33, 42, 52, 63, 75, 88, 102,
    ]
    var y_edges: List[Float64] = [
        0.0, 0.4, 0.9, 1.5, 2.3, 3.3, 4.6, 6.2, 8.0,
    ]

    var z = List[List[Float64]]()
    for r in range(len(y_edges) - 1):
        var row = List[Float64]()
        var altitude = (y_edges[r] + y_edges[r + 1]) / 2.0
        for c in range(len(x_edges) - 1):
            var distance = (x_edges[c] + x_edges[c + 1]) / 2.0
            var plume_x = (distance - 55.0) / 18.0
            var plume_y = (altitude - 2.2) / 0.9
            var temperature = 19.0 - 6.2 * altitude
            temperature += 2.0 * sin(distance / 17.0)
            temperature += 8.0 * exp(
                -(plume_x * plume_x + plume_y * plume_y)
            )
            row.append(temperature)
        z.append(row^)

    var chart = pcolormesh(
        x_edges,
        y_edges,
        z,
        theme=Theme(color_ramp=magma()),
        title="Illustrative Atmospheric Temperature Cross-Section (°C)",
        x_title="Distance downrange (km)",
        y_title="Altitude (km)",
    )
    save(chart, "docs/src/examples/out_pcolormesh.svg")

Args:

x_edges (List[Float64]): Column boundaries, cols + 1 of them, strictly increasing.
y_edges (List[Float64]): Row boundaries, rows + 1 of them, strictly increasing.
z (List[List[Float64]]): The array, row-major (z[row][col]), rectangular and non-empty. Every value must be finite.
theme (Theme): Full styling knobs beyond this function’s own parameters (colors, margins, fonts, gridlines, …) – see Theme’s docstring.
width (Int): Pixel width of the returned Plot (.size()).
height (Int): Pixel height of the returned Plot (.size()).
title (String): The chart’s title, shown above the plot.
subtitle (String): A secondary line shown under the title.
x_title (String): The x-axis caption.
y_title (String): The y-axis caption.

Returns:

Chart[Pcolormesh]: The finished chart – unrendered. Call save(plot, path) to write it (any of .svg/.png/.bmp), or render(plot)/render_svg(plot) for the explicit two-step.

Raises:

fn def pcolormesh(df: DataFrame, row: String, column: String, value: String, x_edges: List[Float64], y_edges: List[Float64], theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", subtitle: String = "", x_title: String = "", y_title: String = "") -> Chart[Pcolormesh]

Draw an irregular cell mesh from long-form DataFrame values.

row and column name numeric cell-center coordinates. The frame is pivoted into a grid in ascending coordinate order; absent cells stay blank. Explicit x_edges and y_edges give the boundaries of those columns and rows, so uneven cell widths are preserved.

Args:

df (DataFrame): One row per measured cell.
row (String): Numeric column of cell-center y coordinates.
column (String): Numeric column of cell-center x coordinates.
value (String): Numeric column of cell values.
x_edges (List[Float64]): Boundaries of the sorted x coordinates, one extra.
y_edges (List[Float64]): Boundaries of the sorted y coordinates, one extra.
theme (Theme): See the grid overload.
width (Int): See the grid overload.
height (Int): See the grid overload.
title (String): See the grid overload.
subtitle (String): See the grid overload.
x_title (String): See the grid overload.
y_title (String): See the grid overload.

Returns:

Chart[Pcolormesh]: The finished chart – unrendered.

Raises:

Error: A named column is invalid, a cell repeats, the edge lengths do not fit the grid, or a center falls outside its corresponding cell.

imshow