workforce-plotting 0.3.0__tar.gz → 0.4.0__tar.gz

{workforce_plotting-0.3.0/src/workforce_plotting.egg-info → workforce_plotting-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workforce-plotting
-Version: 0.3.0
+Version: 0.4.0
 Summary: Simple plotnine figures with Opportunity Insights styling.
 Author: Corey Gelb-Bicknell
 License-Expression: MIT
@@ -53,8 +53,7 @@ conversion dependency. Pandas input needs no extra.
 
 ## Getting help
 
-Function help includes every argument, its default, the expected column names,
-and a short example:
+Function help describes the arguments and shows a short example.
 
 ```python
 from workforce_plotting import plot_lines
@@ -84,8 +83,10 @@ plotnine plot, with no automatic saving.
 Its points remain unconnected even when a separate fitted curve is supplied.
 `plot_validation` accepts `x_lower`, `x_upper`, `y_lower`, `y_upper`,
 `gaps="horizontal"` or `"vertical"`, and a common `(min, max)` pair of `limits`.
+Use `plot_validation(df, x="dml", y="rct", series="program_name")`
+to color the estimates, intervals, and gap lines by program.
 The identity line has slope one in data units; the panel follows the figure's
-aspect ratio. Other functions accept `series` for discrete groups. Use ordered
+aspect ratio. All five functions accept `series` for discrete groups. Use ordered
 categorical columns to control color/legend order. Colors are teal, orange, navy,
 purple, blue, red, and dark green from the public `oi_tools.figures.OIColors` API.
 For a different mapping, add a plotnine manual color or fill scale.
@@ -107,29 +108,40 @@ the scatter data. No smoothing, RMSE calculation, confidence-interval estimation
 or automatic saving happens inside the plotting functions.
 
 Add `pn.coord_flip()` for horizontal bars/intervals; use ordinary plotnine scales
-for dollars, percentages, limits, or log axes. The default font is Times New Roman; install it locally to match the paper.
+for dollars, percentages, limits, or log axes. The default font is Times New Roman when installed. The theme checks for
+DejaVu Serif, DejaVu Sans, STIXGeneral, and other available families before
+rendering. An empty font list triggers registration of the bundled DejaVu Serif.
 Override fonts, dimensions, or text size with
 `theme_workforce(base_family=..., base_size=..., width=..., height=...)`.
 For example, `base_family="DejaVu Sans"` selects sans-serif type.
-Titles, logos, notes, and paper-specific annotations belong in the example/caller.
+Use `title=` for a plot title. Add logos, notes, and paper-specific annotations
+with plotnine.
 
 ## Paper defaults
 
-- Times New Roman, 12-point text, 1.2 line spacing, and an 8-by-5-inch canvas.
+- Times New Roman when available, 12-point text, 1.2 line spacing, and an
+  8-by-5-inch canvas.
 - Gray 0.54-point axes/ticks, 10-point axis-title padding in both directions,
-  2% outer margins, five-point ticks, no grid, and an inside upper-left vertical
+  2% outer margins, 4.14-point ticks, no grid, and an inside upper-left vertical
   legend with a transparent background.
 - Dots use plotnine size 3.75. Legend dots are 25% larger; connected-line plots
   show dots in the legend when points are enabled and lines otherwise.
 - Confidence intervals use a 0.54-point stroke. Dots and interval strokes are
   separate layers, so changing one does not change the other.
 
+All five functions accept `title=` for a centered plot title. Grouped bars,
+validation plots, and intervals on categorical axes put the legend above the panel.
+For longer category names, supply
+labels with line breaks or use `scale_x_discrete(labels=...)` to wrap them.
+Datetime x-axes covering less than a day show clock times in the data's time zone.
+
 Point-based functions accept `point_size`. Those with intervals also accept
-`ci_width` (physical stroke width in points) and `cap_width` (data units,
-perpendicular to the interval). A cap width of zero omits caps. `plot_lines`
-defaults to 0.08; scatter, validation, and interval plots default to zero.
-A data-unit cap width does not imply a fixed length in points across figures.
-For grouped `plot_intervals`, cap widths are narrowed with the dodged groups.
+`ci_width` (stroke width in points) and `cap_width` (plot-axis units
+perpendicular to the interval). Caps default to 1% of the numeric axis span
+or 0.12 category units on a categorical axis. A single numeric x position
+has no default caps. On a log axis, the cap width
+uses the transformed axis units. Set `cap_width=0` to omit caps. Grouped
+`plot_intervals` narrows the default caps when x positions are closely spaced.
 
 Dollar formatting is optional, rather than imposed on every outcome:
 
@@ -140,15 +152,14 @@ p += pn.scale_y_continuous(labels=dollars)  # -$1K, $0, $2.5K, ...
 ```
 
 `plot_validation` keeps its existing name and rectangular shape. Both axes
-share numeric limits, but equal physical scaling is not imposed. Palette and
-line-width defaults are unchanged.
+share numeric limits, but equal physical scaling is not imposed.
 
 Titles remain ordinary plotnine labels. Move the legend without changing the
 plot constructor or shared theme:
 
 ```python
 p += pn.labs(title="Earnings Before and After Enrollment")
-p += pn.theme(legend_position_inside=(0.97, 0.97),
+p += pn.theme(legend_position="inside", legend_position_inside=(0.97, 0.97),
               legend_justification_inside=(1, 1))  # upper-right
 ```
 
@@ -172,7 +183,9 @@ p = (
 
 For unconnected cohort estimates plus a supplied curve, use
 `plot_scatter(df, x="year", y="effect", lower="lower", upper="upper", fitted=curve)`.
-For estimates across categories without a curve, use `plot_intervals`.
+For estimates across categories, use `plot_intervals`. Pass `fitted=` to draw a
+curve from supplied values. For a single series, a supplied curve appears in teal
+with gray points in both `plot_intervals` and `plot_scatter`.
 
 ## Styling your own plots
 
@@ -224,6 +237,14 @@ python examples/paper_examples.py outputs/examples
 pytest
 ```
 
+## Changes in 0.4
+
+- Validation plots accept `series=` to color by program or another grouping column.
+- Plot titles are larger and centered, confidence intervals have short caps by
+  default, and interval plots accept a supplied fit.
+- Numeric group labels, sparse groups, missing estimates, and intraday axes
+  render more reliably.
+
 ## Changes in 0.3
 
 - Paper defaults: Times New Roman, inside vertical legends, five-point ticks,

{workforce_plotting-0.3.0 → workforce_plotting-0.4.0}/README.md

@@ -29,8 +29,7 @@ conversion dependency. Pandas input needs no extra.
 
 ## Getting help
 
-Function help includes every argument, its default, the expected column names,
-and a short example:
+Function help describes the arguments and shows a short example.
 
 ```python
 from workforce_plotting import plot_lines
@@ -60,8 +59,10 @@ plotnine plot, with no automatic saving.
 Its points remain unconnected even when a separate fitted curve is supplied.
 `plot_validation` accepts `x_lower`, `x_upper`, `y_lower`, `y_upper`,
 `gaps="horizontal"` or `"vertical"`, and a common `(min, max)` pair of `limits`.
+Use `plot_validation(df, x="dml", y="rct", series="program_name")`
+to color the estimates, intervals, and gap lines by program.
 The identity line has slope one in data units; the panel follows the figure's
-aspect ratio. Other functions accept `series` for discrete groups. Use ordered
+aspect ratio. All five functions accept `series` for discrete groups. Use ordered
 categorical columns to control color/legend order. Colors are teal, orange, navy,
 purple, blue, red, and dark green from the public `oi_tools.figures.OIColors` API.
 For a different mapping, add a plotnine manual color or fill scale.
@@ -83,29 +84,40 @@ the scatter data. No smoothing, RMSE calculation, confidence-interval estimation
 or automatic saving happens inside the plotting functions.
 
 Add `pn.coord_flip()` for horizontal bars/intervals; use ordinary plotnine scales
-for dollars, percentages, limits, or log axes. The default font is Times New Roman; install it locally to match the paper.
+for dollars, percentages, limits, or log axes. The default font is Times New Roman when installed. The theme checks for
+DejaVu Serif, DejaVu Sans, STIXGeneral, and other available families before
+rendering. An empty font list triggers registration of the bundled DejaVu Serif.
 Override fonts, dimensions, or text size with
 `theme_workforce(base_family=..., base_size=..., width=..., height=...)`.
 For example, `base_family="DejaVu Sans"` selects sans-serif type.
-Titles, logos, notes, and paper-specific annotations belong in the example/caller.
+Use `title=` for a plot title. Add logos, notes, and paper-specific annotations
+with plotnine.
 
 ## Paper defaults
 
-- Times New Roman, 12-point text, 1.2 line spacing, and an 8-by-5-inch canvas.
+- Times New Roman when available, 12-point text, 1.2 line spacing, and an
+  8-by-5-inch canvas.
 - Gray 0.54-point axes/ticks, 10-point axis-title padding in both directions,
-  2% outer margins, five-point ticks, no grid, and an inside upper-left vertical
+  2% outer margins, 4.14-point ticks, no grid, and an inside upper-left vertical
   legend with a transparent background.
 - Dots use plotnine size 3.75. Legend dots are 25% larger; connected-line plots
   show dots in the legend when points are enabled and lines otherwise.
 - Confidence intervals use a 0.54-point stroke. Dots and interval strokes are
   separate layers, so changing one does not change the other.
 
+All five functions accept `title=` for a centered plot title. Grouped bars,
+validation plots, and intervals on categorical axes put the legend above the panel.
+For longer category names, supply
+labels with line breaks or use `scale_x_discrete(labels=...)` to wrap them.
+Datetime x-axes covering less than a day show clock times in the data's time zone.
+
 Point-based functions accept `point_size`. Those with intervals also accept
-`ci_width` (physical stroke width in points) and `cap_width` (data units,
-perpendicular to the interval). A cap width of zero omits caps. `plot_lines`
-defaults to 0.08; scatter, validation, and interval plots default to zero.
-A data-unit cap width does not imply a fixed length in points across figures.
-For grouped `plot_intervals`, cap widths are narrowed with the dodged groups.
+`ci_width` (stroke width in points) and `cap_width` (plot-axis units
+perpendicular to the interval). Caps default to 1% of the numeric axis span
+or 0.12 category units on a categorical axis. A single numeric x position
+has no default caps. On a log axis, the cap width
+uses the transformed axis units. Set `cap_width=0` to omit caps. Grouped
+`plot_intervals` narrows the default caps when x positions are closely spaced.
 
 Dollar formatting is optional, rather than imposed on every outcome:
 
@@ -116,15 +128,14 @@ p += pn.scale_y_continuous(labels=dollars)  # -$1K, $0, $2.5K, ...
 ```
 
 `plot_validation` keeps its existing name and rectangular shape. Both axes
-share numeric limits, but equal physical scaling is not imposed. Palette and
-line-width defaults are unchanged.
+share numeric limits, but equal physical scaling is not imposed.
 
 Titles remain ordinary plotnine labels. Move the legend without changing the
 plot constructor or shared theme:
 
 ```python
 p += pn.labs(title="Earnings Before and After Enrollment")
-p += pn.theme(legend_position_inside=(0.97, 0.97),
+p += pn.theme(legend_position="inside", legend_position_inside=(0.97, 0.97),
               legend_justification_inside=(1, 1))  # upper-right
 ```
 
@@ -148,7 +159,9 @@ p = (
 
 For unconnected cohort estimates plus a supplied curve, use
 `plot_scatter(df, x="year", y="effect", lower="lower", upper="upper", fitted=curve)`.
-For estimates across categories without a curve, use `plot_intervals`.
+For estimates across categories, use `plot_intervals`. Pass `fitted=` to draw a
+curve from supplied values. For a single series, a supplied curve appears in teal
+with gray points in both `plot_intervals` and `plot_scatter`.
 
 ## Styling your own plots
 
@@ -200,6 +213,14 @@ python examples/paper_examples.py outputs/examples
 pytest
 ```
 
+## Changes in 0.4
+
+- Validation plots accept `series=` to color by program or another grouping column.
+- Plot titles are larger and centered, confidence intervals have short caps by
+  default, and interval plots accept a supplied fit.
+- Numeric group labels, sparse groups, missing estimates, and intraday axes
+  render more reliably.
+
 ## Changes in 0.3
 
 - Paper defaults: Times New Roman, inside vertical legends, five-point ticks,

{workforce_plotting-0.3.0 → workforce_plotting-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workforce-plotting"
-version = "0.3.0"
+version = "0.4.0"
 description = "Simple plotnine figures with Opportunity Insights styling."
 readme = "README.md"
 requires-python = ">=3.12"

workforce_plotting-0.4.0/src/workforce_plotting/figures.py

@@ -0,0 +1,394 @@
+"""Workforce plots, shared paper styling, and the Opportunity Insights palette."""
+
+from math import pi, sqrt
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import plotnine as pn
+from matplotlib import font_manager, get_data_path
+from mizani.labels import label_date
+from mizani.palettes import hue_pal
+from oi_tools.figures import OIColors as WFColors, theme_oi
+
+PALETTE = [WFColors.TEAL, WFColors.ORANGE, WFColors.NAVY, WFColors.PURPLE,
+           WFColors.BLUE, WFColors.RED, WFColors.DARK_GREEN]
+
+
+def theme_workforce(base_size=12, base_family="Times New Roman", width=8, height=5):
+    """Apply the paper style to a plotnine plot.
+
+    base_size: Base text size in points (12).
+    base_family: Font family (Times New Roman). The theme silently selects
+        an available fallback when the preferred paper fonts are missing.
+    width, height: Figure size in inches (8 by 5).
+
+    Example
+    -------
+    >>> p = p + theme_workforce(width=10, height=6)
+    """
+    fallback_families = ("DejaVu Serif", "DejaVu Sans", "STIXGeneral")
+    if base_family == "Times New Roman" or base_family in fallback_families:
+        available = set(font_manager.get_font_names())
+        if base_family not in available:
+            if not available:
+                bundled = Path(get_data_path()) / "fonts" / "ttf"
+                for path in bundled.glob("DejaVuSerif*.ttf"):
+                    font_manager.fontManager.addfont(path)
+                available = set(font_manager.get_font_names())
+                if not available:
+                    raise RuntimeError("Matplotlib requires a font to render plot text.")
+            base_family = next(
+                (family for family in fallback_families if family in available),
+                min(available),
+            )
+    return theme_oi(base_size, base_family, width, height) + pn.theme(
+        text=pn.element_text(linespacing=1.2),
+        axis_line=pn.element_line(color="#A0A0A0", size=0.54),
+        axis_ticks=pn.element_line(color="#A0A0A0", size=0.54),
+        axis_ticks_length=4.14,
+        axis_text=pn.element_text(color="black", size=base_size),
+        axis_title=pn.element_text(size=base_size),
+        axis_title_y=pn.element_text(margin={"r": 10}),
+        axis_title_x=pn.element_text(margin={"t": 10}),
+        plot_title=pn.element_text(size=base_size + 2, ha="center", margin={"b": 8}),
+        plot_title_position="plot",
+        legend_position="inside",
+        legend_position_inside=(0.03, 0.97),
+        legend_justification_inside=(0, 1),
+        legend_direction="vertical",
+        legend_background=pn.element_blank(),
+        legend_text=pn.element_text(size=base_size),
+        legend_title=pn.element_blank(),
+        plot_margin=0.02,
+        panel_grid=pn.element_blank(),
+        axis_ticks_minor=pn.element_blank(),
+        legend_key=pn.element_blank(),
+    )
+
+
+def dollars(values):
+    """Format tick values in dollars as $1K, $2.5K, and $0.
+
+    values: Dollar amounts supplied by the axis scale.
+
+    Example
+    -------
+    >>> p = p + pn.scale_y_continuous(labels=dollars)
+    """
+    return [f"{'-' if v < 0 else ''}${abs(v) / 1000:g}K" if v else "$0" for v in values]
+
+
+def _data(data):
+    """Keep pandas inputs; convert Polars using its public conversion method."""
+    if isinstance(data, pd.DataFrame):
+        return data
+    return data.to_pandas()
+
+
+def _interval(lower, upper):
+    if (lower is None) != (upper is None):
+        raise ValueError("Supply both lower and upper interval columns, or neither.")
+
+
+def _group_data(data, series):
+    data = _data(data)
+    if series is not None and not _categorical(data[series]):
+        return data.assign(**{series: data[series].astype("category")})
+    return data
+
+
+def _group_colors(data, series, fitted=None):
+    groups = data[series] if fitted is None else pd.concat([data[series], fitted[series]])
+    count = groups.nunique()
+    return PALETTE if count <= len(PALETTE) else hue_pal()(count)
+
+
+def _x_spacing(values):
+    spacing = values[np.isfinite(values)].drop_duplicates().sort_values().diff().min()
+    return spacing if pd.notna(spacing) else 1
+
+
+class _IntervalDodge(pn.position_dodge):
+    def setup_params(self, data):
+        params = super().setup_params(data)
+        params["width"] = 0.5 * _x_spacing(data["x"])
+        return params
+
+
+class _ErrorBar(pn.geom_errorbar):
+    DEFAULT_PARAMS = {**pn.geom_errorbar.DEFAULT_PARAMS, "width": None, "categorical": False}
+
+    def setup_data(self, data):
+        # Plotnine has already mapped discrete axes and transformed log axes.
+        width = self.params["width"]
+        if width is None:
+            x = data.loc[np.isfinite(data["x"]), "x"]
+            span = x.max() - x.min()
+            width = 0.01 * span if span > 0 else 0
+            if self.params["categorical"]:
+                width = 0.12
+            if isinstance(self.params["position"], _IntervalDodge):
+                width = min(width, 0.5 * _x_spacing(x))
+        data["width"] = width
+        return super().setup_data(data)
+
+
+class _Bar(pn.geom_col):
+    def setup_data(self, data):
+        data["width"] = self.params["width"] * _x_spacing(data["x"])
+        return super().setup_data(data)
+
+
+def _categorical(values):
+    return not (pd.api.types.is_numeric_dtype(values)
+                or pd.api.types.is_datetime64_any_dtype(values))
+
+
+def _time_axis(plot, values):
+    if not pd.api.types.is_datetime64_any_dtype(values):
+        return plot
+    start, end = values.min(), values.max()
+    span = end - start
+    if not pd.Timedelta(0) < span < pd.Timedelta(days=1):
+        return plot
+    fmt = "%H:%M:%S" if span < pd.Timedelta(minutes=5) else "%H:%M"
+    if start.date() != end.date():
+        fmt = "%m-%d " + fmt
+    return plot + pn.scale_x_datetime(labels=label_date(fmt, tz=values.dt.tz))
+
+
+def plot_lines(data, *, x, y, series=None, lower=None, upper=None, points=True,
+               point_size=3.75, ci_width=0.54, cap_width=None, title=None):
+    """Connect points in x order within each series.
+
+    data: Pandas or Polars dataframe with one row per point.
+    x, y: Column names for the horizontal positions and values.
+    series: Optional group column for separate lines and colors.
+    lower, upper: Optional pair of y interval-bound columns.
+    points: Draw dots (True).
+    point_size: Dot size in plotnine units (3.75).
+    ci_width: Interval stroke width in points (0.54).
+    cap_width: Cap width in plot-axis units. Defaults to short caps. Use 0 for none.
+    title: Optional plot title.
+
+    Example
+    -------
+    >>> plot_lines(df, x="year", y="effect", series="group")
+    """
+    _interval(lower, upper)
+    mapping = pn.aes(x=x, y=y, group=1)
+    if series is not None:
+        mapping.update(color=series, group=series)
+    data = _group_data(data, series)
+    p = pn.ggplot(data, mapping)
+    if lower is not None:
+        p += _ErrorBar(pn.aes(ymin=lower, ymax=upper), width=cap_width,
+                       categorical=_categorical(data[x]), na_rm=True,
+                       size=ci_width / sqrt(pi), show_legend=False,
+                       **({} if series is not None else {"color": WFColors.TEAL}))
+    p += pn.geom_line(size=0.914, show_legend=not points,
+                      **({} if series is not None else {"color": WFColors.TEAL}))
+    if points:
+        p += pn.geom_point(size=point_size, stroke=0, na_rm=True,
+                           **({} if series is not None else {"color": WFColors.TEAL}))
+    if series is not None:
+        p += pn.scale_color_manual(values=_group_colors(data, series))
+        if points:
+            p += pn.guides(color=pn.guide_legend(override_aes={"size": point_size * 1.25}))
+    return _time_axis(p + theme_workforce() + pn.labs(title=title), data[x])
+
+
+def plot_validation(data, *, x, y, x_lower=None, x_upper=None,
+                    y_lower=None, y_upper=None, series=None, gaps=None, limits=None,
+                    point_size=3.75, ci_width=0.54, cap_width=None, title=None):
+    """Compare paired estimates against y=x using common axis limits.
+
+    data: Pandas or Polars dataframe with one row per pair.
+    x, y: Column names for the two estimates.
+    x_lower, x_upper: Optional pair of horizontal interval-bound columns.
+    y_lower, y_upper: Optional pair of vertical interval-bound columns.
+    series: Optional group column for coloring estimates and intervals.
+    gaps: Optional "horizontal" or "vertical" segments to the identity line.
+    limits: Common (min, max) range. Defaults to the estimates and bounds.
+    point_size: Dot size in plotnine units (3.75).
+    ci_width: Interval stroke width in points (0.54).
+    cap_width: Cap width in axis units (1% of the shared range). Use 0 for none.
+    title: Optional plot title.
+
+    Example
+    -------
+    >>> plot_validation(df, x="dml_effect", y="rct_effect")
+    """
+    _interval(x_lower, x_upper)
+    _interval(y_lower, y_upper)
+    if gaps not in (None, "vertical", "horizontal"):
+        raise ValueError("gaps must be None, 'vertical', or 'horizontal'.")
+    data = _group_data(data, series)
+    pairs = data[[x, y]].to_numpy(dtype=float, na_value=np.nan)
+    data = data.loc[np.isfinite(pairs).all(axis=1)]
+    expand = limits is None
+    if expand:
+        columns = [v for v in (x, y, x_lower, x_upper, y_lower, y_upper)
+                   if v is not None]
+        values = pd.concat([data[v] for v in columns]).to_numpy(dtype=float, na_value=np.nan)
+        values = values[np.isfinite(values)]
+        if not values.size:
+            raise ValueError("Supply at least one finite pair of estimates or explicit limits.")
+        limits = (values.min(), values.max())
+    if cap_width is None:
+        cap_width = 0.01 * (limits[1] - limits[0])
+    mapping = pn.aes(x=x, y=y)
+    if series is not None:
+        mapping.update(color=series)
+    point_color = {} if series is not None else {"color": WFColors.TEAL}
+    gap_color = {} if series is not None else {"color": WFColors.ORANGE}
+    p = pn.ggplot(data, mapping) + pn.geom_abline(
+        intercept=0, slope=1, color="black", size=0.6)
+    if gaps == "vertical":
+        p += pn.geom_segment(pn.aes(xend=x, yend=x), size=0.5, alpha=0.8,
+                             show_legend=False, **gap_color)
+    elif gaps == "horizontal":
+        p += pn.geom_segment(pn.aes(xend=y, yend=y), size=0.5, alpha=0.8,
+                             show_legend=False, **gap_color)
+    if x_lower is not None:
+        p += pn.geom_errorbarh(pn.aes(xmin=x_lower, xmax=x_upper, height=cap_width),
+                              size=ci_width / sqrt(pi), alpha=0.5, na_rm=True,
+                              show_legend=False, **point_color)
+    if y_lower is not None:
+        p += pn.geom_errorbar(pn.aes(ymin=y_lower, ymax=y_upper, width=cap_width),
+                             size=ci_width / sqrt(pi), alpha=0.5, na_rm=True,
+                             show_legend=False, **point_color)
+    p += pn.geom_point(size=point_size, stroke=0, **point_color)
+    p = (p + pn.coord_cartesian(xlim=limits, ylim=limits, expand=expand)
+         + theme_workforce() + pn.labs(title=title))
+    if series is not None:
+        p = (p + pn.scale_color_manual(values=_group_colors(data, series),
+                                       labels=lambda values: [
+                                           "Missing" if pd.isna(value) else str(value)
+                                           for value in values
+                                       ])
+             + pn.guides(color=pn.guide_legend(ncol=2, byrow=True,
+                                             override_aes={"size": point_size * 1.25}))
+             + pn.theme(legend_position="top", legend_direction="horizontal"))
+    return p
+
+
+def plot_bars(data, *, x, y, series=None, title=None):
+    """Draw bars from values you supply.
+
+    data: Pandas or Polars dataframe with one row per bar.
+    x: Category column. Use ordered categories to set the display order.
+    y: Numeric bar-height column.
+    series: Optional group column for side-by-side bars and colors.
+    title: Optional plot title.
+
+    Example
+    -------
+    >>> plot_bars(df, x="specification", y="rmse")
+    """
+    mapping = pn.aes(x=x, y=y, group=1)
+    if series is not None:
+        mapping.update(fill=series, group=series)
+    data = _group_data(data, series)
+    position = "identity" if series is None else pn.position_dodge2(preserve="single", padding=0)
+    p = pn.ggplot(data, mapping) + _Bar(
+        width=0.7 if series is not None else 0.55, position=position,
+        **({} if series is not None else {"fill": WFColors.TEAL}))
+    p = p + theme_workforce() + pn.labs(title=title)
+    if series is not None:
+        p = (p + pn.scale_fill_manual(values=_group_colors(data, series))
+             + pn.guides(fill=pn.guide_legend(ncol=2, byrow=True))
+             + pn.theme(legend_position="top", legend_direction="horizontal"))
+    return _time_axis(p, data[x])
+
+
+def plot_scatter(data, *, x, y, series=None, fitted=None, lower=None, upper=None,
+                 point_size=3.75, ci_width=0.54, cap_width=None, title=None):
+    """Draw unconnected points with optional intervals and a supplied curve.
+
+    data: Pandas or Polars dataframe with one row per point.
+    x, y: Column names for the two plotted variables.
+    series: Optional group column for separate colors.
+    fitted: Optional dataframe of fitted values using the same x, y,
+        and series column names. The supplied values are joined in x order.
+    lower, upper: Optional pair of y interval-bound columns.
+    point_size: Dot size in plotnine units (3.75).
+    ci_width: Interval stroke width in points (0.54).
+    cap_width: Cap width in plot-axis units. Defaults to short caps. Use 0 for none.
+    title: Optional plot title.
+
+    Example
+    -------
+    >>> plot_scatter(df, x="year", y="effect", fitted=curve_df)
+    """
+    _interval(lower, upper)
+    mapping = pn.aes(x=x, y=y, group=1)
+    if series is not None:
+        mapping.update(color=series, group=series)
+    data = _group_data(data, series)
+    fitted = None if fitted is None else _group_data(fitted, series)
+    p = pn.ggplot(data, mapping)
+    point_color = "#808080" if fitted is not None else WFColors.TEAL
+    if lower is not None:
+        p += _ErrorBar(pn.aes(ymin=lower, ymax=upper), width=cap_width,
+                       categorical=_categorical(data[x]), na_rm=True,
+                       size=ci_width / sqrt(pi), show_legend=False,
+                       **({} if series is not None else {"color": point_color}))
+    if fitted is not None:
+        p += pn.geom_line(data=fitted, size=0.914, show_legend=False,
+                          **({} if series is not None else {"color": WFColors.TEAL}))
+    p += pn.geom_point(size=point_size, stroke=0, na_rm=True,
+                       **({} if series is not None else {"color": point_color}))
+    if series is not None:
+        p += pn.scale_color_manual(values=_group_colors(data, series, fitted))
+        p += pn.guides(color=pn.guide_legend(override_aes={"size": point_size * 1.25}))
+    return _time_axis(p + theme_workforce() + pn.labs(title=title), data[x])
+
+
+def plot_intervals(data, *, x, y, lower, upper, series=None, fitted=None,
+                   point_size=3.75, ci_width=0.54, cap_width=None, title=None):
+    """Draw estimates and their supplied intervals across categories.
+
+    data: Pandas or Polars dataframe with one row per estimate.
+    x, y: Category and estimate column names.
+    lower, upper: Required columns containing the interval endpoints.
+    series: Optional group column for side-by-side estimates and colors.
+    fitted: Optional dataframe of fitted values with the same x, y, and series columns.
+    point_size: Dot size in plotnine units (3.75).
+    ci_width: Interval stroke width in points (0.54).
+    cap_width: Cap width in plot-axis units. Defaults to short caps. Use 0 for none.
+    title: Optional plot title.
+
+    Example
+    -------
+    >>> plot_intervals(df, x="program", y="effect", lower="lo", upper="hi")
+    """
+    mapping = pn.aes(x=x, y=y, group=1)
+    if series is not None:
+        mapping.update(color=series, group=series)
+    data = _group_data(data, series)
+    fitted = None if fitted is None else _group_data(fitted, series)
+    point_color = "#808080" if fitted is not None else WFColors.TEAL
+    colors = {} if series is not None else {"color": point_color}
+    categorical = _categorical(data[x])
+    p = pn.ggplot(data, mapping)
+    if fitted is not None:
+        p += pn.geom_line(data=fitted, size=0.914, show_legend=False,
+                          **({} if series is not None else {"color": WFColors.TEAL}))
+    position = "identity" if series is None else _IntervalDodge(width=0.5)
+    p = (p + _ErrorBar(pn.aes(ymin=lower, ymax=upper), width=cap_width,
+                             categorical=categorical, na_rm=True,
+                             position=position, size=ci_width / sqrt(pi),
+                             show_legend=False, **colors)
+         + pn.geom_point(position=position, size=point_size, stroke=0,
+                         **colors))
+    if series is not None:
+        p += pn.scale_color_manual(values=_group_colors(data, series, fitted))
+        p += pn.guides(color=pn.guide_legend(ncol=2 if categorical else None,
+                                             byrow=categorical,
+                                             override_aes={"size": point_size * 1.25}))
+    p = p + theme_workforce() + pn.labs(title=title)
+    if series is not None and categorical:
+        p += pn.theme(legend_position="top", legend_direction="horizontal")
+    return _time_axis(p, data[x])