workforce-plotting 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

workforce_plotting/__init__.py

@@ -1,9 +1,9 @@
 """Plotnine figures and styling for workforce research."""
 
 from .figures import (
-    WFColors, plot_bars, plot_intervals, plot_lines, plot_scatter,
+    WFColors, dollars, plot_bars, plot_intervals, plot_lines, plot_scatter,
     plot_validation, theme_workforce,
 )
 
 __all__ = ["plot_lines", "plot_validation", "plot_bars", "plot_scatter",
-           "plot_intervals", "theme_workforce", "WFColors"]
+           "plot_intervals", "theme_workforce", "WFColors", "dollars"]

workforce_plotting/figures.py

@@ -1,41 +1,92 @@
-"""Workforce plots, shared styling, and the Opportunity Insights color palette."""
+"""Workforce plots, shared paper styling, and the Opportunity Insights palette."""
+
+from math import pi, sqrt
 
 import pandas as pd
 import plotnine as pn
-from matplotlib import font_manager
 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=None, width=8, height=5):
-    """White background, gray axes, no grid, and a bottom legend.
+def theme_workforce(base_size=12, base_family="Times New Roman", width=8, height=5):
+    """Create the shared paper theme for a new or existing plot.
+
+    Parameters
+    ----------
+    base_size : float, default 12
+        Size of axis text, axis titles, and legend text, in points.
+    base_family : str, default "Times New Roman"
+        Font family. Install this font locally, or choose another installed font,
+        such as "DejaVu Sans".
+    width, height : float, default 8, 5
+        Exported figure dimensions in inches.
+
+    Returns
+    -------
+    plotnine.theme
+        Add to a plot with ``p + theme_workforce(...)``. The plot constructors
+        already apply this theme; call it again only to override their defaults.
 
-    Dimensions are in inches. Install Lucida Sans to match the reference deck.
-    If unavailable, Matplotlib falls back to its default sans-serif font.
+    Notes
+    -----
+    Defaults include gray 0.54-point axes, five-point ticks, 10-point axis-title
+    padding, 2% outer margins, no grid, and a transparent vertical legend inside
+    the upper-left corner. Titles can be added with ``pn.labs(title=...)``.
+
+    Examples
+    --------
+    >>> p = plot_lines(df, x="year", y="earnings")
+    >>> p = p + theme_workforce(width=10, height=6)
     """
-    if base_family is None:
-        base_family = ("Lucida Sans" if "Lucida Sans" in font_manager.get_font_names()
-                       else "DejaVu Sans")
     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=5,
         axis_text=pn.element_text(color="black", size=base_size),
-        axis_title=pn.element_text(size=base_size, lineheight=1.8),
-        axis_title_y=pn.element_text(margin={"r": 16}),
-        axis_title_x=pn.element_text(margin={"t": 14}),
+        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}),
+        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_top=0.044,
-        plot_margin_right=0.015,
-        plot_margin_bottom=0.025,
+        plot_margin=0.02,
         panel_grid=pn.element_blank(),
         axis_ticks_minor=pn.element_blank(),
         legend_key=pn.element_blank(),
     )
 
 
+def dollars(values):
+    """Format axis tick values supplied in dollars as $1K, $2.5K, and $0.
+
+    Parameters
+    ----------
+    values : iterable of numbers
+        Values in dollars, not values already divided by 1,000. Plotnine supplies
+        these values automatically when this function is used as a scale labeler.
+
+    Returns
+    -------
+    list of str
+        Labels in thousands of dollars, with negative values written as -$1K.
+        This changes labels only; it does not change the plotted data.
+
+    Examples
+    --------
+    >>> dollars([-1000, 0, 2500])
+    ['-$1K', '$0', '$2.5K']
+    >>> 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):
@@ -48,11 +99,63 @@ def _interval(lower, upper):
         raise ValueError("Supply both lower and upper interval columns, or neither.")
 
 
