perm_income#

  • Series: lecture-python.myst

  • File: lectures/perm_income.md

  • Audit date: 2026-08-26

  • Corpus snapshot: e25fdf2345

  • Categories audited: writing, math, code, figures, references, links, admonitions (JAX out of scope)

  • Overall score: 7.0 / 10

  • Priority: HIGH

Score breakdown#

Category

Score

One-line note

Writing

3/10

qe-writing-006 ×15; qe-writing-005 ×10; qe-writing-003 ×5, +4 more.

Math

4/10

qe-math-002 ×8; qe-math-010 (proposed) ×3; qe-math-009 ×3.

Code

7.5/10

qe-code-001 ×6.

JAX

out of scope

JAX rules target lecture-jax.

Figures

6/10

qe-fig-005 ×3; qe-fig-003 ×1; qe-fig-006 ×1, +2 more.

References

8.5/10

qe-ref-001 ×3.

Links

10/10

no mechanical violations detected.

Admonitions

10/10

no mechanical violations detected.

Issues#

Critical#

None found.

High severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 6. Lines: 492, 499, 514, 517, 837, 843. Example: 492 is rng = np.random.default_rng() with no seed, and it is the only generator in the lecture, so both figures (495-504 and 512-523) are different on every build - which matters because 507 makes a claim about the drawn path (“Observe that consumption is considerably smoother than income”). 517 compounds it with a second, separately unseeded source: rcolor = random.choice(('c', 'g', 'b', 'k')) from the stdlib random imported at 52, so the 250 path colours are random, carry no information, and change every build. 514 binds b_sum = np.zeros(T+1) and never uses it, and the loop at 515-518 unpacks w and b it does not use. 499 has a space after the opening parenthesis, ax.plot( b, 'b-', label="Debt") (E201). 837 draws the impulse marker at (S, S) with S = 5 labelled “# Impulse date” at 807, but the shock is placed at index S+1 (818, 820) and the jump in c therefore occurs at period 6, so the vertical line sits one period before the response it marks. 843 calls plt.tight_layout() where the two sibling figures (504, 523) do not, and 838 sets grid(alpha=0.5) where 501 and 520 call grid() bare - three figures, three conventions.

  • [qe-fig-008] — Use lw=2 for line charts. Count: 5. Lines: 497, 498, 499, 835, 836. Example: plot() without lw=.

  • [qe-math-002] — Use \top for transpose notation. Count: 8. Lines: 158, 394, 406, 417, 624, 670. Example: apostrophe transpose A'.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 3. Lines: 664, 897. Example: non-blackboard \mathrm{Var}.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 5. Lines: 396, 811, 849, 936, 998. Example: 849 contradicts itself: “In contrast, notice how most of a transitory income shock is saved and only a small amount is saved” - the second clause must read “consumed”, as 785-787 and 797 both explain. 998, footnote f2, states the standard assumptions as “\(u'(c) >0, u''(c)<0, u'''(c) > 0\)” and two sentences later argues from “the fact that \(u''' <0\)”; Jensen’s inequality gives \(\mathbb{E}_t[u'(c_{t+1})] > u'(\mathbb{E}_t[c_{t+1}])\) when \(u'\) is convex, i.e. when \(u''' > 0\), so the sign in the second mention is wrong and it is the step the whole footnote turns on. 936 reads “Application of formula to this example shows that” with the reference missing - 789 has the same sentence complete (“Application of the formula for debt in {eq}`pi_ssr`”). 811 defines a second function also called time_path, with an incompatible signature (time_path(T, permanent=False) against time_path(T, rng) at 482), silently shadowing the first for the rest of the notebook. And 396-419 introduces three labelled moment recursions, {eq}`lss_mut_perm_income`, {eq}`eqsigmalaw` and {eq}`eqymoments`, that are never computed and never referred to again - part of a wider pattern in which nine labelled equations have no citation anywhere in the file: pi_cpa (301), pi_stsp (386), those three, pi_crw (644), sprob12 (718), sprob13 (726) and consexample1b (939).

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 10. Lines: 77, 97, 176, 196, 244, 264, 554, 634, 857, 923. Example: the same term is set both ways six lines apart: economic income in italic at 264 (“These last two equations assert that consumption equals economic income”) and economic income in bold at 270, inside the very list the italic sentence introduces. The bold marker is otherwise used correctly for nine definitions - random walk (91), the five wealth concepts (266-270), cointegrating vector (622), present value of the moving average coefficients (731), fundamental (1006) - while ten more definitions arrive in italic: information set (77), random walks (89), innovation (97), no Ponzi scheme (176), Euler equations (196), law of iterated expectations (244), innovation to the expected present value (554), cointegrating residual (634), innovation representation (857) and permanent (923). The italics that are doing emphasis are correct (necessary 209, is 610, state 40 and 276, exogenous/endogenous 280-281), so the file is running two conventions at once rather than misunderstanding one.

  • [qe-writing-006] — Capitalize lecture titles properly. Count: 15. Lines: 56, 107, 186, 217, 274, 331, 421, 526, 531, 636, …. Example: H2 Title Case: ‘The Savings Problem’ (Savings, Problem).

  • [qe-writing-008] — Remove excessive whitespace between words. Count: 29. Lines: 45, 69, 76, 91, 173, 196, 223, 269, 271, 383, …. Example: 2 spaces.

Medium severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 3. Lines: 495, 512, 827. Example: figsize=.

  • [qe-fig-003] — No matplotlib embedded titles. Count: 1. Lines: 834. Example: .set_title.

  • [qe-fig-005] — Descriptive figure names for cross-referencing. Count: 3. Lines: 474, 511, 804. Example: code-cell figure without mystnb figure metadata.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 3. Lines: 234, 259, 897. Example: the file mixes plain TeX \over with LaTeX \frac for the same two quantities: {r \over 1+r} at 259 and 304 against \frac{r}{1+r} at 269, and {1 \over 1-\beta} at 561 and 585 against \frac{c_t}{1-\beta} at 249. 234 writes the limit condition as \(\lim_{t \to \infty} \beta^{\frac{t}{2}} b_{t+1} = 0\), putting a \frac inside an exponent where \(\beta^{t/2}\) is both standard and legible at that size. 897 writes the innovation as \(a_t := y_t - E [ y_t \,|\, y_{t-1}, \ldots, y_0]\) - a bare E in a lecture that uses \mathbb{E} in all 30 other places, and \,|\, hand-spacing where \mid does the job (the same hand-spacing appears at 76).

  • [qe-ref-001] — Use correct citation style. Count: 3. Lines: 859, 899. Example: {cite} in narrative flow: ‘of {cite}’.

  • [qe-writing-001] — Use one sentence per paragraph. Count: 4. Lines: 173, 222, 998, 1006. Example: 2 sentences in one paragraph.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 4. Lines: 173, 214, 325, 951. Example: 173 is a two-sentence {note} whose second sentence takes 33 words to say that the parameters can be chosen to make negative consumption unlikely. Three forward promises are made and never anchored: “These ideas will be clarified below” (214), “We do this later” (223), “(Later examples will investigate more realistic income streams.)” (425) - none names a section or uses a {ref}, and the lecture has labels available (odr_pi, coint_pi, sub_classic_consumption). 325-327 hedges rather than explains: “To get from the second last to the last expression in this chain of equalities is not trivial. A key is to use the fact that…” - “a key” rather than the step. And 162 (“discounted geometric sums of some quadratic forms to be described below”) and 951 (“it doesn’t capture important aspects of some consumption/savings data”) both gesture at unnamed objects where naming them costs nothing.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 3. Lines: 509, 599, 853. Example: the lecture already draws 250 independent consumption paths (511-523) and then, 130 lines later, derives \(\mathrm{Var}[c_t] = \mathrm{Var}[c_0] + t\,\hat\sigma^2\) (661-671) and says “the variance of \(c_t\) increases over time at a rate proportional to \(t\)” (679) - without measuring the spread of the fan it has in hand. A \(\pm\sqrt{t}\,\hat\sigma\) envelope on that figure, or the realised cross-sectional variance plotted against the predicted line, would test {eq}`pi_vt` with the simulation already written. Second, cointegration is one of the four things the overview promises (41) and the section that delivers it (599-635) produces the cointegrating vector \([(1-\beta)\ \ 1]\) and the residual \((1-\beta)b_t + c_t\) entirely in algebra; time_path at 482 already returns b and c, so one panel showing \(b_t\) and \(c_t\) wandering while \((1-\beta)b_t + c_t\) stays flat is the picture the argument is asking for. Third, “Two Classic Examples” (734) gives Example 1 a two-panel impulse-response figure (804-845) and Example 2 (853-944) nothing at all - no code, no figure - even though its content is a one-parameter family in the Kalman gain \(K\) and 899-901 and 928 make quantitative claims about how the response varies with \(K\) that a single plot over \(K \in [0,1]\) would show.

Low severity#

  • [qe-fig-006] — Lowercase axis labels. Count: 1. Lines: 502. Example: axis label Time.

Strengths#

  • The martingale groundwork at 66-105 is laid before it is needed and drawn tightly: the definition, the conditional-expectation operator \(\mathbb{E}_t := \mathbb{E}[\cdot \mid \mathcal{F}_t]\) with the information set explained as “a collection of random variables that the modeler declares to be visible at \(t\)”, the distinction between martingales and random walks, and then a link to Wald’s martingale at 105 as an explicit counterexample to the converse.

  • The lecture delivers on its own promise of “alternative formulations of the state” (40) with three, and says what changes at each step: \((b_t, z_t)\) at 276-286, then Hall’s \((c_t, z_t)\) at 591-597 with the reason spelled out - “Debt \(b_t\) has disappeared as a component of the state because it is encoded in \(c_t\)” - then the moving-average form at 692-731 in which the state is the shock history.

  • 234-262 states its three ingredients as a numbered list before combining them (the Euler equation {eq}`sprob5`, the budget constraint {eq}`sprob2`, the no-Ponzi bound {eq}`sprob3`), derives the consumption function, and 264-272 then reads the result out as an accounting identity naming all five concepts - financial wealth, non-financial wealth, total wealth, the marginal propensity to consume, economic income - with the last given two equivalent readings.

  • 310-327 shows the algebra eliminating \(c_t\) from the budget constraint in four displayed steps and then flags the one that is hard, naming the two facts needed (\((1+r)\beta = 1\) and \((I - \beta A)^{-1} = \sum_j \beta^j A^j\)) rather than leaving a silent gap or hiding the step.

  • The IID example (421-472) is stripped down until the answer is readable: \(A\), \(U\), \(C\) chosen so that \(b_t = -\sigma \sum_{j=1}^{t-1} w_j\) and \(c_t = \mu + (1-\beta)\sigma\sum_{j=1}^{t} w_j\) in closed form, and 470 then gives the interpretation that makes it memorable - “assets are just the cumulative sum of unanticipated incomes prior to the present date”.

  • Example 1’s impulse responses (804-851) are built for comparison: both panels share the limit L = 0.175, both carry the impulse marker, and 847-851 reads three separate features off the picture - no change in assets after a permanent shock, most of a transitory shock saved, and the box shape as the visible signature of the random-walk property.

  • Footnote f2 at 998 does real work rather than pointing at a reference: it shows that linear marginal utility is not a convenience but the condition for {eq}`sprob5`, and follows the standard alternative through to its consequence - consumption becomes a submartingale and diverges, and so do savings.

  • The Euler equation is asserted at 190-194 with a forward link (199) to an appendix that then proves it for the two-period case in full (957-996), including where \(\beta R = 1\) enters - so the one step the reader is asked to accept is available on demand rather than deferred to another lecture.

  • Every claim about the permanent and transitory components is given twice, once as a difference equation and once in words: {eq}`consexample1` against 780-787, {eq}`consexample1a` against 797, {eq}`incomemaar` against 921-930 with the fractions \(K\), \((1-\beta)(1-K)\) and \(\beta(1-K)\) each accounted for.