Skip to content

ferrum.coord

Coordinate system classes that control how positional encodings map to the plot area.

Coordinate-system declarations for ferrum charts.

CoordFlip dataclass

Flip the x and y axes — e.g. for horizontal bar charts.

Pass to Chart.coord(CoordFlip()).

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="value", y="category").mark_bar().coord(
...     fm.CoordFlip()
... )

to_spec_dict 

to_spec_dict() -> str

Return the string token passed to ChartSpec coord param.

CoordCartesian dataclass

Standard Cartesian coordinates with optional domain and clip overrides.

Parameters:

Name Type Description Default
xlim (float, float) | None

Explicit x-axis domain (min, max). None uses data extent.

 None
ylim (float, float) | None

Explicit y-axis domain (min, max). None uses data extent.

 None
expand bool

Add padding around the data extent (default True).

 True
clip bool

Clip marks to the plot area (default True).

 True

Examples:

>>> fm.Chart(df).mark_point().encode(x="x", y="y").coord(
...     fm.CoordCartesian(xlim=(0, 100))
... )

to_spec_dict 

to_spec_dict() -> dict

Return dict serialization for ChartSpec coord param.

CoordFixed dataclass

Cartesian coordinates with a fixed aspect ratio.

Parameters:

Name Type Description Default
ratio float

Width-to-height ratio of one data unit. 1.0 makes the plot square in data space.

 1.0
xlim (float, float) | None

Explicit x-axis domain.

 None
ylim (float, float) | None

Explicit y-axis domain.

 None
expand bool

Add padding around data extent (default True).

 True
clip bool

Clip marks to plot area (default True).

 True

Examples:

>>> fm.Chart(df).mark_point().encode(x="x", y="y").coord(
...     fm.CoordFixed(ratio=1.0)
... )

to_spec_dict 

to_spec_dict() -> dict

Return dict serialization for ChartSpec coord param.

CoordPolar dataclass

Polar coordinates for pie and radial charts.

The theta parameter names which encoding channel ("x" or "y") is interpreted as the angular variable. The other channel is used as the radial variable (for scatter-in-polar mode); omit it for pie/donut charts.

Parameters:

Name Type Description Default
theta ('x', 'y')

Which encoding channel maps to the angle.

 "x"
start float

Starting angle in radians (default 0 = 12 o'clock).

 0.0
direction (1, -1)

1 for clockwise, -1 for counter-clockwise.

 1
inner_radius float

Inner radius in pixels. 0 (default) gives a filled pie slice; any positive value creates a donut with a hole of that radius.

 0.0
outer_radius float or None

Outer radius in pixels. None (default) fills to half the smaller panel dimension.

 None
pad_angle float

Angular gap between adjacent slices in radians (default 0).

 0.0

Examples:

Pie chart::

fm.Chart(df).mark_arc().encode(x="value", color="category").coord(
    fm.CoordPolar(theta="x")
)

Donut with 60 px hole::

fm.Chart(df).mark_arc().encode(x="value", color="category").coord(
    fm.CoordPolar(theta="x", inner_radius=60)
)

to_spec_dict 

to_spec_dict() -> dict

Return dict serialization for ChartSpec coord param.

CoordGeo dataclass

Geographic map-projection coordinates.

Parameters:

Name Type Description Default
projection str

One of "mercator", "albers_usa", "equal_earth", "natural_earth", "orthographic", "equirectangular".

 'mercator'

Examples:

>>> fm.Chart(geojson_df).mark_geoshape().coord(
...     fm.CoordGeo(projection="equal_earth")
... )

to_spec_dict 

to_spec_dict() -> dict

Return dict serialization for ChartSpec coord param.