-def plot_lines(data, *, x, y, series=None, lower=None, upper=None, points=True):
-    """Lines with optional points and supplied confidence intervals.
+def plot_lines(data, *, x, y, series=None, lower=None, upper=None, points=True,
+               point_size=3.75, ci_width=0.54, cap_width=0.08):
+    """Connect values in x order, optionally adding dots and confidence intervals.
+
+    Use for event studies, earnings trajectories, or model-complexity comparisons.
+    For unconnected estimates, use ``plot_scatter`` or ``plot_intervals`` instead.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame or polars.DataFrame
+        Prepared values, with one row per point. Column names are passed as
+        strings below; do not pass Series objects or arrays in their place.
+    x : str
+        Column for horizontal positions, such as "year" or "event_year".
+    y : str
+        Column containing the values to plot, such as "earnings" or "effect".
+    series : str or None, default None
+        Discrete group column, such as "estimator". Each group gets its own
+        connected line, color, and legend entry. None draws a single teal line.
+        Use ordered categories to control group order in the legend.
+    lower, upper : str or None, default None
+        Columns containing the lower and upper confidence bounds for y. Supply
+        both names together, or omit both. Bounds are drawn as supplied: this
+        function does not calculate standard errors or confidence intervals.
+    points : bool, default True
+        Draw dots on the line. False draws lines without dots.
+    point_size : float, default 3.75
+        Dot size in plotnine marker-size units, not a literal diameter in points.
+        Has no effect when points=False. Legend dots are 25% larger.
+    ci_width : float, default 0.54
+        Confidence-interval stroke width in points in the exported figure.
+        Changing this does not change dot size. Ignored without bounds.
+    cap_width : float, default 0.08
+        Total cap width in x-axis units, not points; zero removes caps. On a
+        discrete x-axis, one unit is the spacing between categories. The visible
+        cap length depends on the axis scale and figure dimensions.
+
+    Returns
+    -------
+    plotnine.ggplot
+        Editable plot. Add titles with ``+ pn.labs(title=..., x=..., y=...)``
+        and save with ``p.save("figure.png", dpi=180)``.
 
-    Use an ordered categorical series to control legend/color order. Add scales,
-    reference lines, facets, and labels using ordinary plotnine layers.
+    Notes
+    -----
+    Lines connect points in ascending x order within each group. Include a row
+    with a missing y value to break a line; omitting a row connects the remaining
+    points. No treatment-timing line or zero-effect line is added automatically.
+    The function does not fit a model or otherwise estimate the supplied values.
+
+    Examples
+    --------
+    For df with columns event_year, effect, lower, upper, and estimator:
+
+    >>> p = plot_lines(df, x="event_year", y="effect", series="estimator",
+    ...                lower="lower", upper="upper")
+    >>> p = p + pn.labs(title="Earnings Effects", x="Event Year", y="Effect")
     """
     _interval(lower, upper)
     mapping = pn.aes(x=x, y=y, group=1)
@@ -60,23 +163,76 @@ def plot_lines(data, *, x, y, series=None, lower=None, upper=None, points=True):
         mapping.update(color=series, group=series)
     p = pn.ggplot(_data(data), mapping)
     if lower is not None:
-        p += pn.geom_errorbar(pn.aes(ymin=lower, ymax=upper), width=0.08,
-                              size=0.4, **({} if series else {"color": WFColors.TEAL}))
-    p += pn.geom_line(size=0.914, **({} if series else {"color": WFColors.TEAL}))
+        p += pn.geom_errorbar(pn.aes(ymin=lower, ymax=upper, width=cap_width),
+                              size=ci_width / sqrt(pi), show_legend=False,
+                              **({} if series else {"color": WFColors.TEAL}))
+    p += pn.geom_line(size=0.914, show_legend=not points,
+                      **({} if series else {"color": WFColors.TEAL}))
     if points:
-        p += pn.geom_point(size=3.45, stroke=0, **({} if series else {"color": WFColors.TEAL}))
+        p += pn.geom_point(size=point_size, stroke=0,
+                           **({} if series else {"color": WFColors.TEAL}))
     if series is not None:
         p += pn.scale_color_manual(values=PALETTE)
+        if points:
+            p += pn.guides(color=pn.guide_legend(override_aes={"size": point_size * 1.25}))
     return p + theme_workforce()
 
 
 def plot_validation(data, *, x, y, x_lower=None, x_upper=None,
-                    y_lower=None, y_upper=None, gaps=None, limits=None):
-    """Compare estimates against a 45-degree identity line.
+                    y_lower=None, y_upper=None, gaps=None, limits=None,
+                    point_size=3.75, ci_width=0.54, cap_width=0):
+    """Compare paired estimates using an identity line and common axis limits.
+
+    Each row is one comparison, for example a site's DML and RCT estimates.
+    The identity line is y=x: points on it represent exact agreement. Unlike
+    ``plot_scatter``, both axes share numeric limits. The panel remains rectangular;
+    equal physical scaling on the two axes is not imposed.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame or polars.DataFrame
+        Prepared paired estimates, with one row per point.
+    x : str
+        Horizontal estimate column, for example "dml_effect".
+    y : str
+        Vertical estimate column, for example "rct_effect".
+    x_lower, x_upper : str or None, default None
+        Columns containing lower and upper bounds for x (horizontal intervals).
+        Supply both names together, or omit both.
+    y_lower, y_upper : str or None, default None
+        Columns containing lower and upper bounds for y (vertical intervals).
+        Supply both names together, or omit both. All bounds are drawn as
+        supplied; the function does not calculate uncertainty.
+    gaps : {None, "horizontal", "vertical"}, default None
+        Optional orange segments from each point to the identity line.
+        "horizontal" connects (x, y) to (y, y), holding y fixed.
+        "vertical" connects (x, y) to (x, x), holding x fixed.
+        None draws no gap segments.
+    limits : tuple of two numbers or None, default None
+        Shared (minimum, maximum) view limits for both axes. None uses the
+        smallest and largest supplied estimates and interval endpoints.
+        Explicit view limits clip the display without dropping input rows.
+    point_size : float, default 3.75
+        Dot size in plotnine marker-size units, not a literal diameter in points.
+    ci_width : float, default 0.54
+        Interval stroke width in points in the exported figure, independent
+        of dot size. Ignored when no interval bounds are supplied.
+    cap_width : float, default 0
+        Cap length in axis units, not points; zero removes caps. It is measured
+        in y units for horizontal intervals and x units for vertical intervals.
 
-    x/y confidence bounds are optional. ``gaps`` may be 'vertical' (from y to x)
-    or 'horizontal' (from x to y). Both axes use the same numeric limits.
-    Default limits include all supplied estimates and interval endpoints.
+    Returns
+    -------
+    plotnine.ggplot
+        Editable plot; add labels with ``+ pn.labs(...)`` or save with ``p.save``.
+        The function does not fit a regression or estimate effects.
+
+    Examples
+    --------
+    For df with dml_effect, rct_effect, rct_lower, and rct_upper columns:
+
+    >>> p = plot_validation(df, x="dml_effect", y="rct_effect",
+    ...                     y_lower="rct_lower", y_upper="rct_upper")
     """
     _interval(x_lower, x_upper)
     _interval(y_lower, y_upper)
