evalrx 0.1.2__py3-none-any.whl

evalrx/agent_assets/skills/nature-figure/references/tutorials.md

@@ -0,0 +1,251 @@
+# Tutorials — Nature Figure Making
+
+End-to-end walkthroughs for the most common publication figure types.
+All examples use helpers from [api.md](api.md) and patterns from [common-patterns.md](common-patterns.md).
+For real production scripts and output previews from figures4papers, open [demos.md](demos.md).
+
+---
+
+## Tutorial 1: Grouped bar chart (multi-metric comparison)
+
+**Goal**: Several methods compared across multiple metrics. Legend in a dedicated panel.
+When methods belong to related families, use one coherent baseline family plus one coherent hero family.
+
+```python
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib import gridspec
+
+# --- Style ---
+plt.rcParams['font.family'] = 'sans-serif'
+plt.rcParams['font.sans-serif'] = ['Arial']
+plt.rcParams['svg.fonttype'] = 'none'
+plt.rcParams['font.size'] = 24
+plt.rcParams['axes.spines.right'] = False
+plt.rcParams['axes.spines.top'] = False
+plt.rcParams['axes.linewidth'] = 3
+
+# --- Data ---
+methods = ['ResNet1d18', 'ResNet1d34', 'ECGFounder', 'CSFM-Tiny', 'CSFM-Base', 'CSFM-Large']
+colors  = ['#484878', '#7884B4', '#B4C0E4', '#E4E4F0', '#E4CCD8', '#F0C0CC']
+metrics = ['Metric 1', 'Metric 2', 'Metric 3']
+mean = {
+    'Metric 1': np.array([0.81, 0.83, 0.86, 0.89, 0.91, 0.92]),
+    'Metric 2': np.array([0.63, 0.67, 0.71, 0.74, 0.77, 0.79]),
+    'Metric 3': np.array([0.41, 0.45, 0.49, 0.53, 0.56, 0.58]),
+}
+std  = {k: v * 0.03 for k, v in mean.items()}  # placeholder
+
+# --- Figure ---
+fig = plt.figure(figsize=(28, 6))
+gs = gridspec.GridSpec(1, len(metrics) + 1)  # +1 for legend panel
+
+handles, labels = None, None
+for col, metric in enumerate(metrics):
+    ax = fig.add_subplot(gs[col])
+    bars = ax.bar(
+        range(len(methods)),
+        mean[metric],
+        yerr=std[metric],
+        capsize=5,
+        color=colors,
+        label=methods,
+        error_kw={'elinewidth': 2, 'capthick': 2},
+    )
+    if col == 0:
+        handles, labels = ax.get_legend_handles_labels()
+    ax.set_xticks([])
+    y_vals = mean[metric]
+    margin = (y_vals.max() - y_vals.min()) * 0.15
+    ax.set_ylim([y_vals.min() - margin, y_vals.max() + margin])
+    ax.set_ylabel(metric, fontsize=32)
+
+# Legend-only panel
+ax_leg = fig.add_subplot(gs[-1])
+ax_leg.legend(handles, labels, fontsize=28, loc='center', frameon=False)
+ax_leg.set_axis_off()
+
+fig.tight_layout(pad=2)
+os.makedirs('./figures', exist_ok=True)
+fig.savefig('./figures/comparison.png', dpi=300)
+fig.savefig('./figures/comparison.pdf', dpi=300)
+plt.close(fig)
+```
+
+---
+
+## Tutorial 2: Ablation bar chart (alpha-graduated, horizontal)
+
+**Goal**: Same method with components progressively added; alpha encodes completeness.
+
+```python
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+
+plt.rcParams['font.family'] = 'sans-serif'
+plt.rcParams['font.sans-serif'] = ['Arial']
+plt.rcParams['svg.fonttype'] = 'none'
+plt.rcParams['font.size'] = 24
+plt.rcParams['axes.spines.right'] = False
+plt.rcParams['axes.spines.top'] = False
+plt.rcParams['axes.linewidth'] = 3
+
+configs = ['None', '+ Module A', '+ Module B', '+ Module C', 'Full']
+values  = np.array([0.72, 0.78, 0.81, 0.84, 0.88])
+stds    = np.array([0.02, 0.02, 0.01, 0.01, 0.01])
+
+n = len(configs)
+blue_rgb = (0.215686, 0.458824, 0.729412)   # #3775BA
+alphas = np.linspace(0.2, 1.0, n)
+colors = [(blue_rgb[0], blue_rgb[1], blue_rgb[2], a) for a in alphas]
+
+fig, ax = plt.subplots(figsize=(12, 6))
+ax.barh(range(n), values, xerr=stds,
+        color=colors, ecolor='k', capsize=5)
+ax.set_yticks(range(n))
+ax.set_yticklabels(configs)
+ax.set_xlim([values.min() - 0.05, values.max() + 0.03])
+ax.set_xlabel('Score', fontsize=32)
+
+fig.tight_layout(pad=2)
+os.makedirs('./figures', exist_ok=True)
+fig.savefig('./figures/ablation.png', dpi=300)
+plt.close(fig)
+```
+
+---
+
+## Tutorial 3: Multi-panel trend with shared legend
+
+**Goal**: Two trend panels (e.g., train/val curves) and a legend-only third panel.
+
+```python
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+
+plt.rcParams['font.family'] = 'sans-serif'
+plt.rcParams['font.sans-serif'] = ['Arial']
+plt.rcParams['svg.fonttype'] = 'none'
+plt.rcParams['font.size'] = 15
+plt.rcParams['axes.spines.right'] = False
+plt.rcParams['axes.spines.top'] = False
+plt.rcParams['axes.linewidth'] = 2
+
+methods = ['Baseline', 'CSFM-Tiny', 'CSFM-Base', 'CSFM-Large']
+colors  = ['#7884B4', '#E4E4F0', '#E4CCD8', '#F0C0CC']
+x = np.arange(0, 100, 5)
+
+fig, axes = plt.subplots(1, 3, figsize=(18, 5))
+
+for panel_idx, (ax, panel_name) in enumerate(zip(axes[:2], ['Training', 'Validation'])):
+    for method, color in zip(methods, colors):
+        y = 0.48 + 0.42 * (1 - np.exp(-x / 30)) + np.random.randn(len(x)) * 0.01
+        if method == 'Baseline':
+            y -= 0.03
+        elif method == 'CSFM-Tiny':
+            y += 0.00
+        elif method == 'CSFM-Base':
+            y += 0.02
+        elif method == 'CSFM-Large':
+            y += 0.03
+        ax.plot(x, y, color=color, lw=2.5, marker='o', markersize=6, label=method)
+    ax.set_title(panel_name, fontsize=18)
+    ax.set_xlabel('Epoch', fontsize=16)
+    ax.set_ylabel('Loss', fontsize=16)
+    if panel_idx == 0:
+        handles, labels = ax.get_legend_handles_labels()
+
+# Legend-only panel
+axes[2].legend(handles, labels, fontsize=14, loc='center', frameon=False)
+axes[2].set_axis_off()
+
+fig.tight_layout(pad=2)
+os.makedirs('./figures', exist_ok=True)
+fig.savefig('./figures/trends.png', dpi=300)
+fig.savefig('./figures/trends.pdf', dpi=300)
+plt.close(fig)
+```
+
+---
+
+## Tutorial 4: Heatmap with dual colormaps (positive/negative columns)
+
+**Goal**: Score matrix where positive = Reds, negative = Blues_r. Cell text auto-contrasted.
+
+```python
+import os
+import numpy as np
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+plt.rcParams['font.family'] = 'sans-serif'
+plt.rcParams['font.sans-serif'] = ['Arial']
+plt.rcParams['svg.fonttype'] = 'none'
+plt.rcParams['font.size'] = 16
+plt.rcParams['axes.spines.right'] = False
+plt.rcParams['axes.spines.top'] = False
+plt.rcParams['axes.linewidth'] = 2
+
+# matrix: rows = methods, cols = metrics (alternating positive/negative directions)
+methods = ['Method A', 'Method B', 'Method C', 'Method D']
+metrics = ['Score (+)', 'Error (-)', 'F1 (+)', 'Loss (-)']
+matrix  = np.array([
+    [0.88,  0.12,  0.85,  0.20],
+    [0.81,  0.18,  0.78,  0.28],
+    [0.75,  0.25,  0.72,  0.35],
+    [0.70,  0.30,  0.68,  0.40],
+])
+
+fig, ax = plt.subplots(figsize=(10, 6))
+n_rows, n_cols = matrix.shape
+vmin, vmax = matrix.min(0), matrix.max(0)
+
+for j in range(n_cols):
+    is_positive = (j % 2 == 0)
+    cmap = plt.cm.Reds if is_positive else plt.cm.Blues_r
+    cmap = cmap.copy()
+    norm = mpl.colors.Normalize(
+        vmin=0 if is_positive else vmax[j],
+        vmax=vmax[j] if is_positive else 0
+    )
+    ax.imshow(matrix[:, j:j+1], cmap=cmap, norm=norm,
+              aspect='auto', extent=[j-0.5, j+0.5, 0, n_rows], origin='lower')
+
+for (i, j), val in np.ndenumerate(matrix):
+    is_positive = (j % 2 == 0)
+    cmap = plt.cm.Reds if is_positive else plt.cm.Blues_r
+    norm = mpl.colors.Normalize(vmin=0 if is_positive else vmax[j],
+                                 vmax=vmax[j] if is_positive else 0)
+    r, g, b, _ = cmap(norm(val))
+    lum = 0.299*r + 0.587*g + 0.114*b
+    color = 'white' if lum < 0.5 else 'black'
+    ax.text(j, i + 0.5, f'{val:.2f}', ha='center', va='center',
+            fontsize=13, color=color)
+
+ax.set_xlim(-0.5, n_cols - 0.5)
+ax.set_xticks(np.arange(n_cols))
+ax.set_xticklabels(metrics, rotation=30, ha='right', fontsize=14)
+ax.tick_params(axis='x', bottom=False, top=False, length=0)
+ax.set_yticks(np.arange(n_rows) + 0.5)
+ax.set_yticklabels(methods, fontsize=14)
+ax.set_frame_on(False)
+ax.invert_yaxis()
+
+fig.tight_layout(pad=2)
+os.makedirs('./figures', exist_ok=True)
+fig.savefig('./figures/heatmap.png', dpi=300)
+plt.close(fig)
+```
+
+---
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to use this skill
+- [api.md](api.md) — Reusable helper implementations
+- [common-patterns.md](common-patterns.md) — Layout and encoding patterns used above
+- [design-theory.md](design-theory.md) — Why these choices exist
+- [chart-types.md](chart-types.md) — Radar, 3D sphere, scatter, fill_between

