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.
