theil_1#

  • Series: lecture-python.myst

  • File: lectures/theil_1.md

  • Audit date: 2026-08-26

  • Corpus snapshot: e25fdf2345

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

  • Overall score: 8.0 / 10

  • Priority: LOW

Score breakdown#

Category

Score

One-line note

Writing

4.5/10

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

Math

6.5/10

qe-math-010 (proposed) ×2; qe-math-009 ×5.

Code

8.5/10

qe-code-001 ×3.

JAX

out of scope

JAX rules target lecture-jax.

Figures

6.5/10

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

References

10/10

no mechanical violations detected.

Links

10/10

no mechanical violations detected.

Admonitions

10/10

no mechanical violations detected.

Issues#

Critical#

None found.

High severity#

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 5. Lines: 145, 255, 277, 184, 103. Example: \(V\) carries two meanings 120 lines apart: 145 defines it as the one-period return function, \(V : S_1 \times S_2 \times U \to \mathbb{R}\), and 149 discounts and sums it, while 262 writes “the additive term in \(V(y) = -y^\top P y - d\)” - the value function. 140 (“recover the return function \(V\)”) makes the first reading explicit, so the second is a straight collision. In the same vein 255 uses \(r\) twice in one display, once as the name of the return function and once as its own control-cost coefficient: \(r(y_t, u_t) = -(q y_t^2 + r u_t^2)\); the code then has to route the lecture’s \(q\) (state cost) into R_mat and its \(r\) (control cost) into Q_mat (277-278) because quantecon.LQ uses the opposite letters, and the comments there are the only thing keeping the reader oriented. 184 and 187 introduce the prescript form \({}_{t+j}z_t^e\) - a prescript, a subscript and a superscript on one letter - for the \(j\)-step forecast, use it twice, and then abandon it for \(\tilde z_t\); \(z^e_{t+j\mid t}\) or \(\mathbb{E}_t z_{t+j}\) would carry the same content. And \(\mathcal{E}\) at 103 and 105 is the only calligraphic set in a lecture whose other spaces are plain (\(S_1\), \(S_2\), \(U\), \(S_1^\infty\)). Fifth - and this is a cross-file break rather than a local one - the code at 277-278 names the state cost R_mat and the control cost Q_mat, matching quantecon.LQ, whose docstring gives the objective as \(x_t' R x_t + u_t' Q u_t\). The companion lecture theil_2 reverses both: its math at line 117 writes \(r(y,u) = -y^\top Q y - u^\top R u\) and its code at lines 150-151 comments Q_mat as “state cost” and R_mat as “control cost”. Each lecture compensates in the call - LQ(Q_mat, R_mat, ...) here at 285, LQ(R_mat, Q_mat, ...) there at 158 - so both compute identical results (I ran both: P = 1.472317, F = 0.524797, d = 27.974028), which is exactly what makes the disagreement invisible to anyone reading one file at a time. The two lectures share a title, a model and this code cell, and neither warns of the swap.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 2. Lines: 149, 154. Example: bare expectation E_0\!\left\{.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 5. Lines: 51, 198, 205, 229, 324. Example: the lecture’s title concept is italicised where it is coined and bolded where it is restated: 51 writes “established a celebrated certainty equivalence (CE) property” and 174 writes “the certainty equivalence theorem” - the rule inverted in both directions on the same term. Bold is then used for pure emphasis four times where the lecture’s own practice elsewhere is italic (identical 60, level/does 62, why 88, reveals nothing 134, quadratic/linear 170, determined 326, flat 306): “the optimal action is a linear function” (198), “depends entirely on preferences \((V)\) and technology \((g)\) but not on the stochastic environment” (205), “as if the agent knew the future path \(z_{t+1}, z_{t+2}, \ldots\) with certainty” (229, an eleven-word clause), and “the deficiency is that the coefficients of the distributed lag are left unrestricted” (324).

Medium severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 3. Lines: 361, 271, 375. Example: 361 writes σ_sq_vals = σ_vals ** 2 with spaces around the exponentiation operator, which the rule singles out as the one operator to write closed up (a**b). 271 renames the math symbol \(b\) of 255 to b_coeff while a, q, r, β and σ all keep their letters, so the one variable that is renamed is renamed away from the notation the rule says to stay close to. And 375-376 wraps float(...) around .item(), which already returns a Python float: P_scalar = float(LQ(Q_mat, R_mat, A, B, C=np.zeros((1, 1)), beta=β).stationary_values()[0].item()). Labels are also quoted two ways - escaped backslashes at 293, 299, 365, 366 ('noise level $\\sigma$') where a raw string would read cleanly.

  • [qe-fig-003] — No matplotlib embedded titles. Count: 2. Lines: 295, 301. Example: .set_title.

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

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 3. Lines: 229, 140, 243. Example: 229 is a 52-word sentence carrying a definition, a re-derivation and a contrast behind one colon and one “i.e.”: “The name “certainty equivalence” reflects a further implication of the LQ structure: the function \(h_1\) can be derived as if the agent knew the future path … – i.e., by solving the deterministic problem in which \(\tilde{z}_t\) is treated as the realized path rather than a forecast”. 140 is 48 words and stacks two citations, a definition and a two-step prescription in one breath. 243 is 47 words with the operative clause parenthesised between two em-dashes (“– i.e., that agents’ forecasts be optimal with respect to the actual law of motion \(f\) –”). 332 is a further 35. The note at 161-162 also runs two sentences without a blank line between them, which is the drafted qe-writing-001 finding.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 3. Lines: 251, 255, 311. Example: 251 announces “The following code verifies the CE principle numerically”, but the model it then builds cannot reach the result the previous 100 lines established. The framework’s content is the split of the decision rule into \(h_1\) (optimization, depends on \(V, g\)) and \(h_2\) (forecasting, depends on \(f, \Phi\)), tabulated at 218-221 and used at 223-225. \(h_2\) exists only if there is an exogenous state to forecast, and the scalar problem at 255, \(y_{t+1} = a y_t + b u_t + \sigma \varepsilon_{t+1}\), has no \(z_t\) at all. So the experiment can exhibit only the weaker claim already made in the Overview at 62 - the gain does not depend on the shock variance, the value constant does - and it never touches \(\tilde z_t\), \(h_1\), \(h_2\), \(S\) or \(T\), which are what the sections it follows are about. The symbol set changes wholesale at the same point: \(z, x, u, f, g, h, V, \Phi\) before 251, and \(y, u, a, b, q, r, \sigma, F, d, P\) after it, with no sentence mapping one onto the other. Second, the code interlude at 251-308 sits between two halves of one argument - 239-249 finishes cross-equation restrictions, 311-332 resumes with the adaptive-expectations critique that depends on \(h_2 = S(f)\) - so the general thread is cut and resumed 60 lines later. Third, 296 sets axes[0].set_ylim(0, 2 * max(F_vals) + 0.1), which is what makes the gain look flat; 306 then reads flatness off the picture. The claim is true and the y-limit is a defensible choice, but nothing in the lecture reports how flat (max(F_vals) - min(F_vals) would settle it in one line), so the reader is asked to trust an axis limit.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 2. Lines: 317, 211. Example: the adaptive-expectations critique (313-332) is the lecture’s sharpest argument and it is made entirely in prose. {eq}`eq:adaptive_expectations_v3` at 317 gives geometrically declining weights \(\lambda(1-\lambda)^i\); 324-328 says the defect is that those weights are “left unrestricted by theory” while the optimal ones are “determined by \(f\)”. One panel - the \(\lambda(1-\lambda)^i\) weights for two values of \(\lambda\) against the optimal forecast weights implied by an AR(1) environment, redrawn for a second \(f\) - would show both halves of that claim at once, including the part the prose can only assert: that the optimal weights move when \(f\) moves and the postulated ones do not. Second, the boxed composite rule at 211, \(h(z_t,x_t) = h_1[h_2(z_t), x_t]\), together with the dependency table at 218-221, is a two-box-and-two-arrow diagram written as algebra; the lecture’s one figure (264-303) is of a different model.

Low severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 1. Lines: 290. Example: figsize=.

  • [qe-fig-004] — Caption formatting conventions. Count: 1. Lines: 264. Example: caption of 7 words.

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

Strengths#

  • The dependency table at 218-221 is the clearest statement of the certainty-equivalence result anywhere in the lecture - two rows, Depends on and Independent of, for \(h_1\) and \(h_2\) - and it is put to work immediately: 223 reads the policy-analysis consequence straight off it (“since \(h_1\) is invariant to \(f\), the policy analyst need only re-solve the forecasting problem”).

  • The lecture is organised as an answer to a quoted question. 76-78 states Hurwicz’s problem verbatim, 84-88 restates it as three conditions, 130-138 shows why an estimated decision rule cannot answer it (“this single estimate, however precise, reveals nothing about how \(T(f)\) varies with \(f\)”), 140 says what would, and 156-158 names the difficulty that remains - so every section has an identifiable job.

  • Citation style is handled correctly and consistently throughout: eleven in-text {cite:t} calls where the author names carry the sentence (51, 66, 68, 76, 90, 140, 170, 174, 248, 313, 330) against a single parenthetical {cite} at 76, (`` {cite}Hurwicz:1962 ``).

  • The critique of adaptive expectations is made precisely rather than dismissively: 322 concedes the point an unsympathetic reader would raise (“The deficiency is not that {eq}`eq:adaptive_expectations_v3` is a distributed lag – linear forecasting rules are perfectly acceptable simplifications”), 324 then locates the actual defect, and 326 names the mapping \(h_2 = S(f)\) that supplies the missing restriction.

  • The numerical check states its prediction before it runs it: 259-262 says what the CE theorem implies for this experiment - the gain \(F\) flat in \(\sigma\), the value constant \(d\) rising with it - and 306-308 reads the two panels back against those two claims, so the figure is a test rather than an illustration.

  • The exercise at 337-353 asks for the sharper version of what the figure showed - not that \(d\) rises but that \(d \propto \sigma^2\) - and the solution then verifies the constant of proportionality against a \(P\) computed from a noiseless problem (375-379), with 384 explaining why substituting \(C = 0\) is legitimate (“\(P\) is determined entirely by preferences and technology, not by the noise level”).