workforce-plotting 0.2.0__tar.gz

workforce_plotting-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Gelb-Bicknell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workforce_plotting-0.2.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include examples *.py

workforce_plotting-0.2.0/PKG-INFO

@@ -0,0 +1,135 @@
+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/README.md

@@ -0,0 +1,111 @@
+# 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/examples/paper_examples.py

@@ -0,0 +1,107 @@
+"""Editable paper/deck recipes using invented values, not research results.
+
+Run: python examples/paper_examples.py /tmp/workforce-plotting-examples
+"""
+
+import sys
+from pathlib import Path
+
+import pandas as pd
+import plotnine as pn
+from mizani.labels import label_dollar
+
+from workforce_plotting import (
+    plot_bars, plot_intervals, plot_lines, plot_scatter, plot_validation,
+)
+
+
+def examples():
+    # Event study: prepared means and bounds, connected separately by group.
+    event = pd.DataFrame({
+        "year": [-2, -1, 0, 1, 2, 3] * 3,
+        "group": ["Treated"] * 6 + ["RCT control"] * 6 + ["Digital twin"] * 6,
+        "earnings": [12, 14, 15, 22, 27, 30, 12, 14, 15, 18, 21, 23,
+                     12, 14, 15, 19, 21, 24],
+    })
+    event["group"] = pd.Categorical(event["group"],
+        categories=["Treated", "RCT control", "Digital twin"], ordered=True)
+    event["earnings"] *= 1000
+    event["lower"] = event["earnings"] - 1200
+    event["upper"] = event["earnings"] + 1200
+    earnings = (plot_lines(event, x="year", y="earnings", series="group",
+                           lower="lower", upper="upper")
+                + pn.scale_y_continuous(labels=label_dollar(scale=0.001, suffix="K", accuracy=1))
+                + pn.labs(x="Years since enrollment", y="Mean annual earnings")
+                + pn.theme(legend_position=(0.2, 0.82), legend_direction="vertical")
+                + pn.guides(color=pn.guide_legend(override_aes={"linetype": ""})))
+
+    # Complexity: supplied RMSE at each sample share, on a log x-axis.
+    complexity = pd.DataFrame({
+        "share": [1, 3.33, 10, 33.3, 100] * 4,
+        "model": ["Full population"] * 5 + ["1%"] * 5 + ["0.04% (CPS-sized)"] * 5 + ["0.02%"] * 5,
+        "rmse": [7400, 3900, 2200, 1900, 1600, 6200, 3900, 3600, 3300, 3000,
+                 6100, 3400, 2800, 2400, 2300, 6300, 4800, 4400, 4200, 4200],
+    })
+    complexity["model"] = pd.Categorical(complexity["model"],
+        categories=["Full population", "1%", "0.04% (CPS-sized)", "0.02%"], ordered=True)
+    complexity_plot = (plot_lines(complexity, x="share", y="rmse", series="model")
+        + pn.scale_x_log10(breaks=[1, 3.33, 10, 33.3, 100],
+                          labels=["1%", "3.33%", "10%", "33.3%", "100%"])
+        + pn.scale_y_continuous(breaks=[0, 2000, 4000, 6000, 8000],
+                               labels=["0", "$2K", "$4K", "$6K", "$8K"])
+        + pn.coord_cartesian(ylim=(0, 8000))
+        + pn.labs(x="Model complexity, share of tuned model", y="Noise-adjusted RMSE")
+        + pn.theme(legend_position=(0.80, 0.78), legend_direction="vertical")
+        + pn.guides(color=pn.guide_legend(override_aes={"linetype": ""})))
+
+    validation = pd.DataFrame({
+        "rct": [-2500, -1000, 200, 1500, 2500, 4000, 6000, 8000, 10000],
+        "twin": [-1500, -1800, 900, 2500, 1800, 5200, 6500, 7200, 11000],
+    })
+    validation["lower"] = validation["twin"] - 900
+    validation["upper"] = validation["twin"] + 900
+    validation_plot = (plot_validation(validation, x="twin", y="rct",
+        gaps="horizontal", limits=(-5000, 12000))
+        + pn.scale_x_continuous(labels=label_dollar(scale=0.001, suffix="K", accuracy=1))
+        + pn.scale_y_continuous(labels=label_dollar(scale=0.001, suffix="K", accuracy=1))
+        + pn.labs(x="Digital-twin estimate", y="RCT estimate"))
+
+    validation_ci = (plot_validation(validation, x="twin", y="rct",
+        x_lower="lower", x_upper="upper", limits=(-5000, 12000))
+        + pn.scale_x_continuous(labels=label_dollar(scale=0.001, suffix="K", accuracy=1))
+        + pn.scale_y_continuous(labels=label_dollar(scale=0.001, suffix="K", accuracy=1))
+        + pn.labs(x="Digital-twin estimate", y="RCT estimate"))
+
+    comparisons = pd.DataFrame({"specification": ["Demographics", "+ Earnings", "+ Parents"],
+                                "rmse": [3500, 2200, 1800]})
+    bars = (plot_bars(comparisons, x="specification", y="rmse")
+            + pn.scale_x_discrete(limits=comparisons["specification"].tolist())
+            + pn.scale_y_continuous(
+                labels=label_dollar(scale=0.001, suffix="K", accuracy=1),
+                expand=(0, 0, 0.05, 0))
+            + pn.labs(x="", y="Noise-adjusted RMSE"))
+
+    placement = pd.DataFrame({"placement": [20, 30, 40, 50, 60],
+                              "effect": [1500, 2600, 2100, 4200, 4800]})
+    # This line is supplied by the analysis; plotting does not fit it.
+    fitted = pd.DataFrame({"placement": [20, 60], "effect": [1300, 4700]})
+    scatter = (plot_scatter(placement, x="placement", y="effect", fitted=fitted)
+               + pn.labs(x="Placement rate (%)", y="Earnings effect"))
+
+    intervals = pd.DataFrame({"program": ["Program A", "Program B", "Program C"],
+                             "effect": [1200, 2500, -500], "lower": [200, 1400, -1500],
+                             "upper": [2200, 3600, 500]})
+    interval_plot = (plot_intervals(intervals, x="program", y="effect",
+        lower="lower", upper="upper") + pn.coord_flip()
+        + pn.labs(x="", y="Earnings effect"))
+    return {"event_study": earnings, "complexity": complexity_plot,
+            "validation": validation_plot, "validation_ci": validation_ci, "bars": bars,
+            "scatter": scatter, "intervals": interval_plot}
+
+
+if __name__ == "__main__":
+    output = Path(sys.argv[1] if len(sys.argv) > 1 else "outputs/examples")
+    output.mkdir(parents=True, exist_ok=True)
+    for name, plot in examples().items():
+        plot.save(output / f"{name}.png", dpi=150, verbose=False)
+        plot.save(output / f"{name}.svg", verbose=False)