evalrx/agent_assets/skills/nature-figure/static/core/contract.md

@@ -0,0 +1,29 @@
+# Figure contract before plotting
+
+A publication-quality scientific figure is a visual argument, not an isolated pretty plot. Every figure starts from a claim, an evidence hierarchy, and a review-risk check before code or aesthetics. Before generating or editing code, establish the contract below.
+
+## Backend selection is a blocking gate
+
+If the user has not explicitly chosen Python or R in the current request or provided a clearly language-specific input file/workflow, ask one concise question: **Python or R?** Then stop and wait for the user's answer. Do not generate mock data, write scripts, create figures, or choose Python/R by default. This overrides general autonomy/default-execution behavior for figure tasks.
+
+Only recommend a backend when the user explicitly asks you to choose or recommend one. In that case, use `references/backend-selection.md`, state the reason, and then proceed with the recommended backend.
+
+## The selected backend is exclusive
+
+Once Python or R is selected, every plotting script, preview image, SVG/PDF/TIFF/PNG export, QA render, and visual workaround must be produced by that same backend. Do not use Python to draw a preview for an R figure, and do not use R to draw a preview for a Python figure, even if the selected runtime or packages are missing locally. The non-selected language may only be used for non-visual file inspection or data conversion when it does not open a graphics device, import plotting libraries, create image/vector files, or change the final visual appearance.
+
+## Missing runtime/package rule
+
+After the backend is selected, check the selected runtime early (`Rscript`/R for R; Python and required plotting packages for Python). If the selected runtime or required packages are unavailable, stop before rendering and report the exact blocker. You may provide a selected-backend script and installation commands, or ask permission to install dependencies, but you must not fall back to the other language to make a substitute figure.
+
+## The five-point contract
+
+1. **Core conclusion**: write the one-sentence claim the figure must defend.
+2. **Evidence chain**: map each planned panel to the claim, and drop panels that do not carry a unique piece of evidence.
+3. **Archetype**: classify the figure as `quantitative grid`, `schematic-led composite`, `image plate + quant`, or `asymmetric mixed-modality figure`.
+4. **Backend**: use the selected Python or R track exclusively for all figure drawing, previewing, exporting, and visual QA. Do not cross-render with the other language.
+5. **Journal/export contract**: set final dimensions, editable text, source data, statistics, image-integrity notes, and export formats before styling.
+
+The highest-priority rule is: **the chart serves the scientific logic**. Aesthetic polish, template matching, and complex layout are subordinate to making the core conclusion clear, defensible, and reviewable.
+
+For the full method to convert a request into core conclusion, evidence hierarchy, panel map, and review-risk checks, open `references/figure-contract.md`.

