Skip to content

rect ​

Draws a rectangle for each data item. The most common mark — bars, stacked bars, mosaic tiles, and waffle cells are all rectangles.

python
from gofish import chart, spread, rect

chart(seafood).flow(spread(by="lake", dir="x")).mark(rect(h="count")).render(
    w=500, h=300, axes=True
)

Signature ​

python
rect(*, x=None, cx=None, x2=None, w=None, em_x=None,
     y=None, cy=None, y2=None, h=None, em_y=None,
     dims=None,
     fill=None, stroke=None, stroke_width=None, opacity=None, filter=None,
     rx=None, ry=None, aspect_ratio=None, inset=None, key=None) -> Mark

Closed signature — no catch-all **kwargs. An unrecognized keyword raises a TypeError at the call site instead of being accepted and then quietly ignored at render time, which is the class of bug that motivated closing it (see Frontend IR).

Parameters ​

A rectangle. Box geometry via the shared dims channels.

OptionTypeDefaultDescription
wint | float | str | LengthValueWidth. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.
hint | float | str | LengthValueHeight. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.
filterFilter | strA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
keystrInternal per-node key override.
rxfloatCorner radius, x. Default: ry, or 0 when neither is given.
ryfloatCorner radius, y. Default: rx, or 0 when neither is given.
aspect_ratiofloatw/h ratio to enforce; the constraining axis wins when both are data-driven.
insetfloat | LengthValue0Pixels drawn in from each side of the space the rect fills, on an axis where it has no size or span of its own (a bar's width in a spread or a partition cell), so neighbors are drawn apart. A side the rect sizes itself, such as a bar's data height, is never inset. It changes only what is drawn: the rect's box stays the space it was given. Also percent(n), n percent of that space on each axis: percent(10) draws a bar at 80% of its band. The percent and any pixels added to it are each 0 or more.
debugboolDev-only flag: logs this mark's key and datum to the console as it is built. It changes nothing about what is drawn.

Box dimensions ​

OptionTypeDefaultDescription
xint | float | strLeft edge position.
cxint | float | strCenter x.
x2int | float | strRight edge position.
em_xboolEmbed x in the parent's x space.
yint | float | strStart edge on y: the top edge where y reads top-down, the bottom edge where it grows upward.
cyint | float | strCenter y.
y2int | float | strOther y edge position.
em_yboolEmbed y in the parent's y space.
dimsdictBox dimensions by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}.

Paint ​

OptionTypeDefaultDescription
fillstrFill color, or a field name for a color scale.
strokestrStroke color. Defaults to fill.
stroke_widthfloat0Stroke width in pixels.
opacityfloat1Opacity, 0 to 1.

Returns a Mark for use in .mark(). To attach a text label, chain .label(accessor, ...) on the returned mark rather than passing a label option here.

Axis names ​

x, y, w, and h mean the first and second axis in any coordinate space. Under polar that is the angle and the radius.

To use the names a coordinate space gives its axes, pass them in the dims dict. Each key is an axis name, and each value is either a position (like x) or a dict with any of "min", "center", "max", "size", and "embedded":

python
# Inside Coord.polar(): the same wedge as rect(w=0.4, h="value")
rect(dims={"theta": {"size": 0.4}, "r": {"size": "value"}})

"x" and "y" are always valid keys too. A name the enclosing coordinate space does not declare raises an error that lists the ones it does, and setting the same part of an axis twice (for example w and dims["theta"]["size"]) is an error. dims is the one keyword for axis names, so the rest of the signature stays closed. The same keyword works on ellipse, petal, text, image, and layer.

Encoding ​

Each option takes a constant or a field name (a string column in your data):

python
rect(h="count", fill="species")  # height and color from fields
rect(h="count", fill="#4e79a7")  # height from data, constant color
rect(w=20, h="count")            # constant width, data-driven height

Examples ​

python
# Stacked bars
chart(seafood).flow(
    spread(by="lake", dir="x"),
    stack(by="species", dir="y"),
).mark(rect(h="count", fill="species"))

# Rounded, outlined tiles
chart(data).mark(rect(h="count", rx=4, stroke="white", stroke_width=2))