matlab/matlab-agentic-toolkit / skills-catalog/ai-and-statistics/matlab-interpret-machine-learning-model
matlab-interpret-machine-learning-model
VerifiedInterpret and explain a trained tabular machine-learning model (classification or regression) in MATLAB. Find which predictors, features, or columns matter most; explain why the model made a specific prediction, including diagnosing predictions it got wrong; show how a predictor affects the output; and compare how the model behaves across cohorts or subgroups. Uses model-agnostic techniques and model-native measures, and works on custom models (such as a dlnetwork) through a prediction function handle. Use for model interpretability, explainability, and feature-importance questions on tabular data, not for training, tuning, feature selection, deploying models, or models trained on image, text, signal, or other non-tabular data.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 31.8 KB |
| manifest.yaml | config | 556 B |
| references/agnostic-effect-shape.md | markdown | 6.8 KB |
| references/agnostic-global-importance.md | markdown | 9.6 KB |
| references/agnostic-local-explanation.md | markdown | 6.6 KB |
| references/cohort-analysis.md | markdown | 4.5 KB |
| references/custom-model-wrapper.md | markdown | 9.4 KB |
| references/native-importance-measures.md | markdown | 9.9 KB |
| scripts/functionHandleMap.m | other | 3.9 KB |
references/cohort-analysis.md
View on GitHub# Cohort / Subgroup Behavior
Compare how the model behaves across operational cohorts (segments, groups): which predictors drive it within each cohort, and how their influence shifts from one cohort to the next.
This is a **group-conditioned analysis**: pick a grouping variable, then compare the model's drivers across its groups.
## Data rule
The **cohorts come from the user** — the segments they want compared (a region, an age band, an operating regime). Subset the data by cohort. Keep the analysis **consistent across cohorts** so the differences are attributable to the cohorts themselves, not to the setup: for `shapley`, hold the **background (`Xtrain`) fixed** across all cohorts; for `permutationImportance`, use the **same predictors and response** on each cohort subset. Prefer **test** data; with training-only data, tell the user the comparison reflects training behavior.
## Decision rule
The per-cohort measure is the same choice as [agnostic-global-importance.md](agnostic-global-importance.md), applied within each cohort; see that reference for the full `permutationImportance`-vs-`shapley` reasoning. In brief:
- **Per-cohort `permutationImportance`** (R2024a) when the comparison is about **magnitude / rank** and a response is available per cohort: gives a stability std for free, answers what each cohort **relies on for accuracy**. It is **unsigned**, so it cannot show a direction flip.
- **Per-cohort `shapley`** (R2021a) when **direction** matters (does a predictor push up in cohort A but down in cohort B), when no response labels are available, or when a Shapley workflow is already running. Signed and complete.
Then, whichever measure is used, **compare with a shift-sensitive lens:**
- Report what **changed** between cohorts predictor-by-predictor: rank deltas and magnitude deltas (and, for `shapley`, direction changes).
- **Do not collapse the comparison to a single global-similarity score** (cosine, correlation, or the like). A global score averages over predictors and hides the local signal that matters: a single-predictor rank flip between two cohorts can leave a high similarity score intact, so the model reads as "reasoning the same way" across cohorts when a decisive predictor has in fact swapped rank. The predictor-by-predictor deltas are the deliverable; a summary score is not a substitute.
## Implementation
**Per-cohort `shapley`** — background fixed across cohorts:
```matlab
explA = shapley(Mdl, Xtrain, QueryPoints=XqueryCohortA, UseParallel="auto");
explB = shapley(Mdl, Xtrain, QueryPoints=XqueryCohortB, UseParallel="auto");
% Compare explA.MeanAbsoluteShapley vs explB.MeanAbsoluteShapley predictor-by-predictor:
% which predictors changed rank, magnitude, or direction between the cohorts?
```
For direction, read signed values from the explainer's `Shapley` property (`MeanAbsoluteShapley` is unsigned). Its value columns are `predictors × query points` matrices; a classifier has one per class, regression and a function handle have one named `Value`. (`Shapley` was `ShapleyValues` before R2024b.)
`swarmchart` / `boxchart` per cohort show each cohort's contribution distribution (see [agnostic-global-importance.md](agnostic-global-importance.md) for the plural-`plot` vs singular-`swarmchart`/`boxchart` method-name split).
**Per-cohort `permutationImportance`** — same response name on each subset:
```matlab
impA = permutationImportance(Mdl, XcohortA, "responseName", Options=statset(UseParallel="auto"));
impB = permutationImportance(Mdl, XcohortB, "responseName", Options=statset(UseParallel="auto"));
% Compare impA.ImportanceMean vs impB.ImportanceMean predictor-by-predictor.
```
Plot each cohort's `ImportanceMean` as a grouped bar chart with `ImportanceStandardDeviation` as error bars — overlapping error bars across cohorts signal the difference is within noise.
## If `Mdl` is a function handle
`permutationImportance` has **no handle path**, so a custom model compares cohorts with per-cohort `shapley` instead (the reroute from Decision 2). Build and call the `shapley` handle exactly as in [agnostic-global-importance.md](agnostic-global-importance.md) (pass `Xtrain`, set `CategoricalPredictors` or omit it when none, and state which predictors you are treating as categorical). For a multiclass model the handle returns a single class's score column, so `MeanAbsoluteShapley` covers that one class; build one explainer per class of interest (the per-class handle decided in [custom-model-wrapper.md](custom-model-wrapper.md)), and compare the same class across cohorts.
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |