# Shap Figures

> Produce top-journal / Nature-grade SHAP visualisations. Use this whenever the user works with SHAP values or wants to beautify / generate publication-quality SHAP figures — SHAP beeswarm & summary plots, mean-|SHAP| feature-importance bars + nightingale rose, SHAP dependence plots (GAM fit with CI, red/blue positive-negative fills, thresholds, in-panel R² & p), spatial SHAP point maps (coolwarm d…

- **Type:** Skill
- **Install:** `agentstack add skill-brad-zqh-shap-figures-shap-figures`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Brad-zqh](https://agentstack.voostack.com/s/brad-zqh)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Brad-zqh](https://github.com/Brad-zqh)
- **Source:** https://github.com/Brad-zqh/shap-figures

## Install

```sh
agentstack add skill-brad-zqh-shap-figures-shap-figures
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Journal-grade SHAP figures (coolwarm toolkit)

A reusable toolkit for publication-quality ML / SHAP / GAM / GIS visualisation.
Use the bundled `scripts/shap_viz.py` (axes-level helpers — you own the
`Figure`/`GridSpec`, the helpers draw into your `Axes`).

## When to use
The user asks to "beautify", "make journal-quality / Nature-style", or generate:
SHAP beeswarm/summary, importance (bar + rose), GAM dependence, model accuracy
scatter, spatial SHAP maps, monthly trend, ablation, or combined multi-panel figures.

## Design rules (keep consistent)
- **Coolwarm everywhere**: blue = low / negative, red = high / positive.
  `CMAP_FV` soft default; `CMAP_DEEP` for beeswarm (deeper ends); `CMAP_SEQ` warm
  sequential (density / importance); standard `coolwarm` for maps & model scatter.
- **Categories**: pick 3 colours (e.g. red / blue / grey) and colour feature names,
  bars and rose wedges consistently.
- **Big, clear serif fonts** (Times New Roman → DejaVu Serif fallback); hairline
  spines; no chart-junk; titles can live in filenames.
- **Composites** get compact `(a) … / (b) … / (c) …` labels via `stack_images(labels=…)`.
- Dependence panels annotate **R²**, **p**, and a Positive/Negative/Threshold legend
  *inside* each subplot. Keep feature order **consistent** across grouped panels.
- Maps: light CartoDB Positron basemap, north arrow + scale bar, deeper coolwarm.
- Save with `bbox_inches="tight"`, dpi 300–400.

## How to use the library
```python
import sys; sys.path.insert(0, os.path.expanduser(
    "~/.claude/skills/shap-figures/scripts"))
import shap_viz as jv
jv.set_style()                       # global serif / sizes

# SHAP beeswarm (one panel)
jv.beeswarm(ax, shap_mat, feat_vals, names, cmap=jv.CMAP_DEEP,
            xlim=(lo, hi), name_colors=colors)   # xlim trims extreme points
jv.add_colorbar(ax, fig, cmap=jv.CMAP_DEEP)

# Importance bar + nightingale rose
jv.importance_panel(ax, importances, names, colors, letter="a", title="Revenue")

# GAM dependence (needs pygam)
jv.gam_dependence(ax, x, shap_x, name="Vegetation", x_transform=to_original_units)

# Spatial SHAP map (xs, ys in EPSG:3857 if basemap=True)
norm = jv.coolwarm_point_map(ax, xs, ys, shap_vals, basemap=True)
jv.north_arrow(ax); jv.scale_bar(ax, length_units=20000, label="20 km")

# Combine saved panels into a labelled composite
jv.stack_images(paths, "combined.png", vertical=True,
                labels=jv.dep_labels(["Revenue", "ADR", "RevPAR"]))
```

## Function reference (`shap_viz.py`)
- `set_style(serif, base)` — global rcParams.
- `beeswarm(ax, shap_mat, feat_vals, names, cmap, dot, xlim, spread_frac, name_colors)`.
- `add_colorbar(ax, fig, cmap, label, full_height)` — Low/High slim bar.
- `importance_panel(ax, importances, names, colors, letter, title, with_rose, fs)`.
- `gam_fit(x, y)` → grid, curve, CI, crossings, R², p. `gam_dependence(ax, x, y, …)`.
- `coolwarm_point_map(ax, xs, ys, values, pct, basemap)` → TwoSlopeNorm.
- `north_arrow(ax)`, `scale_bar(ax, length_units, label)`.
- `stack_images(paths, out, vertical, labels, label_frac)`, `dep_labels(names)`.
- `cat_gradient(base_colors, n)` — graded ramp; `despine(ax)`; palette constants
  `CMAP_FV / CMAP_DEEP / CMAP_SEQ / CAT_COLOR / INK / GRID`.

## Notes
- Optional deps: `pygam` (dependence), `contextily` + `pyproj` (basemaps), `Pillow`
  (`stack_images`). The library imports them lazily so unrelated calls don't fail.
- Helpers are dataset-agnostic: pass arrays / values, not file paths.
- When editing Jupyter cells programmatically, read content from a file then write —
  don't put back-tick text inside `python3 -c "…"` (the shell eats back-ticks).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Brad-zqh](https://github.com/Brad-zqh)
- **Source:** [Brad-zqh/shap-figures](https://github.com/Brad-zqh/shap-figures)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-brad-zqh-shap-figures-shap-figures
- Seller: https://agentstack.voostack.com/s/brad-zqh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.