smoothing#

  • Series: lecture-dp

  • File: lectures/smoothing.md

  • Audit date: 2026-08-26

  • Corpus snapshot: c30490a2f4

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

  • Overall score: 6.0 / 10

  • Priority: HIGH

Score breakdown#

Category

Score

One-line note

Writing

3/10

qe-writing-005 ×6; qe-writing-002 ×5; qe-writing-001 ×2, +4 more.

Math

3/10

qe-math-010 (proposed) ×18; qe-math-002 ×3; qe-math-011 (proposed) ×1, +1 more.

Code

7.5/10

qe-code-001 ×6.

JAX

out of scope

JAX rules target lecture-jax.

Figures

5/10

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

References

10/10

no mechanical violations detected.

Links

7.5/10

qe-link-002 ×6.

Admonitions

N/A

no admonitions, exercises or solutions.

Issues#

Critical#

None found.

High severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 6. Lines: 312, 316, 302, 920, 323, 282. Example: 312-314 indents the continuation of A = np.array([[1., 0., 0.], to 12 spaces against a visual indent of 14 (E128), and 313 has two spaces after the comma in [α,  ρ1, ρ2], (E241) - as does 316, S_y = np.array([[1,  1.0, 0.]]). 302-303 are two consecutive blank lines inside the body of complete_ss, immediately before its return (E303). 920-921 over-indents the continuation of ax[0].plot(...) to 20 spaces where the visual indent is 12 (E127), while the identical construction at 928-929 uses the correct 11 - so the same file does it both ways. 323 passes the simulation length positionally as a literal, complete_ss(β, b0, x0, A, C, S_y, 80), fifteen lines after N_simul = 80 was defined at 308, so the two can drift apart. And 282-285 plus 290 are five lines of commented-out Atilde/Ctilde/S_ytilde scaffolding left inside the function, together with a comment at 279-281 explaining what that dead code was for.

  • [qe-fig-008] — Use lw=2 for line charts. Count: 10. Lines: 330, 331, 338, 339, 919, 920, 922, 927, 928, 930. Example: plot() without lw=.

  • [qe-link-002] — Use doc links for cross-series references. Count: 6. Lines: 87, 121, 126, 263, 362, 793. Example: raw link to python-intro.quantecon.org.

  • [qe-math-002] — Use \top for transpose notation. Count: 3. Lines: 151, 177, 190. Example: apostrophe transpose C'.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 18. Lines: 177, 184, 190, 196, 199, 204, 236, 378, 381, 398, …. Example: missing braces: \mathbb E.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 5. Lines: 158, 413, 487, 606, 364. Example: 158 garbles its own object: ‘we can price claims to consumption at time \(t+1\) consumption that pay off when \(x_{t+1} \in S\)’ - ‘consumption’ twice, the second one stranded. 413-416 spends 41 words saying one thing twice: ‘differ in how thoroughly the market structure allows a consumer to transfer resources across time and Markov states, there being more transfer opportunities in the complete markets setting than in the incomplete markets setting’. 487 is ‘It is timely please to recall that…’, which is not grammatical and is the fourth of four ‘please’ asides in the lecture (187, 263, 349, 487) - a tic that adds no information. 606-607 is a 48-word single sentence whose first eleven words (‘To summarize what we have achieved up to now, we have computed’) are pure throat-clearing. And 364 says ‘In that incomplete markerts setting’.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 6. Lines: 39, 42, 199, 431, 462, 461. Example: the two terms the lecture is built on are bolded in the bullets that mention them and italicised in the paragraphs that define them: complete markets / incomplete markets at 39-40 (a passing reference), then ‘Complete markets allow a consumer to buy and sell claims contingent on all possible states of the world’ at 42 and ‘Incomplete markets allow a consumer to buy and sell a limited set of securities’ at 44 - the actual definitions, in italic. The same inversion recurs: ‘Exogenous means that they are unaffected by the consumer’s decisions’ (431) and ‘so-called natural debt limits that assure that it is feasible for the consumer to repay debts due’ (462) are definitions in italic, while the emphasis at 199 - ‘is the value of time \(t+1\) state-contingent claims’ - is bold. Bold is also used as a label rather than a definition at 461 (**Remark:**). The genuinely correct uses are all italic emphasis (smooth 98, for sure 474, tomorrow’s 519, guess and verify 508) and bold definitions (pricing kernel 146, one-period ahead Arrow securities 426, financial income 458, expenditures 459, implied price 477), so the rule is understood - it is applied inconsistently to the four terms above.

  • [qe-writing-008] — Remove excessive whitespace between words. Count: 52. Lines: 26, 40, 42, 44, 54, 65, 68, 93, 99, 103, …. Example: 2 spaces.

Medium severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 2. Lines: 326, 916. Example: figsize=.

  • [qe-fig-003] — No matplotlib embedded titles. Count: 4. Lines: 329, 337, 918, 926. Example: .set_title.

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

  • [qe-fig-006] — Lowercase axis labels. Count: 4. Lines: 333, 342, 924, 933. Example: axis label Periods.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 4. Lines: 855, 151, 70, 135. Example: the vector arrows at 855-871 are decoration the rest of the lecture does without: \(\vec v\) and \(\vec y\) appear at 855, 858, 863 and 871 for two-element vectors, while every other vector in the file - \(x_t\) (135), \(b(x_{t+1})\) (170), the bmatrix stacks at 537-552 - is a plain letter, and the code calls the same object plain v (731). Second, \,|\, is used as the conditioning bar in about twenty displays (151, 154, 158, 162, 167, 378, 434, 450, 471, 481, 493, 515, 529-530, 569, 588-589) while the plain | appears at 436, 461, 603 and 606 for the same thing - \mid is the one-token form that means it. Third, \(\mathbb R^n\) is braced at 70 (${\mathbb R}^n$) and bare at 165. Fourth, \cr is the line break inside aligned and bmatrix at 135-136, 528-531, 538-552 and 858, while \\ does the job at 388-389 and 847-848; \cr is the deprecated plain-TeX form and mixing the two in one file is gratuitous.

  • [qe-math-011 (proposed)] — Distribution names in plain letters, not \mathcal / \mathbb. Count: 1. Lines: 140. Example: decorated distribution {\cal N}.

  • [qe-writing-001] — Use one sentence per paragraph. Count: 2. Lines: 461, 519. Example: 2 sentences in one paragraph.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 4. Lines: 617, 737, 898, 26. Example: the code for Model 2 arrives 140 lines before Model 2 does. The ### Code cell under ## Model 1 (complete markets) (617-745) defines consumption_incomplete (714-744), whose docstring says ‘Computes endogenous values for the incomplete market case’ and whose body implements {eq}`cs_12` and {eq}`cs_13` - neither of which has been derived yet; ## Model 2 (one-period risk-free debt only) only opens at 759 and derives them at 866-880, then line 900 has to say ‘The code above also contains a function called consumption_incomplete()’. Inside that cell, the comment at 737 reads # Optimal decisions from (12) and (13), hard-coding the rendered numbers of two auto-numbered equations, so it goes stale the moment a display is added above. Then ### The incomplete markets model at 898 sits after ### Summary of outcomes (882) inside the section that is already the incomplete markets model, so the reader meets a heading announcing a model they finished reading about sixteen lines earlier. And line 26 promises a library it never names - ‘this lecture uses the library:’ - where the double space is the hole the word quantecon fell out of.

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

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 2. Lines: 634, 461. Example: the lecture’s whole point is a contrast between two market structures, and the object that creates the contrast - the two-state chain \(P = \begin{bmatrix} .8 & .2 \\ .4 & .6 \end{bmatrix}\) (634-635, written only as a Python default) with Arrow prices \(q(j|i) = \beta P_{ij}\) (471) - is never drawn. A two-node transition diagram with the persistence probabilities on the loops would make ‘debt returns to the initial debt level when the state returns to \(s_0\)’ (614) visible rather than asserted, and it is the one figure the reference example for this rule (kolmogorov_fwd) exists to illustrate. Second, the file contains no admonitions at all, and has two passages that are exactly what admonitions are for: the **Remark:** at 461-463 about natural debt limits (a caveat set off with bold and a colon, three sentences long, ending ‘We shall discuss such debt limits in another lecture’) wants a {note}, and the unanswered rhetorical question at 519, ‘(Why is this is a plausible guess?)’, wants an {exercise} with a {solution}.

Low severity#

None found.

Strengths#

  • The guess-and-verify argument is run as an actual proof and the reader is told where they are in it at every step: the guess is displayed and labelled at 512-517 ({eq}`eq_guess`), the two Markov-state budget constraints it implies are written out at 528-531, the count of equations against unknowns is stated explicitly (‘These are \(2\) equations in the \(3\) unknowns’, 555-556), the missing third equation is supplied by an assumption that is named as an assumption (558-562), and 613 comes back and says ‘We have verified guess {eq}`eq_guess`’.

  • Every one of the eleven labelled equations is cited later - cs_14 at 173, cs_15/cs_16 at 259-261, cs_budget1 at 490, cs_2 at 484 and 497, eq_guess at 521 and 613, cs_4a at 574 and 583, cs_5 at 574 and 594, cs_10 at 813, 816 and 866, cs_12/cs_13 at 900 - so the labels carry the argument rather than decorating it.

  • The Hall interest-rate assumption is translated into each new market structure rather than restated: 54-57 gives it in price terms (‘it costs \(\beta\) of time \(t\) consumption to buy one unit of consumption at time \(t+1\) for sure’), 148-151 gives the continuous-state Arrow counterpart as a pricing kernel, and 471-485 gives the finite-state counterpart \(q(j|i) = \beta P_{ij}\) and then checks it by summing over \(j\) to recover \(\beta\) (480-482).

  • The two figures are set up to be compared rather than merely displayed: both are 1x2 (consumption panel, debt panel), both plot nonfinancial income as the same dashed reference series (331, 339, 922, 930), and the second overlays the complete- and incomplete-markets paths on one axis (919-921, 927-929) so the random walk and the flat line are read against each other directly.

  • The interpretation of each figure is written out as an itemised list of what to look for, not left to the reader - 349-357 for the linear-state-space case (income stationary, consumption constant, debt an affine function of income) and 938-945 for the Markov case (consumption constant vs random walk, debt oscillating vs unit root).

  • consumption_complete (668-711) solves the \(N\)-state problem rather than the two-state one it was derived for, building the augmented system that folds the \(t=0\) constraint {eq}`cs_5` in as an extra row (692-706), and 621-622 says so explicitly (‘for the general case with \(N\) Markov states’).