phillips_learning#

  • Series: lecture-python.myst

  • File: lectures/phillips_learning.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.7 / 10

  • Priority: LOW

Score breakdown#

Category

Score

One-line note

Writing

5/10

qe-writing-005 ×2; qe-writing-003 ×3; qe-writing-002 ×4, +2 more.

Math

7.5/10

qe-math-010 (proposed) ×1; qe-math-009 ×7.

Code

8.5/10

qe-code-001 ×4.

JAX

out of scope

JAX rules target lecture-jax.

Figures

6/10

qe-fig-004 ×5; qe-fig-003 ×1; qe-fig-005 ×1, +1 more.

References

7/10

qe-ref-001 ×17.

Links

10/10

no mechanical violations detected.

Admonitions

10/10

no mechanical violations detected.

Issues#

Critical#

None found.

High severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 6. Lines: 606, 633, 669, 701, 736, 813. Example: figsize=.

  • [qe-fig-004] — Caption formatting conventions. Count: 5. Lines: 597, 624, 662, 694, 729. Example: caption of 11 words.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 7. Lines: 361, 356, 345, 310, 313, 537, 563. Example: seven letters carry two meanings each, and in every case one meaning belongs to the primer (71-411) and the other to the model (413 onward), which is exactly where a reader is switching between them. \(\gamma\) is the vector of Phillips-curve coefficients throughout (83, 93, 109, 424, 445, 514) and at 361 it is the gain decay exponent: “\(h(s) = \exp(s)\) when \(\gamma = 1\) in \(a_n = a_0/n^\gamma\)”. \(h\) is the Phelps decision rule \(h(\gamma)\) (98, 434, 464, 514) and at 356 and 361 it is the weight function \(h(s)\) inside the action functional. \(R\) is \(\sum_j \mathbb{E}\,\zeta_t\zeta_{t-j}^\top\) at 345, \(R_{XC}\) the regressor second-moment matrix at 94 and 446, and in the code three more things - R = np.outer(c, c) (517), R2 = model.σC2 a scalar variance (547), R1 a matrix increment (567). \(A\) is the set of admissible escape paths at 310 and the LQ transition matrix at 468 and 520. \(\delta\) is the tolerance in the escape limit at 313 and 318-320 and the discount factor at 468, 486 and 737. \(T\) is the escape horizon in \(S(T,\phi)\) at 308 and the prior sample size at 537 (T_prior). And \(\phi\) is the stacked belief vector \((\gamma, \operatorname{col}(R_{XC}))\) at 109 while the code’s φ at 563 is the regressor vector \(X_{C,t}\) - the two most important symbols of the primer, reused for something else in the implementation. The gain itself has three names in three sections: \(a_n\) (161, 176, 194), \(g_t\) (445, 450, 452), and the forgetting factor \(\lambda\) with g0 = 1 - λ (535, 548).

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 1. Lines: 318. Example: non-blackboard \operatorname{Prob}.

  • [qe-ref-001] — Use correct citation style. Count: 17. Lines: 186, 189, 194, 220, 267, 313, 330, 375, 377, 394, …. Example: {cite} in narrative flow: ‘{cite}’.

