Canvas: Five good types — classification, detection, and Slutsky decomposition

[yueswater]

Overview

Implement automatic good-type classification for both goods and render the appropriate Slutsky decomposition diagram. The five types are defined by the signs of income and substitution effects, and by income elasticity:

---

Classification taxonomy

Type	$\partial x^{\ast}/\partial I$	Income elasticity $\varepsilon_{x,I}$	$\partial x^{\ast}/\partial p_x$	Substitution effect	Income effect
Normal — Necessity	$> 0$	$0 < \varepsilon < 1$	$< 0$	$< 0$	$< 0$ (reinforces)
Normal — Luxury	$> 0$	$\varepsilon > 1$	$< 0$	$< 0$	$< 0$ (reinforces)
Inferior	$< 0$	$\varepsilon < 0$	$< 0$	$< 0$ (dominates)	$> 0$ (offsets)
Giffen	$< 0$	$\varepsilon < 0$	$> 0$	$< 0$	$> 0$ (dominates)

The Slutsky equation ties them together:

$$\underbrace{\frac{\partial x^{\ast}}{\partial p_x}}_{\text{total effect}} = \underbrace{\frac{\partial h_x}{\partial p_x}}_{\text{substitution (} \leq 0\text{)}} - \underbrace{x^{\ast} \cdot \frac{\partial x^{\ast}}{\partial I}}_{\text{income effect}}$$

---

Proposed features

A. Automatic classifier

from econ_viz.optimizer import classify_good

result = classify_good(model, good="x", px=2, py=3, income=60)
# GoodType.NORMAL_NECESSITY | NORMAL_LUXURY | INFERIOR | GIFFEN

Reports:

• Income elasticity $\varepsilon_{x,I}$
• Sign of total price effect
• Magnitudes of substitution and income effects

B. Slutsky decomposition diagram (three-panel)

For a price change $p_x^0 \to p_x^1$:

1. Panel 1: original optimum $A$ on $U^0$; new budget line; new optimum $C$ on $U^1$
2. Panel 2: compensated budget line (slope $p_x^1/p_y$, tangent to $U^0$); intermediate point $B$; $A \to B$ labelled substitution effect
3. Panel 3: shift from compensated to actual budget; $B \to C$ labelled income effect

Colour coding:

• Normal: substitution and income arrows both point left (demand increases when price falls)
• Inferior: income effect arrow points right, but shorter than substitution
• Giffen: income effect arrow points right and is longer — net demand moves right when price rises

C. ICC slope as luxury/necessity detector

On the Income Consumption Curve, the slope of the ICC in $(x, y)$ space identifies good type:

• ICC slopes upward → both normal
• ICC bends back in $x$ → $x$ is inferior
• ICC bends back in $y$ → $y$ is inferior

Annotate the ICC with the detected type at each segment.

---

Tasks

• GoodType enum: NORMAL_NECESSITY, NORMAL_LUXURY, INFERIOR, GIFFEN
• classify_good(model, good, px, py, income) using comparative_statics (Solver: Comparative statics helper #12)
• Three-panel Slutsky decomposition diagram
• Income/substitution effect arrows with magnitude labels
• ICC slope-based type annotation
• Canonical test models per type (e.g. Stone-Geary for inferior region)
• Documentation with one example per good type

[yueswater]

Cross-link: the decomposition diagram part of this issue is now provided by #55 (Canvas.add_decomposition(...)). This issue stays scoped to the good-type classification layer (classify_good, the four-type taxonomy, and ICC slope-based annotation), which will consume the diagram component from #55.