Skip to content

layer ​

Overlays multiple children in the same coordinate space without any layout offset.

python
from gofish import layer, rect, ellipse

layer([
    rect(w=100, h=80, fill="#9ecae1"),
    ellipse(w=60, h=60, fill="#fcae91"),
]).render()

Both shapes occupy the same space. The ellipse is drawn on top of the rectangle because it appears second in the list.

Signature ​

python
layer(children, **options) -> Mark

The children are a positional list of marks; layout options are passed as kwargs. A child may also be a nested chart(...), a .layer(...) chain, or a layer of charts, as in a chart's mark(...). layer always returns the combinator mark, whatever its children are, so it renders on its own or sits in a mark position. Children typically carry .name(...) tags so they can be referenced from a .relate(...) callback or by a sibling relational mark like line / ref.

Parameters ​

Compose children on the same canvas at (0, 0) unless placed by constraints. Also accepts explicit box dims when given a self-scaling size.

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.
coordAnyCoordinate transform (Coord.polar(), Coord.clock(), Coord.wavy(), ...) the children are drawn in. Given one, the layer becomes that coordinate boundary.
axesbool | dictDraw the coordinate axes of this layer's coord. Ignored on a layer with no coord.
paddingfloat30Pixels the content of this layer's coord keeps from the edge of its box (a polar space's outer radius is half the shorter side less this). Ignored on a layer with no coord.
transformdictNon-affine-foldable scale applied to the composed children.
boxboolTrue renders this as a coordinate-space transparent "box" boundary rather than a plain layer.

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}.

Coordinate space ​

With coord=, the layer is the box of that coordinate space: its children are drawn in it, and axes and padding apply to it.

python
from gofish import layer, chart, stack, rect, Coord

layer([
    chart(seafood)
    .flow(stack(by="species", dir="x"))
    .mark(rect(w="count", fill="species")),
], coord=Coord.clock(), w=300, h=300)

Z-ordering ​

By default, children are drawn in the order they appear in the list — later children appear on top. You can override this with .z_order(n) on any child. Children are sorted by z-order value before rendering; lower values are drawn first (underneath). Children with the same z-order value keep their original list order.

python
from gofish import layer, rect, ellipse

layer([
    ellipse(w=60, h=60, fill="#fcae91").z_order(1),  # forced on top
    rect(w=100, h=80, fill="#9ecae1").z_order(0),     # forced underneath
])

.z_order() is available on every Mark. The chart-composing form of layer (which overlays whole charts) exposes the same control on a ChartBuilder as .z_order().

Notes ​

  • This is the low-level combinator-form layer, which wraps an explicit list of marks and renders directly. To overlay whole charts — for example to draw one chart's marks on top of another and relate them with cross-chart constraints — use the chart-composing form layer([chart1, chart2]), which composes ChartBuilder instances and accepts .relate(...).
  • Naming a child (rect(...).name("a")) makes it addressable from a .relate(...) callback and from a sibling line or ribbon drawn over the same layer.