`imshow`

fn def imshow(df: DataFrame, row: String, column: String, value: String, 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[Imshow]

imshow() over a long-form dataframe_mojo DataFrame (#743): one row per cell, with row and column giving the cell’s coordinates and value its height.

A field is a grid, and a frame is a list of cells, so the rows are pivoted into one. Both axes come out ascending. A cell with no row is missing, not zero: it comes out blank and takes no part in the color limits (#367), which is what lets a table that was never rectangular be drawn as a field.

Args:

df (DataFrame): The frame to read.
row (String): The numeric column giving each cell’s row coordinate.
column (String): The numeric column giving each cell’s column coordinate.
value (String): The numeric column holding each cell.
theme (Theme): Full styling knobs beyond this function’s own parameters.
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 line under the title.
x_title (String): The x-axis caption; defaults to column.
y_title (String): The y-axis caption; defaults to row.

Returns:

Chart[Imshow]: The finished chart – unrendered.

Raises:

Error: A named column is missing, is not numeric, the columns differ in length, or a (row, column) pair repeats.

fn def imshow[dtype: DType](z: List[List[Scalar[dtype]]], 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[Imshow]

Display a 2D array as an image: one colored cell per element, on continuous axes in row/column index units.

Mark.IMSHOW. This is the chart for anything that is an array rather than a table – a matrix, a raster, a spectrogram, a correlation surface, a decoded PNG. Mark.HEATMAP looks like the same thing and is not: it takes categorical x and y labels with one value per pair, so a 512x512 array would need 512 category labels.

Row 0 is at the top, and the y-axis counts downward to match. That is the order a raster’s scanlines arrive in, and the order a matrix is written in – imshow(read_png(...)) comes out the right way up. It is the opposite of contour(), which puts row 0 at the bottom because its grid is a sampled surface rather than an image.

The image fills the plot rect, so its pixels are only square when the rect happens to be. The alternative, square pixels that leave the axes partly empty, is not the default. Filling is the right default here because every other mark in this package fills its rect, and because the common case – a matrix, a correlation surface, a field – has no physical aspect to preserve. For a photo or anything else where a stretch would misrepresent the data, size the chart so the plot rect matches the array: the rect is width minus the left margin, the right margin and the legend column, and height minus the top and bottom margins, all of which Theme exposes.

Cells are flat colors, no interpolation: what you see is the array’s own resolution, not detail invented between samples.

Color comes from the theme’s scale over the array’s own range. Theme(color_ramp=colormaps.viridis()) is worth reaching for here more than anywhere else in this package – a scalar field shown through a three-stop ramp gets contrast where the data has none, which is the specific problem perceptually uniform maps were built to fix.

Example:

from std.math import exp

from dataviz import imshow
from dataviz.core.colormaps import viridis
from dataviz import save
from dataviz import Theme

def main() raises:
    # Illustrative thermal-camera readings across a server rack.
    # Two hot components sit on top of a gentle exhaust gradient.
    var z = List[List[Float64]]()
    for r in range(48):
        var row = List[Float64]()
        for c in range(64):
            var dx1 = (Float64(c) - 19.0) / 7.0
            var dy1 = (Float64(r) - 17.0) / 6.0
            var dx2 = (Float64(c) - 46.0) / 9.0
            var dy2 = (Float64(r) - 31.0) / 8.0
            var temperature = 24.0 + Float64(r) * 0.08
            temperature += 31.0 * exp(-(dx1 * dx1 + dy1 * dy1))
            temperature += 22.0 * exp(-(dx2 * dx2 + dy2 * dy2))
            row.append(temperature)
        z.append(row^)

    var chart = imshow(
        z,
        theme=Theme(color_ramp=viridis()),
        title="Illustrative Server-Rack Thermal Scan (°C)",
        x_title="Sensor column",
        y_title="Sensor row",
    )
    save(chart, "docs/src/examples/out_imshow.svg")

Parameters:

dtype (DType)

Args:

z (List[List[Scalar[dtype]]]): The array, row-major (z[row][col]), rectangular and non-empty. Rows are the y axis and columns the x axis. 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[Imshow]: 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:

pcolormesh