@@ -97,20 +253,49 @@ def plot_validation(data, *, x, y, x_lower=None, x_upper=None,
     elif gaps == "horizontal":
         p += pn.geom_segment(pn.aes(xend=y, yend=y), color=WFColors.ORANGE, size=0.5, alpha=0.8)
     if x_lower is not None:
-        p += pn.geom_errorbarh(pn.aes(xmin=x_lower, xmax=x_upper), height=0,
-                              color=WFColors.TEAL, size=0.5, alpha=0.5)
+        p += pn.geom_errorbarh(pn.aes(xmin=x_lower, xmax=x_upper, height=cap_width),
+                              color=WFColors.TEAL, size=ci_width / sqrt(pi), alpha=0.5)
     if y_lower is not None:
-        p += pn.geom_errorbar(pn.aes(ymin=y_lower, ymax=y_upper), width=0,
-                             color=WFColors.TEAL, size=0.5, alpha=0.5)
-    return (p + pn.geom_point(color=WFColors.TEAL, size=3.45, stroke=0)
+        p += pn.geom_errorbar(pn.aes(ymin=y_lower, ymax=y_upper, width=cap_width),
+                             color=WFColors.TEAL, size=ci_width / sqrt(pi), alpha=0.5)
+    return (p + pn.geom_point(color=WFColors.TEAL, size=point_size, stroke=0)
             + pn.coord_cartesian(xlim=limits, ylim=limits) + theme_workforce())
 
 
 def plot_bars(data, *, x, y, series=None):
-    """Bars for already-calculated values; optional series are side by side.
+    """Draw supplied values as bars, optionally grouped side by side.
+
+    Use for RMSE by specification or other already-calculated category summaries.
+    This function draws values directly: it does not count rows, average values,
+    or calculate confidence intervals.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame or polars.DataFrame
+        One row per bar, containing the category and its already-calculated value.
+    x : str
+        Category column, for example "specification". Use an ordered categorical
+        column or ``+ pn.scale_x_discrete(limits=[...])`` to control its order.
+    y : str
+        Numeric bar-height column, for example "rmse".
+    series : str or None, default None
+        Discrete group column. Groups receive different colors and appear side
+        by side within each x category, with a legend identifying them.
+        None draws a single teal series.
 
-    Set x to an ordered categorical column, or add scale_x_discrete(limits=...),
-    to choose the category order. Add coord_flip() for horizontal bars.
+    Returns
+    -------
+    plotnine.ggplot
+        Editable plot. Add ``+ pn.coord_flip()`` for horizontal bars, labels with
+        ``+ pn.labs(...)``, or optional dollar labels with
+        ``+ pn.scale_y_continuous(labels=dollars)``. Save with ``p.save``.
+
+    Examples
+    --------
+    For df with specification and rmse columns:
+
+    >>> p = plot_bars(df, x="specification", y="rmse")
+    >>> p = p + pn.labs(title="RMSE by Specification", x="", y="RMSE")
     """
     mapping = pn.aes(x=x, y=y, group=1)
     if series is not None:
@@ -122,37 +307,137 @@ def plot_bars(data, *, x, y, series=None):
     return p + theme_workforce()
 
 
-def plot_scatter(data, *, x, y, series=None, fitted=None):
-    """Points, optionally with a separate dataframe of precomputed fitted values.
+def plot_scatter(data, *, x, y, series=None, fitted=None, lower=None, upper=None,
+                 point_size=3.75, ci_width=0.54, cap_width=0):
+    """Draw unconnected points, optionally with intervals and a supplied curve.
+
+    Use to show a relationship between two variables or cohort estimates with a
+    separate fitted curve. Unlike ``plot_validation``, no identity line is added
+    and the x and y axes choose their ranges independently.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame or polars.DataFrame
+        Prepared observations or estimates, with one row per point.
+    x : str
+        Horizontal-position column, for example "placement_rate" or "year".
+    y : str
+        Vertical-value column, for example "effect".
+    series : str or None, default None
+        Discrete group column, such as "city". Groups get distinct colors and
+        legend entries. None draws teal dots with a navy fitted curve, if supplied.
+    fitted : pandas.DataFrame, polars.DataFrame, or None, default None
+        Separate table of already-calculated curve coordinates. It must use
+        the same x and y column names and, when series is supplied, the same
+        group column name. Its rows need not match the number of observations.
+        Points in this table are connected in x order within each group.
+        This function never fits, interpolates, or smooths a statistical model;
+        None draws no curve. The observed dots themselves are not connected.
+    lower, upper : str or None, default None
+        Columns in data containing lower and upper confidence bounds for y.
+        Supply both names together, or omit both. These intervals describe the
+        supplied point estimates; they are not a confidence band for the curve.
+    point_size : float, default 3.75
+        Dot size in plotnine marker-size units, not a literal diameter in points.
+        Legend dots are 25% larger.
+    ci_width : float, default 0.54
+        Interval stroke width in points in the exported figure, independent
+        of dot size. Ignored without bounds.
+    cap_width : float, default 0
+        Total interval-cap width in x-axis units, not points; zero removes caps.
+        The visible length depends on the axis scale and figure dimensions.
 
-    ``fitted`` uses the same x, y, and (when specified) series column names.
-    The function never fits or smooths a curve.
+    Returns
+    -------
+    plotnine.ggplot
+        Editable plot; add labels with ``+ pn.labs(...)`` or save with ``p.save``.
+        All estimates, fitted values, and bounds must be calculated beforehand.
+
+    Examples
+    --------
+    For df with year, effect, lower, and upper columns, and curve_df with year
+    and effect columns containing previously calculated fitted values:
+
+    >>> p = plot_scatter(df, x="year", y="effect", lower="lower", upper="upper",
+    ...                  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)
     p = pn.ggplot(_data(data), mapping)
+    if lower is not None:
+        p += pn.geom_errorbar(pn.aes(ymin=lower, ymax=upper, width=cap_width),
+                              size=ci_width / sqrt(pi), show_legend=False,
+                              **({} if series else {"color": WFColors.TEAL}))
     if fitted is not None:
-        p += pn.geom_line(data=_data(fitted), size=0.914,
+        p += pn.geom_line(data=_data(fitted), size=0.914, show_legend=False,
                           **({} if series else {"color": WFColors.NAVY}))
-    p += pn.geom_point(size=3.45, stroke=0, **({} if series else {"color": WFColors.TEAL}))
+    p += pn.geom_point(size=point_size, stroke=0, **({} if series else {"color": WFColors.TEAL}))
     if series is not None:
         p += pn.scale_color_manual(values=PALETTE)
+        p += pn.guides(color=pn.guide_legend(override_aes={"size": point_size * 1.25}))
     return p + theme_workforce()
 
 
-def plot_intervals(data, *, x, y, lower, upper, series=None):
-    """Points with supplied interval bounds, dodged when series are supplied.
+def plot_intervals(data, *, x, y, lower, upper, series=None,
+                   point_size=3.75, ci_width=0.54, cap_width=0):
+    """Draw unconnected estimates and confidence intervals across categories.
+
+    Use for treatment effects by program/site or coefficient plots. Unlike
+    ``plot_lines``, estimates are not connected, and no fitted curve is added.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame or polars.DataFrame
+        Prepared estimates, with one row per category (or category/group pair).
+    x : str
+        Category column, such as "program" or "site". Ordered categories control
+        the display order; otherwise plotnine uses its normal category ordering.
+    y : str
+        Numeric estimate column, such as "effect".
+    lower, upper : str
+        Required column names for the lower and upper confidence bounds for y.
+        Supply the actual endpoints, not standard errors. The function does
+        not calculate bounds or choose a confidence level.
+    series : str or None, default None
+        Discrete group column, such as "estimator". Groups receive different
+        colors and are offset side by side within each category so dots and
+        intervals do not overlap exactly. None draws one teal series.
+    point_size : float, default 3.75
+        Dot size in plotnine marker-size units, not a literal diameter in points.
+        Legend dots are 25% larger.
+    ci_width : float, default 0.54
+        Interval stroke width in points in the exported figure, independent
+        of dot size.
+    cap_width : float, default 0
+        Cap width in category-axis units, not points; zero removes caps.
+        One unit is the spacing between categories on a discrete axis.
+        Caps are narrowed along with groups when series are offset side by side.
+
+    Returns
+    -------
+    plotnine.ggplot
+        Editable plot. Add ``+ pn.coord_flip()`` for a horizontal coefficient
+        plot, labels with ``+ pn.labs(...)``, or save with ``p.save``.
+
+    Examples
+    --------
+    For df with program, effect, lower, and upper columns:
 
-    x is the category and y the estimate. Add coord_flip() for a horizontal
-    coefficient plot. Interval bounds are used as supplied, without adjustment.
+    >>> p = plot_intervals(df, x="program", y="effect", lower="lower", upper="upper")
+    >>> p = p + pn.coord_flip()
     """
     mapping = pn.aes(x=x, y=y, ymin=lower, ymax=upper)
     if series is not None:
         mapping.update(color=series, group=series)
-    p = pn.ggplot(_data(data), mapping) + pn.geom_pointrange(
-        position=pn.position_dodge(width=0.5), size=0.5,
-        **({} if series else {"color": WFColors.TEAL}))
+    dodge = pn.position_dodge(width=0.5)
+    p = (pn.ggplot(_data(data), mapping)
+         + pn.geom_errorbar(pn.aes(width=cap_width), position=dodge, size=ci_width / sqrt(pi),
+                             show_legend=False, **({} if series else {"color": WFColors.TEAL}))
+         + pn.geom_point(position=dodge, size=point_size, stroke=0,
+                         **({} if series else {"color": WFColors.TEAL})))
     if series is not None:
         p += pn.scale_color_manual(values=PALETTE)
+        p += pn.guides(color=pn.guide_legend(override_aes={"size": point_size * 1.25}))
     return p + theme_workforce()

workforce_plotting-0.3.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: workforce-plotting
+Version: 0.3.0
+Summary: Simple plotnine figures with Opportunity Insights styling.
+Author: Corey Gelb-Bicknell
+License-Expression: MIT
+Project-URL: Repository, https://github.com/coreygb1/workforce-plotting
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: plotnine<0.16,>=0.15
+Requires-Dist: pandas>=2.2
+Requires-Dist: oi-tools>=0.11.7
+Provides-Extra: polars
+Requires-Dist: polars>=1; extra == "polars"
+Requires-Dist: pyarrow>=14; extra == "polars"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: polars>=1; extra == "dev"
+Requires-Dist: pyarrow>=14; extra == "dev"
+Dynamic: license-file
+
+# workforce-plotting
+
+Five small plotnine functions with a shared paper style based on Opportunity Insights. Supply
+prepared estimates and confidence bounds; the functions only draw them. Every
+function returns a `plotnine.ggplot` that you can edit with ordinary layers.
+
+## Install
+
+Python 3.12 or newer is required (matching `oi-tools`). For a Polars workflow:
+
+```bash
+uv add 'workforce-plotting[polars]'
+```
+
+Or use pip:
+
+```bash
+pip install 'workforce-plotting[polars]'
+```
+
+For local development from this checkout:
+
+```bash
+pip install -e '.[dev]'
+```
+
+For Polars input, install the `polars` extra, which also supplies the Arrow
+conversion dependency. Pandas input needs no extra.
+
+## Getting help
+
+Function help includes every argument, its default, the expected column names,
+and a short example:
+
+```python
+from workforce_plotting import plot_lines
+help(plot_lines)
+```
+
+In Jupyter, use `plot_lines?` or press Shift+Tab inside the parentheses. Column
+arguments such as `x`, `y`, and `series` are names in your dataframe, not arrays.
+`series="city"` means one color and legend entry per city; `plot_lines` also
+connects observations separately within each city. Estimates and confidence
+bounds must already be calculated. Every plot function returns an editable
+plotnine plot, with no automatic saving.
+
+## Functions
+
+| Function | Use |
+|---|---|
+| `plot_lines(data, x=..., y=..., series=...)` | Event studies, trajectories, model complexity |
+| `plot_validation(data, x=..., y=...)` | RCT versus digital-twin estimates with an identity line |
+| `plot_bars(data, x=..., y=..., series=...)` | Already-calculated values by category |
+| `plot_scatter(data, x=..., y=..., fitted=...)` | Unconnected points, optional CIs and a supplied fitted curve |
+| `plot_intervals(data, x=..., y=..., lower=..., upper=...)` | Estimates and supplied confidence intervals |
+| `theme_workforce()` | Times New Roman, gray axes, white background, no grid |
+
+`plot_lines` accepts `lower` and `upper` columns and `points=False`.
+`plot_scatter` also accepts `lower` and `upper` for supplied confidence bounds.
+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`.
+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
+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.
+
+```python
+import plotnine as pn
+from workforce_plotting import plot_lines
+
+p = plot_lines(df, x="year", y="earnings", series="group")
+p += pn.labs(x="Years since enrollment", y="Mean annual earnings")
+p.save("earnings.svg")
+```
+
+Dataframes should be tidy: one row per plotted point, with separate columns for
+x, y, and an optional series. Lines connect points in x order within each series.
+Include a row with a missing y where a line should break; simply omitting a row
+connects the remaining observations. Fitted lines use the same column names as
+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.
+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.
+
+## Paper defaults
+
+- Times New Roman, 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
+  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.
+
+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.
+
+Dollar formatting is optional, rather than imposed on every outcome:
+
+```python
+from workforce_plotting import dollars
+
+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.
+
+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),
+              legend_justification_inside=(1, 1))  # upper-right
+```
+
+To put it below the figure, use
+`pn.theme(legend_position="bottom", legend_direction="horizontal")`.
+
+## Event-study recipe
+
+Use `plot_lines` with supplied estimates and confidence bounds, then add the
+reference lines explicitly. Here treatment begins at event year zero; a zero-effect
+line is added, but no treatment-timing line is imposed:
+
+```python
+p = (
+    plot_lines(df, x="event_year", y="effect", lower="lower", upper="upper")
+    + pn.geom_hline(yintercept=0, color="#A0A0A0", size=0.54)
+    + pn.scale_y_continuous(labels=dollars)
+    + pn.labs(x="Years Relative to Treatment", y="Earnings Effect")
+)
+```
+
+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`.
+
+## Styling your own plots
+
+Use the theme and colors without using the plot constructors. `WFColors` is an
+alias of `oi_tools.figures.OIColors`, and `theme_workforce` builds on `theme_oi`.
+The `oi-tools` dependency remains; you only need workforce imports in your code.
+All plotting functions and styling live together in `workforce_plotting/figures.py`.
+
+```python
+import polars as pl
+import plotnine as pn
+from workforce_plotting import theme_workforce, WFColors
+
+df = pl.DataFrame({"year": [2020, 2021, 2022], "earnings": [20000, 23000, 25000]})
+p = (
+    pn.ggplot(df.to_pandas(), pn.aes(x="year", y="earnings"))
+    + pn.geom_line(color=WFColors.TEAL)
+    + pn.geom_point(color=WFColors.TEAL)
+    + theme_workforce()
+    + pn.labs(x="Year", y="Annual earnings")
+)
+p.save("earnings.svg")
+```
+
+Plot constructors accept Polars directly. When building a plotnine plot yourself,
+the explicit conversion above works with the supported plotnine version.
+
+## Default outputs
+
+`examples/default_examples.py` draws all five functions with their basic calls:
+no added reference lines, titles, labels, scales, coordinates, or theme overrides.
+It uses the same data for scatter and validation so their default behavior can
+be compared directly. All values are invented.
+
+```bash
+python examples/default_examples.py outputs/defaults
+```
+
+Titles remain available through `pn.labs(title=...)`; the plain default examples
+deliberately do not add them.
+
+## Editable examples
+
+`examples/paper_examples.py` contains synthetic recipes for the paper/deck plot
+families. These are invented values, not research results.
+
+```bash
+python examples/paper_examples.py outputs/examples
+pytest
+```
+
+## Changes in 0.3
+
+- Paper defaults: Times New Roman, inside vertical legends, five-point ticks,
+  shared margins, and consistent axis-title spacing. Choose a different font
+  explicitly with `theme_workforce(base_family=...)` for deck-style figures.
+- Consistent dots, larger legend dots, and independently sized intervals.
+- Optional scatter confidence intervals and an optional `dollars` labeler.
+- Complete function help plus plain-default and customized example scripts.
+
+The five plot names and the rectangular validation layout are unchanged.
+
+## Changes from 0.1
+
+This is a fresh API. The old Matplotlib functions, plotting dataclasses, curve
+fitting machinery, and `aipw_analysis` compatibility package have been removed.
+Plot creation and saving are now separate. The public API consists of the five plot functions, `theme_workforce`, `WFColors`, and the optional `dollars` formatter.

