Mojo function 🡭

facet_by

fn def facet_by(df: DataFrame, column: String, missing: Missing = Missing.DRAW, label: String = "(missing)", order: List[String] = List()) -> List[FacetPart]

Split df into one part per distinct value of column, in first-appearance order (#364).

This is what a faceted figure needs and what a plotting call cannot express: every mark already takes a frame, so a facet is a loop over the parts rather than a facet-shaped variant of each of the 78 one-call functions.

var panels = List[AnyChart]()
for part in facet_by(sales, "region"):
    panels.append(
        scatter(part.frame, x="spend", y="revenue", title=part.name).erased()
    )
save_facets(panels, 2, "by-region.png")

Panels drawn this way have independent domains, because each is scaled from its own rows. When the comparison between panels is the point, pass the pooled extent to each panel’s scale_x_domain()/scale_y_domain() – pooled_extent() below computes it – or hand the panels to render_facets(shared_y_scale=True).

The faceting column may be strings or numbers; numbers are named by their own formatting, which is what a reader sees on the panel.

Args:

• df (DataFrame): The frame to split.
• column (String): The column whose distinct values become the parts.
• missing (Missing): The policy in force (Theme.missing).
• label (String): What an absent level is called (Theme.missing_category_label).
• order (List[String]): Optional panel order. It must name every observed level; absent levels are reserved but do not create empty panels.

Returns:

List[FacetPart]: One part per level, in first-appearance order.

Raises:

Error: No column of that name, or, under Missing.RAISE, a row whose level is absent.