Medium severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 4. Lines: 520, 497, 563, 502. Example: 520 and 521 each pack two statements onto one line with a semicolon - A = np.zeros((5, 5)); B = np.zeros((5, 1)) and A[0, :] = c; B[0, 0] = γ0 (E702) - inside the one function where the reader most needs to follow the state-space construction line by line. Three one-line docstrings are written as padded single-double-quote strings rather than triple-quoted: "E[X_C X_C'] at the serially-uncorrelated classical SCE." (497), "Government decision rule ŷ_t = h(γ)·X_{t-1} for belief γ." (515), "Simulate the adaptive system. λ=1 is least squares; λ<1 is constant gain." (541). φ at 563 names the regressor vector \(X_{C,t}\), which is what the lecture’s own comment on that line says, while the mathematics reserves \(\phi\) for the stacked belief vector (109) - the two are different lengths and different objects. Three lines exceed 79 characters (502 at 83, 567 at 82, 571 at 86). Nothing else: Unicode Greek is used throughout, ** is written without spaces, and the class and function names follow PEP8.

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

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 4. Lines: 54, 215, 241, 721. Example: the two bullets that carry the lecture’s thesis are 70 and 55 words: 54 runs “With a decreasing gain that implements least squares, the mean dynamics pull the economy to a self-confirming equilibrium, and we get nothing new: the system is stuck near the Nash outcome” plus its continuation, and 55 similarly. Both would split at their existing colons. Elsewhere: 215-219 is 57 words on the Jacobian and local stability; 721 is 55 words with an em-dash aside and an “except that” clause carrying the section’s whole point; 401-405 is 53 words with a parenthetical list inside it; 388-389 is 54 words across two numbered items; 241 is 52. Fourteen paragraphs in the file run past 42 words. The primer is where they cluster (75, 215, 241, 327, 388, 401), which compounds the problem that 77 already concedes about that section.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 3. Lines: 836, 413, 77. Example: 836 reads “The contrast between Figures 8.1 and 8.2 hinges on the gain”, and those numbers appear nowhere else in the lecture: they are {cite}`Sargent1999`’s figure numbers, the lecture’s own two figures carry mystnb names fig-learn-ls (602) and fig-learn-cgain (629), and {numref} is not used once in the file. So the one cross-reference in the lecture cannot be resolved from inside it. This is a suite-wide convention and it is worth fixing here because it is the same defect as phillips_two_stories, where the book’s numbers are baked into set_title strings and eight prose sentences depend on them: across the eleven Phillips lectures, source-paper figure numbers appear in prose or in embedded titles 21 times (two_stories 12, credible_policies 2, escaping_nash 2, priors 2, self_confirming 2, learning 1) and {numref} is used exactly once in the whole suite, in phillips_drifts_volatilities. Second, the primer builds its entire apparatus on \(\phi\), \(b(\phi)\), \(\phi_f\), \(S(T,\phi)\), \(\tilde\phi(\cdot)\) and \(\partial D\) (104-331), and the model section from 413 onward never uses any of those symbols again - the escape-route figure at 694-711 shows a belief path in terms of “constant” and “sum of weights”, never in terms of \(\tilde\phi\) leaving \(D\), so the theory and the simulation are never joined symbol to symbol. Third, 77 tells the reader the primer can be skipped (“readers who want the punchline can skip to the simulations below and refer back as needed”), which is honest but is also an admission that 340 lines of the lecture are optional; the material that is genuinely needed later - the induction-hypothesis direction of the escape, 365 - is two sentences of it.

  • [qe-writing-004] — Avoid unnecessary capitalization in narrative text. Count: 1. Lines: 770. Example: mid-sentence ‘Critique’.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 2. Lines: 55, 206. Example: twelve of the fourteen bold spans are terms defined on first use and are correct - gain (52), mean dynamics and escape routes (75), artificial time (164), theory of large deviations (251), Legendre transform (278), action functional (286), recursive least squares (439), induction hypothesis (658), anticipated utility (750), Keynesian (793). The two exceptions: 55 bolds new outcomes emerge, which is emphasis on a claim and wants italic (the same bullet already italicises constant and escapes), and 206 bolds mean dynamics a second time having defined it at 75, so a reader cannot tell which of the two is the definition.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 3. Lines: 71, 694, 606. Example: the primer (71-411) runs 340 lines, introduces the two objects that “organize everything that follows” (75), and contains no figure at all - in a section whose own author says at 77 that readers may want to skip it. The picture it is about is a phase portrait: the mean-dynamics flow toward \(\phi_f\), the compact set \(D\) with boundary \(\partial D\), and the least-action path \(\tilde\phi(\cdot)\) leaving through it (301-325). That single sketch would carry {eq}`pl_ode`, {eq}`pl_escapeproblem` and {eq}`pl_escapelim` together, and 327’s “crucial contrast” - that the mean dynamics do not depend on the noise while the escape routes do - is a statement about two arrows in the same diagram. Second, {numref}`fig-learn-belief-path` (694-711) already plots the realised belief path in two dimensions coloured by time, which is the empirical version of that phase portrait; overlaying the mean-dynamics direction at a few points, or simply marking \(\phi_f\) and the induction line as the primer’s \(\partial D\), would join the two halves of the lecture in one figure. Third, the lecture’s central claim is the contrast between least squares and constant gain, and it is delivered as two separate single-panel figures 20 lines apart (606-613 and 633-640) with the same axes but independent y-limits, so the comparison the reader is asked to make is across two differently scaled charts; two stacked panels with sharey=True would make it one glance.

Low severity#

  • [qe-fig-005] — Descriptive figure names for cross-referencing. Count: 1. Lines: 812. Example: code-cell figure without mystnb figure metadata.

Strengths#

  • The lecture states its own thesis as a one-parameter claim in the overview and then delivers exactly that: 52-55 says the answer ‘depends on a single parameter — the gain’, gives the two cases in two bullets, and 589-651 runs the same simulation twice changing only λ=1.0 to λ=0.975, so the comparison is controlled by construction.

  • The primer is labelled as skippable and its purpose is stated up front (73-77), and it does the one thing that makes the escape story more than a curiosity: 380-389 explains that the same recursion is an algorithm when \(\phi_n\) is an iterate and a model when \(\phi_n\) is a belief, which is why a numerical-analysis result about gain sequences becomes an economic result about policy.

  • 327 draws the distinction that a reader would otherwise miss - ‘the mean dynamics do not depend on the noise around them, whereas the escape routes do’ - and 323-325 states what {eq}`pl_escapelim` means in words, that conditional on escaping, the system leaves near the terminal point of the least-action path, so the escapes ‘seem purposeful’ without any large shock.

  • The mechanism is not merely asserted but located in the data the simulation produces: 654-690 plots inflation against the sum of weights on lagged inflation, 688 notes that every stabilization coincides with that sum moving from \(-1\) toward zero, and {numref}`fig-learn-belief-path` (694-711) then shows the same thing as a path in belief space coloured by time.

  • Four {note} admonitions carry the intellectual history without interrupting the argument - stochastic approximation back to {cite}`RobbinsMonro1951` and {cite}`KieferWolfowitz1952` (178-190), the large-deviation foundations (329-331), the published analytic treatment in {cite}`ChoWilliamsSargent2002` and what it proves (367-378), and the learning-literature history (391-411).

  • The concluding section turns the model into a falsifiable statement and hands it to the next lecture: 774-778 says ‘it is worth recording what the model predicts before anyone looks’, states the prediction (drifting coefficients, not merely drifting shock variances), and points at {doc}`phillips_drifts_volatilities` ‘including one prediction of the escape mechanism that the data decline to confirm’ - and that lecture does report exactly that failure at its lines 1902-1904 and 3272-3278, so the cross-reference is accurate in both directions.

  • Both exercises change one thing and explain the result mechanically rather than descriptively: pl_ex1 varies the gain and prints the near-Ramsey fraction in the legend itself (812-824), and pl_ex2 varies the prior tightness and 857-861 explains the outcome through the effective gain \(1/(T+t)\) and the marginal stability of the self-confirming equilibrium.

  • AdaptivePhillips._sce_moments (496-512) builds \(\mathbb{E}[X_C X_C^\top]\) from a regressor list of (lag, variable) pairs and a moment dictionary rather than by writing out 36 entries, so the moment matrix can be checked against the model rather than trusted.