effector's report
Description
The in-depth guide to part (b) of effector's API:
the one-liner effector.explain(...), the Report it returns, and a map
of its components; each component has its own page.
Reading time
Approx. 5' to read; each component page is another 2' to 7'.
One call
import effector
report = effector.explain(X, model, schema=schema, y=y_test)
explain walks the interactive API for you, with
default settings, in a fixed order:
flowchart LR
A["<b>fit</b><br/>once"] --> B["<b>rank</b><br/>importance"]
B --> C["<b>hunt</b><br/>find_regions on the<br/>heterogeneous features"]
C --> D["<b>select</b><br/>which splits pay<br/>for themselves"]
D --> E["<b>freeze</b><br/>โ Report"]The result is a value, not a live handle on the engine: you can pickle it,
to_dict() it, mail it, and read it back with Report.from_dict() on a machine
that has neither your model nor your data.
The headline
Before anything else, explain prints the one number worth having:
[effector] global effects (GAM) -> 71.7% of the model's variance
regional effects (CALM) -> 88.6%
๐ How much of your model does this explanation actually capture? Each line is a surrogate you could actually ship. The GAM is the purely global read: one curve per feature, no regions; it reproduces 71.7% of the model's variance. The CALM allows subregions and reaches 88.6%. You may interpret them both as:
How to read the headline
The global effects (GAM) explain the black-box model with 71.7% fidelity. The regional effects (CALM) explain the black-box model with 88.6% fidelity.
The second line only appears when a split was accepted; a model that is already additive prints one line, and that is the correct answer.
โ ๏ธ If that first number is low, every global effect plot you are about to look at is a bad summary of your model. That is the point of showing it first.
Reading .show()
report.show()
Three tables, then the partition trees.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
PDP report ยท target: bike-rentals
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
DATA & MODEL
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
instances 2,000
features 11 ยท 5 nominal ยท 3 ordinal ยท 3 continuous
model output mean 174 ยท std 177 ยท range [-48.9, 928]
model Rยฒ 0.947 (on this subsample)
EXPLAINED VARIANCE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
step split on solo ฮRยฒ Rยฒ heter
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
GAM (all features global) โ โ 71.7% โ
+ hr temp, workingday, yr +15.5% +15.5% 87.2% 0.48 โ 0.29
+ hum hr, temp, weathersit +1.8% +1.4% 88.6% 0.17 โ 0.15
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
FINAL 88.6%
REJECTED SPLITS min gain 1.0%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
feature split on solo ฮRยฒ reason
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ temp hr, hum +1.7% +0.9% below threshold
โ yr hr, hum +1.5% -0.1% redundant
โ workingday hr, yr +4.9% -4.3% redundant
โ redundant: it would explain variance on its own (see solo),
but the accepted splits already account for it.
FEATURES ranked, in the selected snapshot
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
feature importance heter #regions
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
hr 0.7314 โโโโโโโโโโโโโโโโโโ 0.2882 4
temp 0.2281 โโโโโโ 0.2668 1
yr 0.1878 โโโโโ 0.2028 1
hum 0.1020 โโโ 0.1525 4
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
the features above carry 80% of the total importance mass
Terminals that mangle box-drawing characters
report.show(ascii=True) draws the same tables in plain ASCII.
The components
Every block above, and every section of the HTML page, has its own in-depth page: how to read it, where its numbers come from, and what to check.
| component | the question it answers |
|---|---|
| The data & model header | what ran, on what data, and how good is the model? |
| The explained variance ledger | how much of the model does the explanation capture? |
| The rejected splits | what was refused, and why? |
| The ranked features | where is the signal, and in which units? |
| The triage plane | where to look first? |
| The regional analysis | how to read a tree and its per leaf plots? |
| The global baseline | what would you have believed without regions? |
| Configuring the report | which knob moves what? |
The HTML page
report.to_html("report.html") # writes the file; returns None
A single self-contained file: every figure inlined as a base64 PNG, no external assets, no CDN. Mail it, commit it, drop it in a PR.
flowchart TD
S1["<b>1 ยท Overview</b><br/>where to look"]
S2["<b>2 ยท Regional analysis</b><br/>the final CALM"]
S3["<b>3 ยท Global baseline</b><br/>without regions"]
S1 --> S2 --> S3| section | what it shows | in depth |
|---|---|---|
| 1 ยท Overview | the ledger bar, the triage plane, the ranked table | ledger ยท triage ยท ranking |
| 2 ยท Regional analysis | the selected snapshot, one subsection per feature | regional analysis |
| 3 ยท Global baseline | what you would have believed without regions | global baseline |
๐ Section 3 exists so the report can be checked, not just trusted. It is the explanation you would have shipped if you had never split anything.
See a real one
This is the page produced by the bike-sharing run above; the very report whose
.show() you just read. It is live: scroll it, click a figure to zoom, collapse
a section.
It is a value
d = report.to_dict() # plain, serializable
again = effector.Report.from_dict(d) # no model, no data needed
again.show() # identical output
Every knob of the pipeline, to_html(share_y=), and the unbound behavior of a
rebuilt report live in configuring the report.
Where to next
- The components: the eight in-depth pages above
- The interactive API: drive the same pipeline yourself
- The input layer: schema, names, types, units
- API docs: the
Reportreference