evalrx/agent_assets/skills/nature-figure/static/core/stance.md

@@ -0,0 +1,37 @@
+# Default operating stance
+
+The older Python/matplotlib rules in this skill remain valid. The skill also supports R, especially `ggplot2 + patchwork + ComplexHeatmap + ggrepel + svglite/cairo_pdf + ragg`.
+
+## Color policy
+
+Prefer **unified method families across all panels** over maximal hue separation. For dense Nature Machine Intelligence-style figure pages, use the low-saturation `NMI pastel` family described in `references/api.md` and reserve green/red mainly for gains, drops, and other directional cues.
+
+## Stance
+
+- Start by classifying the requested figure into one of four archetypes: `quantitative grid`, `schematic-led composite`, `image plate + quant`, or `asymmetric mixed-modality figure`.
+- Prefer one **hero panel** plus subordinate evidence panels over filling the canvas with equal-sized subplots.
+- If the user asks for a single chart, still identify its role in the manuscript claim: discovery, mechanism, validation, comparison, robustness, or clinical/biological relevance.
+- Keep the background white for plots and diagrams; switch to black only for microscopy / volume-rendering image plates.
+- Prefer direct labels over legends when categories are spatially fixed or the legend would force unnecessary eye travel.
+- Keep one restrained palette per figure: usually one neutral family, one signal family, and one accent family.
+- Treat statistics, `n`, error-bar definitions, source-data traceability, and image-integrity notes as part of the figure, not as optional caption cleanup.
+- When the user asks for broad `Nature` style rather than ML/NMI-specific style, read `references/nature-2026-observations.md` before choosing layout.
+- When the user references `figures4papers` or the older `scientific-figure-making` skill, treat this skill as the successor and open `references/demos.md` for bundled Python demo scripts.
+
+## User-facing privacy rule
+
+Do not disclose private local paths, private filenames, chat-attachment names, internal reference filenames, template identifiers, or the provenance of private working materials in user-facing replies, generated code comments, figure legends, reports, or manuscript text. Use generic descriptions such as "the provided R template collection", "a private working draft", or "the internal figure contract". If the user provides a private plotting template collection, use it only as an internal adaptation source and do not reveal its path, filenames, or provenance. Only reveal an exact path or source file when the user explicitly asks for that audit trail.
+
+## When to load this skill
+
+- Python or R figures for **papers, slides, or reports** targeting Nature, Science, Cell, NeurIPS, ICLR, or similar venues.
+- Requests involving **grouped bars, trend lines, heatmaps, radar plots, multi-panel grids**, or **PDF/SVG/high-DPI** output.
+- Any mention of "Nature style", "publication figure", "paper figure", "SCI figure", "figures4papers", "scientific-figure-making", "R plotting template", or "high-quality scientific plot".
+- Requests to improve a figure's logic, aesthetics, panel layout, figure legend, export quality, or journal-readiness.
+
+## When NOT to load
+
+- Plotly, Altair, Bokeh, or other interactive/web-first plotting.
+- EDA-only plots without a publication target.
+- Primary workflow is 3D, GIS, or non-scientific illustration tooling.
+- Illustrator / Figma–first layout.

