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

workforce_plotting-0.3.0/PKG-INFO

@@ -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/README.md

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

@@ -0,0 +1,48 @@
+"""The five plotting functions with no extra layers; all data are illustrative.
+
+Run: python examples/default_examples.py outputs/defaults
+"""
+
+import sys
+from pathlib import Path
+
+import polars as pl
+
+from workforce_plotting import (
+    plot_bars, plot_intervals, plot_lines, plot_scatter, plot_validation,
+)
+
+
+def examples():
+    lines = pl.DataFrame({
+        "year": [2019, 2020, 2021, 2022, 2023] * 2,
+        "earnings": [12000, 14000, 18000, 22000, 25000,
+                     12000, 13000, 15000, 18000, 20000],
+        "group": ["Group A"] * 5 + ["Group B"] * 5,
+    })
+    paired = pl.DataFrame({
+        "dml": [-1500, -1800, 900, 2500, 1800, 5200, 6500, 7200, 11000],
+        "rct": [-2500, -1000, 200, 1500, 2500, 4000, 6000, 8000, 10000],
+    })
+    bars = pl.DataFrame({"specification": ["A", "B", "C"], "rmse": [9500, 3800, 1800]})
+    intervals = pl.DataFrame({
+        "program": ["Program A", "Program B", "Program C"],
+        "effect": [1200, 2500, -500],
+        "lower": [200, 1400, -1500], "upper": [2200, 3600, 500],
+    })
+    return {
+        "plot_lines": plot_lines(lines, x="year", y="earnings", series="group"),
+        "plot_validation": plot_validation(paired, x="dml", y="rct"),
+        "plot_bars": plot_bars(bars, x="specification", y="rmse"),
+        "plot_scatter": plot_scatter(paired, x="dml", y="rct"),
+        "plot_intervals": plot_intervals(intervals, x="program", y="effect",
+                                          lower="lower", upper="upper"),
+    }
+
+
+if __name__ == "__main__":
+    output = Path(sys.argv[1] if len(sys.argv) > 1 else "outputs/defaults")
+    output.mkdir(parents=True, exist_ok=True)
+    for name, plot in examples().items():
+        plot.save(output / f"{name}.png", dpi=180, verbose=False)
+        plot.save(output / f"{name}.svg", verbose=False)

workforce_plotting-0.3.0/examples/paper_examples.py