workforce_plotting-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+workforce_plotting/__init__.py,sha256=WMPL6dhkaVLCxJPSb516VWcVSjsI2R_UMYIjwfOe4R4,344
+workforce_plotting/figures.py,sha256=Dp9NrPWg5X0SxGmJV5k_1wEcqaKbbxj5sciUX4-NFIQ,20145
+workforce_plotting-0.3.0.dist-info/licenses/LICENSE,sha256=vIUOXKFifh8J0Pb7KgpB0HKgiKPfoMcz9zAqUHKl8mo,1076
+workforce_plotting-0.3.0.dist-info/METADATA,sha256=z0AqJOr6HBGGss21eIkXQNQa3LxsLWS6RkFZnczsHEM,9803
+workforce_plotting-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+workforce_plotting-0.3.0.dist-info/top_level.txt,sha256=VBDPtAcqz3Z46cgEzdq8GGm8YIFQtkNcI1Zv8pqqcu4,19
+workforce_plotting-0.3.0.dist-info/RECORD,,

workforce_plotting-0.2.0.dist-info/METADATA

@@ -1,135 +0,0 @@
-Metadata-Version: 2.4
-Name: workforce-plotting
-Version: 0.2.0
-Summary: Simple plotnine figures with Opportunity Insights styling.
-Author: Corey Gelb-Bicknell
-License-Expression: MIT
-Project-URL: Repository, https://github.com/coreygb1/workforce-plotting
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: plotnine<0.16,>=0.15
-Requires-Dist: pandas>=2.2
-Requires-Dist: oi-tools>=0.11.7
-Provides-Extra: polars
-Requires-Dist: polars>=1; extra == "polars"
-Requires-Dist: pyarrow>=14; extra == "polars"
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: polars>=1; extra == "dev"
-Requires-Dist: pyarrow>=14; extra == "dev"
-Dynamic: license-file
-
-# workforce-plotting
-
-Five small plotnine functions with a shared Opportunity Insights style. Supply
-prepared estimates and confidence bounds; the functions only draw them. Every
-function returns a `plotnine.ggplot` that you can edit with ordinary layers.
-
-## Install
-
-Python 3.12 or newer is required (matching `oi-tools`). For a Polars workflow:
-
-```bash
-uv add 'workforce-plotting[polars]'
-```
-
-Or use pip:
-
-```bash
-pip install 'workforce-plotting[polars]'
-```
-
-For local development from this checkout:
-
-```bash
-pip install -e '.[dev]'
-```
-
-For Polars input, install the `polars` extra, which also supplies the Arrow
-conversion dependency. Pandas input needs no extra.
-
-## Functions
-
-| Function | Use |
-|---|---|
-| `plot_lines(data, x=..., y=..., series=...)` | Event studies, trajectories, cohort trends, model complexity |
-| `plot_validation(data, x=..., y=...)` | RCT versus digital-twin estimates with an identity line |
-| `plot_bars(data, x=..., y=..., series=...)` | Already-calculated values by category |
-| `plot_scatter(data, x=..., y=..., fitted=...)` | Points with an optional precomputed fitted line |
-| `plot_intervals(data, x=..., y=..., lower=..., upper=...)` | Estimates and supplied confidence intervals |
-| `theme_workforce()` | Shared white background, gray axes, sans-serif type, no grid |
-
-`plot_lines` accepts `lower` and `upper` columns and `points=False`.
-`plot_validation` accepts `x_lower`, `x_upper`, `y_lower`, `y_upper`,
-`gaps="horizontal"` or `"vertical"`, and a common `(min, max)` pair of `limits`.
-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
-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.
-
-```python
-import plotnine as pn
-from workforce_plotting import plot_lines
-
-p = plot_lines(df, x="year", y="earnings", series="group")
-p += pn.labs(x="Years since enrollment", y="Mean annual earnings")
-p.save("earnings.svg")
-```
-
-Dataframes should be tidy: one row per plotted point, with separate columns for
-x, y, and an optional series. Lines connect points in x order within each series.
-Include a row with a missing y where a line should break; simply omitting a row
-connects the remaining observations. Fitted lines use the same column names as
-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. Fonts, dimensions, and text size
-use Lucida Sans when installed and DejaVu Sans otherwise. They can be overridden with `theme_workforce(base_family=..., base_size=..., width=..., height=...)`.
-Titles, logos, notes, and paper-specific annotations belong in the example/caller.
-
-## Styling your own plots
-
-Use the theme and colors without using the plot constructors. `WFColors` is an
-alias of `oi_tools.figures.OIColors`, and `theme_workforce` builds on `theme_oi`.
-The `oi-tools` dependency remains; you only need workforce imports in your code.
-All plotting functions and styling live together in `workforce_plotting/figures.py`.
-
-```python
-import polars as pl
-import plotnine as pn
-from workforce_plotting import theme_workforce, WFColors
-
-df = pl.DataFrame({"year": [2020, 2021, 2022], "earnings": [20000, 23000, 25000]})
-p = (
-    pn.ggplot(df.to_pandas(), pn.aes(x="year", y="earnings"))
-    + pn.geom_line(color=WFColors.TEAL)
-    + pn.geom_point(color=WFColors.TEAL)
-    + theme_workforce()
-    + pn.labs(x="Year", y="Annual earnings")
-)
-p.save("earnings.svg")
-```
-
-Plot constructors accept Polars directly. When building a plotnine plot yourself,
-the explicit conversion above works with the supported plotnine version.
-
-## Editable examples
-
-`examples/paper_examples.py` contains synthetic recipes for the paper/deck plot
-families. These are invented values, not research results.
-
-```bash
-python examples/paper_examples.py outputs/examples
-pytest
-```
-
-## Changes from 0.1
-
-This is a fresh API. The old Matplotlib functions, plotting dataclasses, curve
-fitting machinery, and `aipw_analysis` compatibility package have been removed.
-Plot creation and saving are now separate. The public API consists of the five plot functions, `theme_workforce`, and `WFColors`.

workforce_plotting-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-workforce_plotting/__init__.py,sha256=Hu7rBJz6wdcIAn84s62-xTZFlz_bTee-3xIDd8u87s8,324
-workforce_plotting/figures.py,sha256=YHXf-PC349SgBXOTJhI4GZZcvPjJmZvP2xEC0eMWMiQ,6978
-workforce_plotting-0.2.0.dist-info/licenses/LICENSE,sha256=vIUOXKFifh8J0Pb7KgpB0HKgiKPfoMcz9zAqUHKl8mo,1076
-workforce_plotting-0.2.0.dist-info/METADATA,sha256=llHdwfUYE9Osn3Mp6uAQvfzOCxxOP-rnyKyep6TsJK4,5309
-workforce_plotting-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-workforce_plotting-0.2.0.dist-info/top_level.txt,sha256=VBDPtAcqz3Z46cgEzdq8GGm8YIFQtkNcI1Zv8pqqcu4,19
-workforce_plotting-0.2.0.dist-info/RECORD,,