evalrx/agent_assets/skills/nature-figure/static/fragments/backend/python.md

@@ -0,0 +1,37 @@
+# Backend: Python (matplotlib / seaborn)
+
+**Python-only execution rule.** When the user has selected Python, do all figure drawing, previewing, exporting, and visual QA in Python. Do not call R/ggplot2, ComplexHeatmap, patchwork, or any R graphics device to create a temporary preview, fallback export, or layout approximation. If Python or required Python plotting packages are missing, stop before rendering and report the missing dependency. You may still write the Python script, provide `pip`/environment install commands, or ask permission to install dependencies, but do not cross-render the figure in R.
+
+## Python quick-start
+
+```python
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+mpl.rcParams.update({
+    "font.family": "sans-serif",
+    "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
+    "svg.fonttype": "none",     # editable text in SVG
+    "pdf.fonttype": 42,         # editable TrueType text in PDF
+    "font.size": 7,             # use 15-24 only for large slide-sized panels
+    "axes.spines.right": False,
+    "axes.spines.top": False,
+    "axes.linewidth": 0.8,
+    "legend.frameon": False,
+})
+
+def save_pub_py(fig, filename, dpi=600):
+    fig.savefig(f"{filename}.svg", bbox_inches="tight")
+    fig.savefig(f"{filename}.pdf", bbox_inches="tight")
+    fig.savefig(f"{filename}.tiff", dpi=dpi, bbox_inches="tight")
+```
+
+Use `text.usetex = True` only when LaTeX is installed and math-rich labels are required.
+
+## Going deeper
+
+- `references/api.md` — Python PALETTE, helper function signatures, validation rules.
+- `references/common-patterns.md` — hero panels, legend-only axes, dark image plates, asymmetric layouts.
+- `references/chart-types.md` — radar, 3D sphere, fill_between, scatter patterns.
+- `references/tutorials.md` — end-to-end walkthroughs for bars, trends, heatmaps.
+- `references/demos.md` — bundled figures4papers Python scripts and output previews.

