A scatter plot with a histogram of each of its columns along its top and right sides.
Options
Options
datatable - A table or live pipeline output for the scatter and its histograms; the same as wrapping the Marginals in Data.
schemaobject - Column types for data, such as {"day": "datetime"}, as on Data.
keycolumn | column[] - The column, or columns, that identify each row of data across updates, as on Data.
binsnumber | number[] | "auto" | "sturges" | "fd" | "scott" | expression - Both histograms' bins, as Histogram's bins: a count, edges, a rule or an expression. Default:
30. heightnumber - The height of the whole figure, at least 160: the histograms take a fifth of it (at least 48 px) across the scatter's side, and the scatter the rest. Default:
450 px. viewport{x, y, zoom, zoomX, zoomY, center} - The scatter's 2D view, as a Plot's viewport; the histograms follow it on their axes.
onviewportchange(viewport) => void - Called when the viewer pans or zooms the scatter, with its new viewport. Python: on_event("viewportchange").
Position
xcolumn - The column the scatter plots along x, binned by the histogram above it. Required.
ycolumn - The column the scatter plots along y, binned by the histogram to its right. Required.
Appearance
fillchannel - The fill color: a CSS color, or a column of numbers or categories mapped to colors.
colorchannel - The line or text color: a CSS color, or a column mapped to colors.
sizechannel - The size of each point or label: a number, or a column mapped to sizes. In px.
opacitychannel - The opacity, 0 to 1: a number, or a column (categories map through opacityScale). Default:
1. outlineColorchannel - The outline's color: a CSS color, or a column of categories mapped through outlineColorScale.
outlineOpacitychannel - Border opacity from 0 to 1: a number, numeric column, array or expression. Fades the border over the fill; mark opacity still applies to both. Missing values hide the border. Default:
1. outlineWidthchannel - The outline's width in CSS pixels, drawn inside the mark's edge (a point's at most its radius). Default:
0.
Scales
fillScalescale - The fill's scale, which marks can share: continuous({domain, colormap, transform}) for numbers, categorical({domain, range}) or ordinal() for categories.
colorScalescale - A scale for color that marks can share.
colormapstring | color[] | object - The colormap of a numeric fill or color: a name, a list of colors, or {colors, space, positions}. Default: the theme's (Viridis).
sizeScalescale - The size's scale, which marks can share: continuous({domain, range, transform}) for numbers (without a range, the automatic one), or categories with a numeric range.
outlineColorScalescale - A categorical() scale from the outlineColor column's categories to colors.
opacityScalescale - A categorical() scale from the opacity column's categories to opacities, 0 to 1.
Display
labelstring - The mark's name in the legend and the settings pane.
legendboolean - Whether the mark has a legend entry. Default:
true. visibleboolean - Whether the mark is drawn. Default:
true. blend"normal" | "additive" | "multiply" | "screen" | "subtractive" - How the mark mixes with what is drawn under it; any mode but normal draws it transparent, and SVG and PDF exports draw additive and subtractive as an image. Default:
"normal". glownumber - How much the mark glows: its own color times glow blooms around it in the plot's presentation (0 does not glow); the Plot's bloom effect sets the bloom's strength and radius. SVG and PDF exports draw the whole plot as an image. Default:
0. shadeShadeSpec - A plugin's shade (registerPlugin): { kind, ...parameters }, as { kind: "hatch", spacing: 6 } (Python hm.shade("hatch", spacing=6)), recolors each fragment the mark draws; picking, tooltips, domains and legends are unchanged. SVG and PDF exports draw a shaded mark as an image.
optionsstring[] - The settings the settings pane shows for this mark, by name.
namestring - The mark's name in the settings pane, and the name facet.endpoint() and partition.endpoint() find it by.
Interaction
identityidentity - Whose rows these are for selections: an identity() shared by tables that show the same things. Default: its data's.
selectboolean | selection | object - Click to replace the selection; an exact repeat clears it. Shift/Meta/Ctrl-click toggles membership (whole series for Line, Area): true uses its data's selection, or give a selection(). input("root").set("id") writes an input instead: a click sets it to the clicked row's id (a drill-down's root), .set(literal(v)) to a constant, .reset() to its default, and a click on nothing restores its default (input("root", {default}), else a Select of that name's, else null); several marks may write one input.
hoverboolean | selection | object - Mark the row under the pointer as @hovered (a whole series for Line, Area), without fading the others: true uses its data's hover, or give a selection(). input("focus").set("series") writes an input instead: while the pointer is on a row the input shows its series (or .set(literal(v)), a constant), then its committed value again (a hover that would change this mark's own rows is an error).
tooltipboolean | field[] | object - Show the nearest row's values in a box by the pointer: true, a list of fields, or {fields, radius, content}. Default: the Plot's.
brushboolean | selection | object - Brush rows with Shift-drag (point marks; Line, Area brush whole series): true uses its data's brush, a selection() shares one, {selection, axis} picks the axes.
nearbyboolean | selection | object - Mark the rows near the pointer (point marks): true, a selection(), or {selection, radius, units, axis}.
nearestboolean | selection | object - Mark the row a tooltip shows as @nearest, with or without the tooltip: under the pointer, else the nearest drawn row within radius pixels (a whole series for Line, Area): true, a selection(), or {selection, radius}. Default: the Plot's.
respondboolean | "selected" | "brushed" | "hovered" | "nearby" | "nearest" | selection | array - Which interaction states fade this mark's other rows to selectionOpacity; "hovered" fades them while hovering, "nearest" while a row is nearest. Default: the states it sets, except hover and nearest.
selectionOpacitynumber - The opacity of the rows outside the selection while one is active. Default:
0.25. dragboolean | "x" | "y" | "z" | "xy" | "xz" | "yz" | "xyz" - Drag rows to move them (point marks): true along every numeric axis, or the axes to move along. Default:
false. onclick(event) => void - Called for click on this mark; row provenance is optional after transforms.
ondblclick(event) => void - Called for dblclick on this mark; row provenance is optional after transforms.
onpointerenter(event) => void - Called for pointerenter on this mark; row provenance is optional after transforms.
onpointerleave(event) => void - Called for pointerleave on this mark; row provenance is optional after transforms.
onpointermove(event) => void - Called for pointermove on this mark; row provenance is optional after transforms.
onpointerdown(event) => void - Called for pointerdown on this mark; row provenance is optional after transforms.
onpointerup(event) => void - Called for pointerup on this mark; row provenance is optional after transforms.
onpointercancel(event) => void - Called for pointercancel on this mark; row provenance is optional after transforms.
onpointerover(event) => void - Called for pointerover on this mark; row provenance is optional after transforms.
onpointerout(event) => void - Called for pointerout on this mark; row provenance is optional after transforms.
onpointermissed(event) => void - Called for pointermissed on this mark; row provenance is optional after transforms.
ondrag(event) => void - Called while rows are dragged, each time they move. Python: on_event("drag").
ondragend(event) => void - Called when a drag ends; event.cancelled when Escape put the rows back. Python: on_event("dragend").
enterEffectboolean | "fade" | object - How rows that arrive in a keyed update appear: "fade", or {effect, duration, easing}. animate()'s enter option is the value a channel starts from.
exitEffectboolean | "fade" | object - How rows that leave in a keyed update disappear, as enterEffect. animate()'s exit option is the value a channel ends at.
Animation
animationboolean - Animate changes to the mark's values. Default:
false. animationDurationnumber - How long an animated change takes. Default:
300 ms. animationEasing"linear" | "quad-in" | "quad-out" | "quad-in-out" | "cubic-in" | "cubic-out" | "cubic-in-out" | "sine-in-out" - The animation's easing. Default:
"cubic-in-out".
Symbol
shapestring | column | string[] - The point symbol: a shape name, a column of categories mapped to shapes, or one name per row. Default:
"circle". shapeScalescale - A categorical() scale from the shape column's categories to shape names.
Legend settings
legendFontSizenumbersetting - The size of the mark's legend text. Default: the theme's (14 in the default theme). In px.
legendFontFamilystringsetting - The font of the mark's legend text, a CSS font-family. Default: the plot's font.
legendTextColorcolorsetting - The color of the mark's legend text. Default:
"#40505d". legendTickFormatstringsetting - How a colorbar labels numbers: a d3-format string, or a %-pattern for dates. Default:
".3~g".
Color settings
quantizebooleansetting - Step a numeric fill or color into `levels` colors instead of a smooth gradient. Default:
false. levelsnumbersetting - How many colors quantize steps through. Default:
10.
Limits
maxElementsnumbersetting - The most rows the mark prepares on the GPU. Default:
250000.
The mark's own axes
xTransform"linear" | "log" | "sqrt" | "symlog"setting - This mark's own x transform, instead of its frame's. Default: its frame's.
xInvertbooleansetting - Reverse this mark's x direction. Default:
false. xbounds[number, number]setting - The x extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
xrange[number, number]setting - Where this mark's x extent lands, in its frame's world units. Default: its frame's.
yTransform"linear" | "log" | "sqrt" | "symlog"setting - This mark's own y transform, instead of its frame's. Default: its frame's.
yInvertbooleansetting - Reverse this mark's y direction. Default:
false. ybounds[number, number]setting - The y extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
yrange[number, number]setting - Where this mark's y extent lands, in its frame's world units. Default: its frame's.
zTransform"linear" | "log" | "sqrt" | "symlog"setting - This mark's own z transform, instead of its frame's. Default: its frame's.
zInvertbooleansetting - Reverse this mark's z direction. Default:
false. zbounds[number, number]setting - The z extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
zrange[number, number]setting - Where this mark's z extent lands, in its frame's world units. Default: its frame's.
Usage
Marginals draws a scatter of x against y with a histogram of x above it and one of y to its right, as seaborn’s jointplot draws it: three Plots whose plot areas line up, each histogram sharing the scatter’s domain on its axis and following it as the scatter pans and zooms. The histograms take a fifth of height (at least 48 px) and have no axes of their own; bins sets both.
Its other props go to the scatter’s Points: fill="species" colors the points by a column (with the scatter’s legend), size, opacity, tooltip and brush work as on Points. Its children are drawn in the scatter’s Plot, over the points (a Smooth, rules, labels). Give the rows with data, or put the Marginals in a Data. It sits where a Plot does: in a Scene, Row, Column or Grid, not inside a Plot. Its PNG, SVG and PDF exports compose its three views; bound in Svelte, view("top"), view("main") and view("right") give each view’s Plot handle.
Marginals is a chart template, built from Plots, Points and Histograms: import it from hmplot/charts in JavaScript or use hm.charts.Marginals in Python. Its panels fill their grid cells in both live views and image exports.
See the executable marginal distributions recipe for human-readable axis labels and category colors. The histogram count axes fit their counts automatically. Do not pin a count domain to [0, 1] unless the histogram is normalized to that range; raw counts would clip into solid blocks. Use Marginals rather than manually aligning a Row and Column of plots.
hm.check(chart) reports the scatter and both histograms together, including their diagnostics and the composed figure PNG.