Skip to content

circle ​

Draws a circle for each data item. The mark for scatter plots, bubble charts, and dot-based glyphs. It is an ellipse locked to a 1:1 aspect ratio, and it takes the same box dimensions.

The diameter is set by at most one of r, area, w, or h. A number is pixels (square pixels for area), and a field name, field(...), or function is data.

  • r is the radius, so the diameter is 2r for every kind of value. A data r sizes both axes.
  • area is the circle's area. It is an area channel: it sums the mark's rows and hands the circle the square root of the sum, so the area, not the radius, is proportional to the value. A data area sizes both axes.
  • w or h is the diameter along that axis. The other axis takes the same length, so a data w or h sizes both axes at one scale. Where the circle is placed at a data value on the other axis (a scatter with only x), the other axis follows it in pixels and takes no room there.

With none of them, the circle fills the space it is given. Passing more than one is an error.

python
from gofish import chart, scatter, circle

chart(catch_locations, axes=True).flow(scatter(by="lake", x="x", y="y")).mark(
    circle(r=5)
).render(w=500, h=300)

Signature ​

python
circle(r=None, area=None, w=None, h=None, x=None, cx=None, x2=None, y=None, cy=None,
       y2=None, em_x=None, em_y=None, dims=None, fill=None, stroke=None,
       stroke_width=None, opacity=None, fill_opacity=None, debug=None) -> Mark

Parameters ​

A circle: an ellipse locked to a 1:1 aspect ratio, with the same box dimensions. Its size is set by at most one of r, area, w, or h and applies to both axes; with none, the circle fills the space it is given.

OptionTypeDefaultDescription
filterFilter | strA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
rint | float | strRadius. The diameter is 2r for a number (pixels), a field name, or an accessor alike. Pass at most one of r, area, w, and h.
areaint | float | strArea. A number is square pixels. A field name or an accessor is data, summed over the mark's rows, and the circle's area is proportional to it, so its radius grows with the square root. Pass at most one of r, area, w, and h.
fillstrFill color, or a field name for a color scale.
strokestrStroke color. Defaults to fill.
stroke_widthfloat0Stroke width in pixels.
opacityint | float | str1Opacity, 0 to 1, applied to fill and stroke: a number, a field name, or a per-datum accessor (in JS also a live(...) value, which does not cross the wire).
fill_opacityfloatOpacity of the fill alone, 0 to 1. The stroke keeps opacity.
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.
wint | float | strWidth.
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.
hint | float | strHeight.
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}.

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.

Examples ​

python
# Fixed-size dots
chart(data).flow(scatter(x="x", y="y")).mark(circle(r=5))

# Bubble chart — radius encodes a field
chart(data).flow(scatter(x="x", y="y")).mark(circle(r="population", fill="region"))

# Area proportional to a field, one circle per lake
chart(data).flow(spread(by="lake", dir="x")).mark(circle(area="count", fill="lake"))

# Diameter read against the y axis
chart(data).flow(spread(by="category", dir="x")).mark(circle(h="value"))

# Outlined dots
chart(data).flow(scatter(x="x", y="y")).mark(
    circle(r=4, fill="white", stroke="black", stroke_width=2)
)