evalrx/agent_assets/skills/nature-figure/static/fragments/backend/r.md

@@ -0,0 +1,44 @@
+# Backend: R (ggplot2 / patchwork / ComplexHeatmap)
+
+**R-only execution rule.** When the user has selected R, do all figure drawing, previewing, exporting, and visual QA in R. Do not call matplotlib/seaborn or any Python graphics device to create a temporary preview, fallback export, or layout approximation. If `Rscript`/R or required R packages are missing, stop before rendering and report the exact blocker. You may still write the R script, provide install commands (for example `install.packages(...)`), or ask permission to install dependencies, but do not cross-render the figure in Python.
+
+## R quick-start
+
+```r
+library(ggplot2)
+library(patchwork)
+
+theme_set(
+  theme_classic(base_size = 6.5, base_family = "Arial") +
+    theme(
+      axis.line = element_line(linewidth = 0.35, colour = "black"),
+      axis.ticks = element_line(linewidth = 0.35, colour = "black"),
+      legend.title = element_text(size = 6.2),
+      legend.text = element_text(size = 5.8),
+      strip.text = element_text(size = 6.2, face = "bold"),
+      plot.title = element_text(size = 7, face = "bold"),
+      panel.grid = element_blank()
+    )
+)
+
+save_pub_r <- function(plot, filename, width_mm = 183, height_mm = 120, dpi = 600) {
+  w <- width_mm / 25.4
+  h <- height_mm / 25.4
+  svglite::svglite(paste0(filename, ".svg"), width = w, height = h)
+  print(plot)
+  dev.off()
+  grDevices::cairo_pdf(paste0(filename, ".pdf"), width = w, height = h, family = "Arial")
+  print(plot)
+  dev.off()
+  ragg::agg_tiff(paste0(filename, ".tiff"), width = w, height = h, units = "in", res = dpi)
+  print(plot)
+  dev.off()
+}
+```
+
+## Going deeper
+
+- `references/r-workflow.md` — the R plotting workflow when the user provides R scripts, templates, or data.
+- `references/r-template-index.md` — adapt a user-provided or private R template collection without exposing source paths.
+- `references/design-theory.md` — typography, color theory, layout rationale, export policy (backend-agnostic).
+- `references/nature-2026-observations.md` — real Nature page archetypes to match before choosing layout.