@@ -0,0 +1,130 @@
+"""Paper-style recipes using invented values, not research results.
+
+Run: python examples/paper_examples.py outputs/examples
+"""
+
+import sys
+from pathlib import Path
+
+import polars as pl
+import plotnine as pn
+
+from workforce_plotting import (
+    dollars, plot_bars, plot_intervals, plot_lines, plot_scatter, plot_validation,
+)
+
+
+def examples():
+    # Connected event-study estimates. The analysis supplies the intervals.
+    event = pl.DataFrame({
+        "year": [-3, -2, -1, 0, 1, 2, 3] * 2,
+        "group": ["RCT"] * 7 + ["DML"] * 7,
+        "effect": [-100, 150, 0, 1200, 2100, 2500, 2700,
+                   0, 100, 0, 1000, 2000, 2600, 2800],
+    }).with_columns(
+        pl.col("group").cast(pl.Enum(["RCT", "DML"])),
+        lower=pl.col("effect") - 400, upper=pl.col("effect") + 400,
+    )
+    event_study = (plot_lines(event, x="year", y="effect", series="group",
+                              lower="lower", upper="upper", cap_width=0.05)
+        + pn.geom_hline(yintercept=0, color="#A0A0A0", size=0.54)
+        + pn.scale_y_continuous(labels=dollars)
+        + pn.scale_x_continuous(breaks=list(range(-3, 4)))
+        + pn.labs(title="Event study", x="Years Relative to Treatment", y="Earnings Effect"))
+
+    # Supplied RMSE estimates: neither fitting nor noise adjustment happens here.
+    complexity = pl.DataFrame({
+        "share": [1.0, 3.33, 10.0, 33.3, 100.0] * 4,
+        "sample": ["Full population"] * 5 + ["1%"] * 5
+                  + ["0.04% (CPS-sized)"] * 5 + ["0.02%"] * 5,
+        "rmse": [10000, 5800, 2300, 1600, 1500, 10200, 5800, 2500, 1800, 1800,
+                 9800, 5800, 3300, 2600, 2600, 9200, 6500, 5100, 3900, 3400],
+    }).with_columns(pl.col("sample").cast(pl.Enum(
+        ["Full population", "1%", "0.04% (CPS-sized)", "0.02%"])))
+    complexity_plot = (plot_lines(complexity, x="share", y="rmse", series="sample")
+        + 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, 3000, 6000, 9000, 12000], labels=dollars)
+        + pn.coord_cartesian(ylim=(0, 12000))
+        + pn.labs(title="Model complexity", x="Model Complexity (% of Tuned Model)",
+                  y="Noise-Adjusted RMSE")
+        + pn.theme(legend_position_inside=(0.97, 0.97),
+                   legend_justification_inside=(1, 1)))
+
+    validation = pl.DataFrame({
+        "rct": [-2500, -1000, 200, 1500, 2500, 4000, 6000, 8000, 10000],
+        "twin": [-1500, -1800, 900, 2500, 1800, 5200, 6500, 7200, 11000],
+    }).with_columns(
+        x_lower=pl.col("twin") - 900, x_upper=pl.col("twin") + 900,
+        y_lower=pl.col("rct") - 1300, y_upper=pl.col("rct") + 1300,
+    )
+    validation_plot = (plot_validation(validation, x="twin", y="rct",
+        x_lower="x_lower", x_upper="x_upper", y_lower="y_lower", y_upper="y_upper",
+        limits=(-5000, 12000), cap_width=150)
+        + pn.scale_x_continuous(labels=dollars)
+        + pn.scale_y_continuous(labels=dollars)
+        + pn.labs(title="Validation", x="DML Treatment Effect", y="RCT Treatment Effect"))
+
+    comparisons = pl.DataFrame({
+        "specification": ["Demographics", "+ Earnings", "+ Geography"],
+        "rmse": [9500, 3800, 1800],
+    })
+    bars = (plot_bars(comparisons, x="specification", y="rmse")
+        + pn.scale_x_discrete(limits=comparisons["specification"].to_list())
+        + pn.scale_y_continuous(labels=dollars, expand=(0, 0, 0.1, 0))
+        + pn.labs(title="Covariate comparison", x="", y="Noise-Adjusted RMSE"))
+
+    placement = pl.DataFrame({"placement": [20, 30, 40, 50, 60],
+                              "effect": [1500, 2600, 2100, 4200, 4800]})
+    # The analysis supplies the fitted values; plot_scatter only draws them.
+    fitted = pl.DataFrame({"placement": [20, 60], "effect": [1300, 4700]})
+    scatter = (plot_scatter(placement, x="placement", y="effect", fitted=fitted)
+        + pn.scale_y_continuous(labels=dollars)
+        + pn.scale_x_continuous(labels=lambda xs: [f"{x:g}%" for x in xs])
+        + pn.labs(title="Scatter with supplied fitted line", x="Placement Rate", y="Earnings Effect"))
+
+    intervals = pl.DataFrame({
+        "program": ["Program A", "Program B", "Program C"] * 2,
+        "estimator": ["RCT"] * 3 + ["DML"] * 3,
+        "effect": [1200, 2500, -500, 1500, 2200, -200],
+        "lower": [200, 1400, -1500, 900, 1600, -800],
+        "upper": [2200, 3600, 500, 2100, 2800, 400],
+    }).with_columns(pl.col("estimator").cast(pl.Enum(["RCT", "DML"])))
+    interval_plot = (plot_intervals(intervals, x="program", y="effect",
+        lower="lower", upper="upper", series="estimator")
+        + pn.geom_hline(yintercept=0, color="#A0A0A0", size=0.54)
+        + pn.coord_flip()
+        + pn.scale_x_discrete(limits=["Program C", "Program B", "Program A"])
+        + pn.scale_y_continuous(labels=dollars)
+        + pn.labs(title="Estimates across programs", x="", y="Earnings Effect"))
+
+    cohorts = pl.DataFrame({
+        "year": [2010, 2012, 2014, 2016, 2018] * 2,
+        "city": ["City A"] * 5 + ["City B"] * 5,
+        "effect": [4000, 6000, 5500, 9000, 11000, 5000, 7500, 6500, 6000, 4000],
+    }).with_columns(pl.col("city").cast(pl.Enum(["City A", "City B"])),
+                   lower=pl.col("effect") - 1500, upper=pl.col("effect") + 1500)
+    curves = pl.DataFrame({
+        "year": [2010, 2012, 2014, 2016, 2018] * 2,
+        "city": ["City A"] * 5 + ["City B"] * 5,
+        "effect": [4000, 5200, 6800, 8800, 11000, 5400, 6600, 6800, 6000, 4200],
+    }).with_columns(pl.col("city").cast(pl.Enum(["City A", "City B"])))
+    cohort_plot = (plot_scatter(cohorts, x="year", y="effect", series="city",
+        lower="lower", upper="upper", fitted=curves, cap_width=0.08)
+        + pn.scale_y_continuous(labels=dollars)
+        + pn.scale_x_continuous(breaks=[2010, 2012, 2014, 2016, 2018])
+        + pn.labs(title="Cohorts with supplied curves", x="Enrollment Year", y="Earnings Effect"))
+
+    plots = {"event_study": event_study, "validation": validation_plot,
+             "bars": bars, "scatter": scatter, "intervals": interval_plot,
+             "cohorts": cohort_plot, "complexity": complexity_plot}
+    return {name: p + pn.labs(caption="Illustrative data; not research results.")
+            + pn.theme(plot_caption=pn.element_text(size=9)) for name, p in plots.items()}
+
+
+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=180, verbose=False)
+        plot.save(output / f"{name}.svg", verbose=False)

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

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

{workforce_plotting-0.2.0 → workforce_plotting-0.3.0}/src/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"]