workforce_plotting-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workforce-plotting"
+version = "0.2.0"
+description = "Simple plotnine figures with Opportunity Insights styling."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Corey Gelb-Bicknell" }]
+dependencies = ["plotnine>=0.15,<0.16", "pandas>=2.2", "oi-tools>=0.11.7"]
+
+[project.optional-dependencies]
+polars = ["polars>=1", "pyarrow>=14"]
+dev = ["pytest>=8", "build", "twine", "polars>=1", "pyarrow>=14"]
+
+[project.urls]
+Repository = "https://github.com/coreygb1/workforce-plotting"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["workforce_plotting*"]

workforce_plotting-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workforce_plotting-0.2.0/src/workforce_plotting/__init__.py

@@ -0,0 +1,9 @@
+"""Plotnine figures and styling for workforce research."""
+
+from .figures import (
+    WFColors, 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"]

workforce_plotting-0.2.0/src/workforce_plotting/figures.py

@@ -0,0 +1,158 @@
+"""Workforce plots, shared styling, and the Opportunity Insights color palette."""
+
+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.
+
+    Dimensions are in inches. Install Lucida Sans to match the reference deck.
+    If unavailable, Matplotlib falls back to its default sans-serif font.
+    """
+    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(
+        axis_line=pn.element_line(color="#A0A0A0", size=0.54),
+        axis_ticks=pn.element_line(color="#A0A0A0", size=0.54),
+        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}),
+        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,
+        panel_grid=pn.element_blank(),
+        axis_ticks_minor=pn.element_blank(),
+        legend_key=pn.element_blank(),
+    )
+
+
+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 plot_lines(data, *, x, y, series=None, lower=None, upper=None, points=True):
+    """Lines with optional points and supplied confidence intervals.
+
+    Use an ordered categorical series to control legend/color order. Add scales,
+    reference lines, facets, and labels using ordinary plotnine layers.
+    """
+    _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=0.08,
+                              size=0.4, **({} if series else {"color": WFColors.TEAL}))
+    p += pn.geom_line(size=0.914, **({} if series else {"color": WFColors.TEAL}))
+    if points:
+        p += pn.geom_point(size=3.45, stroke=0, **({} if series else {"color": WFColors.TEAL}))
+    if series is not None:
+        p += pn.scale_color_manual(values=PALETTE)
+    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.
+
+    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.
+    """
+    _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 = _data(data)
+    if limits is None:
+        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]).dropna()
+        if values.empty:
+            raise ValueError("Supply at least one nonmissing estimate or explicit limits.")
+        limits = (values.min(), values.max())
+    p = pn.ggplot(data, pn.aes(x=x, y=y)) + 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), color=WFColors.ORANGE, size=0.5, alpha=0.8)
+    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)
+    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)
+            + 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.
+
+    Set x to an ordered categorical column, or add scale_x_discrete(limits=...),
+    to choose the category order. Add coord_flip() for horizontal bars.
+    """
+    mapping = pn.aes(x=x, y=y, group=1)
+    if series is not None:
+        mapping.update(fill=series, group=series)
+    p = pn.ggplot(_data(data), mapping) + pn.geom_col(
+        width=0.7, position="dodge", **({} if series else {"fill": WFColors.TEAL}))
+    if series is not None:
+        p += pn.scale_fill_manual(values=PALETTE)
+    return p + theme_workforce()
+
+
+def plot_scatter(data, *, x, y, series=None, fitted=None):
+    """Points, optionally with a separate dataframe of precomputed fitted values.
+
+    ``fitted`` uses the same x, y, and (when specified) series column names.
+    The function never fits or smooths a curve.
+    """
+    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 fitted is not None:
+        p += pn.geom_line(data=_data(fitted), size=0.914,
+                          **({} if series else {"color": WFColors.NAVY}))
+    p += pn.geom_point(size=3.45, stroke=0, **({} if series else {"color": WFColors.TEAL}))
+    if series is not None:
+        p += pn.scale_color_manual(values=PALETTE)
+    return p + theme_workforce()
+
+
+def plot_intervals(data, *, x, y, lower, upper, series=None):
+    """Points with supplied interval bounds, dodged when series are supplied.
+
+    x is the category and y the estimate. Add coord_flip() for a horizontal
+    coefficient plot. Interval bounds are used as supplied, without adjustment.
+    """
+    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}))
+    if series is not None:
+        p += pn.scale_color_manual(values=PALETTE)
+    return p + theme_workforce()

workforce_plotting-0.2.0/src/workforce_plotting.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+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/src/workforce_plotting.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+examples/paper_examples.py
+src/workforce_plotting/__init__.py
+src/workforce_plotting/figures.py
+src/workforce_plotting.egg-info/PKG-INFO
+src/workforce_plotting.egg-info/SOURCES.txt
+src/workforce_plotting.egg-info/dependency_links.txt
+src/workforce_plotting.egg-info/requires.txt
+src/workforce_plotting.egg-info/top_level.txt
+tests/test_plots.py

workforce_plotting-0.2.0/src/workforce_plotting.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

workforce_plotting-0.2.0/src/workforce_plotting.egg-info/requires.txt

@@ -0,0 +1,14 @@
+plotnine<0.16,>=0.15
+pandas>=2.2
+oi-tools>=0.11.7
+
+[dev]
+pytest>=8
+build
+twine
+polars>=1
+pyarrow>=14
+
+[polars]
+polars>=1
+pyarrow>=14

workforce_plotting-0.2.0/src/workforce_plotting.egg-info/top_level.txt

@@ -0,0 +1 @@
+workforce_plotting

workforce_plotting-0.2.0/tests/test_plots.py

@@ -0,0 +1,101 @@
+import pandas as pd
+import plotnine as pn
+import pytest
+from oi_tools.figures import OIColors
+
+from workforce_plotting import plot_bars, plot_intervals, plot_lines, plot_scatter, plot_validation
+
+
+@pytest.fixture
+def data():
+    return pd.DataFrame({"x": [2, 0, 1, 2, 0, 1], "y": [4., 1, 2, 8, 3, 5],
+                         "group": ["A"] * 3 + ["B"] * 3,
+                         "lo": [3., 0, 1, 7, 2, 4], "hi": [5., 2, 3, 9, 4, 6]})
+
+
+def test_all_plots_render_without_changing_values(data):
+    before = data.copy(deep=True)
+    plots = [plot_lines(data, x="x", y="y", series="group", lower="lo", upper="hi"),
+             plot_bars(data, x="x", y="y", series="group"),
+             plot_scatter(data, x="x", y="y", series="group", fitted=data),
+             plot_intervals(data, x="x", y="y", lower="lo", upper="hi", series="group"),
+             plot_validation(data, x="x", y="y", y_lower="lo", y_upper="hi")]
+    import matplotlib.pyplot as plt
+    for p in plots:
+        assert isinstance(p, pn.ggplot)
+        fig = p.draw()
+        plt.close(fig)
+    pd.testing.assert_frame_equal(before, data)
+
+
+def test_lines_sort_and_group_and_keep_missing_gaps(data):
+    data.loc[2, "y"] = float("nan")
+    p = plot_lines(data, x="x", y="y", series="group")
+    p._build()
+    lines = p._build_objs.layers[0].data
+    assert lines.groupby("group")["x"].apply(list).tolist() == [[0, 1, 2], [0, 1, 2]]
+    assert lines["y"].isna().sum() == 1
+    assert lines.groupby("group")["color"].first().tolist() == [OIColors.TEAL, OIColors.ORANGE]
+
+
+def test_validation_gaps_and_bounds(data):
+    for direction in ["horizontal", "vertical"]:
+        p = plot_validation(data, x="x", y="y", gaps=direction,
+                            y_lower="lo", y_upper="hi")
+        p._build()
+        segments = p._build_objs.layers[1].data
+        if direction == "horizontal":
+            assert list(segments.xend) == list(data.y)
+            assert list(segments.yend) == list(data.y)
+        else:
+            assert list(segments.xend) == list(data.x)
+            assert list(segments.yend) == list(data.x)
+        intervals = p._build_objs.layers[2].data
+        assert list(intervals.ymin) == list(data.lo)
+        assert list(intervals.ymax) == list(data.hi)
+
+
+def test_polars_conversion(data):
+    pl = pytest.importorskip("polars")
+    p = plot_lines(pl.from_pandas(data), x="x", y="y")
+    pd.testing.assert_frame_equal(p.data, data)
+
+
+def test_invalid_partial_interval(data):
+    with pytest.raises(ValueError, match="both"):
+        plot_lines(data, x="x", y="y", lower="lo")
+    with pytest.raises(ValueError, match="gaps"):
+        plot_validation(data, x="x", y="y", gaps="unknown")
+
+
+def test_categorical_x_connects_single_series():
+    data = pd.DataFrame({"x": pd.Categorical(["late", "early", "middle"],
+        categories=["early", "middle", "late"], ordered=True), "y": [3, 1, 2]})
+    p = plot_lines(data, x="x", y="y")
+    p._build()
+    line = p._build_objs.layers[0].data
+    assert line.group.nunique() == 1
+    assert line.y.tolist() == [1, 2, 3]
+
+
+def test_validation_preserves_bounds_outside_view(data):
+    p = plot_validation(data, x="x", y="y", x_lower="lo", x_upper="hi",
+                        y_lower="lo", y_upper="hi", limits=(1, 3))
+    p._build()
+    horizontal, vertical = p._build_objs.layers[1:3]
+    assert horizontal.data.xmin.tolist() == data.lo.tolist()
+    assert horizontal.data.xmax.tolist() == data.hi.tolist()
+    assert vertical.data.ymin.tolist() == data.lo.tolist()
+    assert vertical.data.ymax.tolist() == data.hi.tolist()
+
+
+def test_standalone_theme_and_colors():
+    import matplotlib.pyplot as plt
+    from workforce_plotting import WFColors, theme_workforce
+    from workforce_plotting.figures import theme_workforce as module_theme
+
+    assert WFColors is OIColors
+    assert module_theme is theme_workforce
+    p = (pn.ggplot(pd.DataFrame({"x": [1, 2], "y": [3, 4]}), pn.aes("x", "y"))
+         + pn.geom_line(color=WFColors.TEAL) + theme_workforce())
+    plt.close(p.draw())