evalrx/agent_assets/skills/outcome-driver-analysis/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: outcome-driver-analysis
+description: >
+  Run a full, disciplined statistical analysis to find what differentiates a binary
+  outcome (success vs. fail, pass vs. fail, correct vs. incorrect) using a set of
+  explanatory variables the user specifies. Covers exploring the explanatory variables
+  themselves (distributions, outliers, missingness, correlations), exploring each
+  variable against the outcome (contingency tables for categorical variables,
+  distribution comparisons for continuous variables, conditioning on other variables),
+  marginal screening, fitting a justified regression model (logistic vs. linear vs.
+  mixed-effects, with explicit reasoning), goodness-of-fit diagnostics, result
+  visualization, and a plain-language written report. Use this whenever the user has
+  examples labeled by a binary outcome plus candidate explanatory variables and wants
+  to know what drives the difference -- e.g. analyzing model error cases ("why do
+  these examples fail"), pass/fail experiment results, or any dataset framed as
+  success/failure with covariates -- even if they don't use the word "statistics."
+  Do NOT use this for pure simulation studies with no real data, generating
+  paper-ready LaTeX tables for an already-written paper, or benchmarking many methods
+  against each other across datasets -- those are out of scope.
+version: 0.2.0
+license: MIT
+compatibility: Claude Code project-scoped skill. Assumes R and/or Python available on PATH; pick whichever is appropriate per task rather than requiring both.
+metadata:
+  tags: statistics research-workflow eda logistic-regression mixed-effects reproducibility R Python
+  agentskills_spec: "1.0"
+---
+
+# Outcome driver analysis
+
+You are running a statistical analysis to explain a binary outcome (success/fail,
+pass/fail, correct/incorrect) using explanatory variables the user provides. Work
+through the pipeline below in order -- each step's findings feed the next one. Do not
+skip straight to modeling: the exploratory steps surface issues (outliers, missing
+data, collinearity, confounding) that change how the model should be built and read.
+
+## Scope
+
+This skill is for analyzing a real dataset with a binary outcome and candidate
+explanatory variables -- most often model error analysis (why did these examples
+fail?), but equally applicable to any pass/fail or success/failure outcome with
+covariates. It is not for simulation studies with no real data, generating
+publication-ready LaTeX tables for a paper that's already written, or benchmarking
+many methods against each other across datasets.
+
+## Chart types and palettes: defer to a chart-style skill when present
+
+This skill decides WHAT to visualize at each step (the statistical intent);
+it does not own HOW. When a dedicated chart-style skill (e.g.
+`eval-chart-style`) is installed alongside this one, that skill's chart-type
+policy and palette GOVERN every figure called for below — read the concrete
+figure prescriptions in steps 2, 3 and 7 as the standalone fallback for when
+no chart-style skill is present, never as an override of one.
+
+## Choosing R or Python
+
+Pick per task, in this order:
+1. If the user is continuing an existing project, match whatever language that
+   project's code already uses.
+2. Otherwise, pick based on the modeling need identified in step 5: mixed-effects /
+   hierarchical models are frequently more ergonomic in R (`lme4`, `glmmTMB`), while
+   plain logistic regression, screening, and diagnostics are equally well supported in
+   both R and Python (`statsmodels`, `scikit-learn`).
+3. If genuinely ambiguous, ask the user.
+
+Bundled helper scripts exist in both languages under `scripts/` -- use the one that
+matches your choice; they are templates to adapt to the actual variable names and
+data, not black boxes to run unmodified.
+
+## 1. Intake -- clarify variables and structure
+
+Before writing any code, confirm (from what the user already said, or by asking):
+- Which column is the binary outcome, and which columns are the explanatory variables
+  to investigate.
+- The research question or problem behind the analysis -- what decision or
+  understanding this is meant to support. Record it; the final report must be framed
+  around it, not written as a generic statistical summary.
+- Each explanatory variable's type: categorical, continuous, or count.
+- Whether observations are clustered or repeated -- e.g. multiple examples from the
+  same underlying model, prompt template, dataset, or subject. This is needed later to
+  decide whether a mixed-effects model is warranted.
+
+## 2. Explanatory-variable EDA
+
+Before relating anything to the outcome, characterize the explanatory variables on
+their own terms:
+- **Distribution**: histogram (continuous) or bar chart (categorical) per variable.
+- **Outliers**: flag with an IQR or z-score rule for continuous variables; flag rare
+  categories for categorical variables.
+- **Missingness**: count and pattern per variable. Spot-check whether missingness
+  itself is associated with the outcome (missing values are often not random).
+- **Inter-variable structure**: correlation matrix for continuous-continuous pairs,
+  Cramer's V for categorical-categorical pairs, correlation ratio (eta-squared) or
+  ANOVA for mixed pairs. This surfaces redundant or collinear explanatory variables
+  early, before they cause multicollinearity problems at the modeling stage.
+
+Use `scripts/explanatory_var_eda.R` or `.py` as a starting template.
+
+## 3. Per-variable exploration vs. outcome
+
+For each explanatory variable, relate it to the outcome:
+- **Categorical variable** -> contingency table (variable x outcome) with row/column
+  proportions; chi-square test of independence, or Fisher's exact test when any
+  expected cell count is small (below ~5).
+- **Continuous variable** -> a per-group distribution-comparison figure
+  (standalone fallback: side-by-side boxplot; an installed chart-style skill's
+  distribution-first policy — e.g. violin + jittered points — takes
+  precedence), plus a group-comparison test: Welch's t-test if roughly normal,
+  Mann-Whitney U as the robust default when normality is doubtful.
+- Always report an effect size next to the test, not just a p-value: Cramer's V or
+  odds ratio for categorical variables, Cohen's d or rank-biserial correlation for
+  continuous variables.
+- **Conditioning**: repeat the above stratified by, or faceted on, a plausible
+  confounding or interacting variable. Flag relationships that appear, vanish, or
+  reverse within strata (a Simpson's-paradox pattern) -- these are candidates for an
+  interaction term or control variable in the model stage, not things to quietly drop.
+
+Use `scripts/univariate_eda.R` or `.py` as a starting template.
+
+## 4. Marginal variable screening
+
+Before committing to a multivariable model, screen each explanatory variable for a
+marginal (unadjusted) signal against the outcome: fit a univariate logistic regression
+per variable (or reuse the chi-square/t-test/Mann-Whitney results from step 3), and
+rank by p-value or by AIC improvement over the null model.
+
+This matters most when there are many candidate variables -- it narrows the field to a
+manageable candidate set for the full model. Do not silently drop a variable just
+because its bivariate test wasn't significant; a real effect can be masked by a
+confounder and only emerge once other variables are adjusted for in step 5. Screening
+informs the candidate list, it does not replace the full model.
+
+Screening metrics and thresholds are summarized in `references/model_selection.md`.
+
+## 5. Model selection and fitting, with explicit justification
+
+Consult `references/model_selection.md` for the full decision table. The core logic:
+
+- **Binary outcome -> logistic regression, not linear regression.** State explicitly
+  why: a linear model can predict outside [0, 1], and its error/variance structure
+  doesn't match a 0/1 target (violates linearity and homoscedasticity assumptions that
+  linear regression relies on). Continuous outcomes would call for linear regression
+  instead, and count outcomes for Poisson or negative binomial -- this decision logic
+  generalizes even though the immediate case here is binary.
+- **Plain GLM vs. mixed-effects (GLMM)**: use a random effect for the clustering
+  variable identified in step 1 when observations are not independent (repeated
+  examples from the same model, prompt, or dataset). Use a plain GLM when observations
+  are reasonably independent. State this decision and the reasoning tied to the actual
+  data structure -- don't pick silently.
+- **Candidate predictors**: start from the variables that passed step 4 screening, plus
+  any interaction flagged by the step 3 conditioning check.
+- **Per-variable significance in the fitted model**: after fitting, test each
+  variable's significance with a Wald test or a likelihood-ratio test (comparing the
+  model with and without that term). Report this alongside the bivariate/screening
+  results from steps 3-4, so the reader can see whether a variable's marginal signal
+  holds up after adjusting for the others, or was actually explained by a confounder.
+
+Use `scripts/fit_outcome_model.R` or `.py` as a starting template.
+
+## 6. Goodness-of-fit and diagnostics
+
+- Hosmer-Lemeshow test (or a suitable alternative when there are many continuous
+  predictors, since Hosmer-Lemeshow can be unreliable there).
+- Deviance or Pearson residuals, binned residual plots.
+- VIF for multicollinearity among the final model's predictors.
+- Influence diagnostics (e.g. Cook's-distance analogs for GLMs).
+- ROC curve and AUC for discrimination; a calibration plot for calibration.
+- For GLMMs specifically: also check random-effect variance estimates, intraclass
+  correlation (ICC), and convergence warnings.
+
+## 7. Visualize results
+
+- Coefficient / odds-ratio forest plot with confidence intervals.
+- Predicted-probability curves for the key continuous predictors (holding other
+  variables at a reference value or mean).
+- ROC curve and calibration plot (carried over from step 6, presented as final results
+  rather than diagnostics here).
+
+## 8. Conclusion and report
+
+State which variables matter, in which direction, with what size and uncertainty, and
+tie the finding back to the steps 2-5 evidence (distribution/outlier caveats, bivariate
+and screening signal, adjusted-model significance) as corroboration or explanation.
+
+Frame the conclusion around the specific research question recorded in step 1 -- not
+as a generic statistical summary. Write it in plain language: the audience is
+scientific researchers who understand research methodology but are not necessarily
+statisticians, so translate statistical results into substantive meaning (for example,
+"cases where X exceeded N were far more likely to fail" rather than reporting only an
+odds ratio and a p-value), while still surfacing the effect size, uncertainty, and any
+caveats a careful reader would need (small samples, assumption violations, correlated
+predictors).
+
+Figure styling conventions come from the installed chart-style/polish skills
+(e.g. `eval-chart-style` for chart types and palette, `nature-figure` for
+publication polish) -- do not duplicate those conventions here.
+
+Save reproducibility information -- environment/package versions and any random seeds
+used -- to `session_info.txt` alongside the analysis.
+
+Start each new analysis under `projects/<analysis-name>/`, with the raw dataset copied
+(read-only) into `data/`, outputs written to `output/figures/` and `output/tables/`,
+and the writeup as `report.md` following `assets/analysis_report_template.md`.
+
+## Reference files
+
+- `references/model_selection.md` -- decision tables for outcome type x clustering x
+  assumption status -> model family, the univariate-test decision table from step 3,
+  and the marginal-screening metrics from step 4. Read this when deciding on a test or
+  model.
+- `scripts/explanatory_var_eda.R` / `.py` -- step 2 starting template.
+- `scripts/univariate_eda.R` / `.py` -- steps 3-4 starting template.
+- `scripts/fit_outcome_model.R` / `.py` -- steps 5-7 starting template.
+- `assets/analysis_report_template.md` -- report skeleton for step 8.

evalrx/agent_assets/skills/outcome-driver-analysis/assets/analysis_report_template.md

@@ -0,0 +1,53 @@
+<!--
+Report skeleton for step 8 of the outcome-driver-analysis skill. Copy this into
+projects/<analysis-name>/report.md and fill it in.
+
+Figure/table formatting and prose style are covered by the clear-technical-writing
+skill -- apply its conventions when writing the actual content, don't duplicate them
+here.
+-->
+
+# [Analysis title]
+
+## Research question
+
+What decision or understanding is this analysis meant to support (from intake, step 1)?
+
+## Data
+
+Source, size, outcome definition, explanatory variables and their types, any known
+data-quality caveats.
+
+## Explanatory-variable summary
+
+Distributions, outliers, missingness, notable correlations among explanatory variables
+(step 2).
+
+## Univariate findings
+
+How each explanatory variable relates to the outcome on its own, and what changes when
+conditioning on other variables (step 3). Marginal screening results (step 4).
+
+## Model and justification
+
+Which model was fit and why (outcome type, independence/clustering structure, step 5).
+Per-variable significance after adjusting for other predictors.
+
+## Diagnostics
+
+Goodness-of-fit, residuals, multicollinearity, discrimination and calibration (step 6).
+
+## Results
+
+Coefficient/odds-ratio plot, predicted-probability curves, ROC and calibration plots
+(step 7).
+
+## Conclusions
+
+Plain-language answer to the research question above: which variables matter, in what
+direction, how strongly, and with what caveats. Written for a scientific-researcher
+audience, not a statistics audience (step 8).
+
+## Reproducibility
+
+Environment/package versions and random seeds used (see `session_info.txt`).