subjective_beliefs_business_cycles#

  • Series: lecture-python-advanced.myst

  • File: lectures/subjective_beliefs_business_cycles.md

  • Audit date: 2026-08-26

  • Corpus snapshot: b83d6da399

  • 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-004 ×8; qe-writing-005 ×8; qe-writing-002 ×5, +5 more.

Math

3/10

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

Code

7/10

qe-code-002 ×2; qe-code-001 ×2.

JAX

out of scope

JAX rules target lecture-jax.

Figures

7/10

qe-fig-005 ×2; qe-fig-004 ×1; qe-fig-001 ×5.

References

9/10

qe-ref-001 ×1.

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: 5. Lines: 332, 1262, 1470, 1647, 2421. Example: figsize=.

  • [qe-math-002] — Use \top for transpose notation. Count: 40. Lines: 1059, 1093, 1108, 1113, 1116, 1122, 1137, 1158, 1175, 1200, …. Example: apostrophe transpose )'.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 44. Lines: 80, 88, 104, 114, 161, 480, 483, 484, 518, 519, …. Example: bare expectation E_t[.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 5. Lines: 120, 363, 404, 1450, 1497. Example: the “Empirical facts” section (404-427) restates in three bullets what the two preceding figure discussions have just established: 408-409 (“Both wedges are positive on average”) repeats 360 (“Both wedges are positive most of the time”), 411-412 (“countercyclical: they rise during every NBER recession in the sample”) repeats 360-361 (“both rise during the shaded NBER recessions”), and 414-416 (“the first principal component explains about four-fifths of their joint variation”) repeats 387 and 396-402. Line 120-122 is a 37-word sentence whose whole job is to restate 111-118: “Thus the lecture uses one object in two related ways: empirically, a belief wedge is a survey forecast minus a statistical benchmark forecast; in the model, it is a subjective expectation minus an objective expectation.” Line 363 opens with a pronoun that has no antecedent - “It suggests that households persistently overpredict unemployment and inflation” - where the referent is the pair of facts in the previous paragraph. And several paragraphs are split mid-thought, leaving an orphan clause standing as its own paragraph: 1450-1453 (“…act as if bad future states are more likely.” / “Vacancy posting weakens, output falls, unemployment rises, and the two survey wedges jump together.”), 1497-1501, 944-945, 1630-1631 and 2452-2453.

  • [qe-writing-004] — Avoid unnecessary capitalization in narrative text. Count: 8. Lines: 642, 758, 764, 844, 959, 1194, 1215. Example: mid-sentence ‘Step’.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 8. Lines: 29, 48, 432, 706, 1045, 1220, 1789, 2201. Example: the two terms the lecture is named for are the two it italicises: “These biases, called belief wedges” (29) and “a time-varying belief shock” (48), with wedge loadings (432) a third - all definitions, all in italic - while the sentence immediately above 29 puts the finding in bold (“systematic upward biases”, 27). Bold is then used for plain emphasis at 1045 (“with objective law of motion”), 1220 (“driven by the single scalar belief factor”), 1789 (“Under the subjective measure”) and 2256 (“the wedge is negative”), alongside its correct definitional uses (likelihood ratio 488, risk-sensitive 539, Riccati equation 746). Italic also does heading duty in nine places where a heading or a {prf} label would be clearer: Case 1: fixed \(\theta\). (706), Case 2: state-dependent \(\theta_t\). (726), Part 1. / Part 2. / Part 3. (2221, 2249, 2259) and the four exercise titles (2201, 2278, 2332, 2392).

  • [qe-writing-006] — Capitalize lecture titles properly. Count: 1. Lines: 1304. Example: H2 Title Case: ‘A reduced-form emulator of the New Keynesian model’ (New).

Medium severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 2. Lines: 1002, 1834. Example: 1002 builds two f-strings with no placeholders in them, labels_f = [f'subjective, θ = θ_bar', f'subjective, θ = 2θ_bar'], which ruff reports as F541; the f prefixes are inert and the neighbouring list at 903-905 uses a real placeholder in one entry and none in the others, so the distinction is invisible. And compute_tau_wedge_loadings (1834, called at 1881) spells out tau in an identifier in a file that otherwise uses the unicode letter for exactly that index - τ_max is this function’s own parameter (1834), for τ in range(...) its own loop variable (1853), and τ_max, τ_grid, τ appear at 979-987, 998, 1880-1896 - so the name should be compute_τ_wedge_loadings (qe-code-002’s intent, though the detector does not reach inside the identifier; see scanner_doubts).

  • [qe-code-002] — Use Unicode symbols for Greek letters in code. Count: 2. Lines: 1834, 1881. Example: spelled-out tau.

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

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 3. Lines: 1069, 2108, 2150. Example: two matrices are set in blackboard bold, \(\mathbb{M}_{t+1}\) (2104, 2108) and \(\mathbb{D}\) (2121-2164), and 2150-2151 states the reason: “(We write \(\mathbb{D}\) for this matrix to avoid confusion with the expectation operator \(E_t\).)” - so the decoration exists only because the lecture writes expectation as a bare \(E_t\) throughout. Fixing the 38 qe-math-010 (proposed) occurrences to \mathbb{E}_t frees plain \(D\) and removes the stated justification, and it also stops blackboard bold meaning two different things in one file. Second, q now carries five distinct meanings: the answer shares \(q_t^u, q_t^d\) (225-231), the value-function constant \(v_q\) (466, 632), the law-of-motion intercept \(\psi_q\) (1049), the volatility-scaling parameter \(\mathsf{q}\) in a fifth font (1069, 1090, 1970-2012), and q = macro_q in code at 175 - where the perturbation parameter is the one object with no competing claim on a fresh letter. Third, the appendix writes \operatorname{stack} and \mathrm{diag} (2108, 2143) as multi-letter operators inside a display that already has six subscripted \(g\) variants, where naming the rows explicitly would be shorter than the notation that describes them.

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

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 3. Lines: 396, 843, 303. Example: the lecture carries three different specifications of the belief factor and never says which one is in force where. Case 1 fixes \(\theta_t = \theta\) (706-724), Case 2 makes it linear in the state, \(\theta_t = \bar\theta(\bar x + x_t)\) (726-759, restated at 1053-1054 and 2092), and 841-847 introduces a third - an exogenous AR(1) - conceding that it is “a third specification of pessimism, distinct from the fixed \(\theta\) of Case 1 and the state-dependent \(\theta_t\) of Case 2” without reconciling them; 1962-1964 defers the reconciliation to the appendix, which then re-derives Case 2 (2020-2045) and never returns to the AR(1). The code mixes them freely: solve_vx solves the Case-2 Riccati equation in \(\mu_\theta\) (775-799), simulate_θ draws AR(1) paths (850-859), and the exercise at 2297-2301 feeds an AR(1) path straight into the Case-2 wedge formula belief_wedge(m_temp, θ_sim_temp), while the notation table at 464-465 defines \(\bar\theta\) only as “loading of the belief factor on the state”. Separately, five results are hard-coded in prose that a cell in the same lecture computes - “The reported PC1 share of 0.809” at 396 against pc1_share at 296 (which the figure also prints at 381), “from about 0.55 to about 1.39” at 1586-1587 against std_no_θ_scaled/std_full_scaled at 1552-1553, and “0.52 and 1.22” at 437-438 and again as literals in the comments at 1256-1257 against c_u/c_π at 448-449 - so a recalibration silently falsifies the prose. And fred_recession_spans (303-322) fetches a live CSV from fred.stlouisfed.org at build time, parsing a hard-coded column name observation_date, while every other input comes from the pinned data-lectures mirror at 149-153.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 3. Lines: 216, 1591, 1685. Example: “Role of firms’ beliefs” (1591-1621) makes five quantitative claims with no figure and no code - inflation falls on impact, the inflation wedge is too small, wages fall by less, the perceived surplus stays larger, comovement weakens - in a lecture where every other claim gets its own panel, and where the machinery to show it already exists: the irf function (1418-1436) plus a second NKModel with the belief loadings on the inflation row zeroed would produce the comparison in six lines. “Extensions” (1685-1746) likewise reports thirteen numbers in running prose (0.85, 0.56, 1.49, 0.22, 0.20, 0.35, 0.51, 0.83, 0.79, 1.39, 0.77, 0.45, 0.13) where a five-row table indexed by variant would let a reader compare them. And the Carlson-Parkin inversion at 216-258 is the one step in the empirical section a reader is unlikely to have seen before - a normal cross-section of household forecasts cut by thresholds \(\pm a\), with the observed shares as tail masses - and the single figure that would explain it, that density with the two cut points and the three shares shaded, is not drawn.

Low severity#

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

  • [qe-ref-001] — Use correct citation style. Count: 1. Lines: 1745. Example: {cite} in narrative flow: ‘{cite}’.

  • [qe-writing-009 (proposed)] — Write “IID” — not “i.i.d.” or “iid”. Count: 1. Lines: 498. Example: i.i.d…

Strengths#

  • The notation table at 457-468 is placed before any theory and pins down exactly the three-way distinction the rest of the lecture turns on - \(\theta_t\) the belief factor, \(\bar\theta\) its loading on the state, \(\mu_\theta = \bar\theta\bar x\) its steady-state level - along with \(v_x\), \(v_q\), \(\nu_t\) and \(\Delta_t^{(\tau)}\), so the reader never has to reconstruct a symbol from context.

  • The empirical section is reproducible end to end from pinned inputs: the two CSVs come from the data-lectures mirror (149-153), the nine VAR variables are constructed one line each with their FRED series named (176-186), the VAR itself is 18 readable lines (194-213), and the Carlson-Parkin inversion is derived from the two share equations (225-244) before being coded in five lines (253-257), with 246-250 saying where the single free parameter \(a = 1.045\) comes from.

  • The lecture states the gaps between its own numbers and the paper’s rather than papering over them - 396-402 explains why its PC1 share is 0.809 against the paper’s 78.6%, 435-438 says the wedge loadings are set to hit the empirical means instead of being derived, 1237-1244 repeats the warning at the point of use and gives the structural benchmark’s 0.55/0.90 against the data’s 0.52/1.22, and 1329-1331 says outright that the emulator matrices “are not obtained by solving the structural equilibrium conditions”.

  • The certainty-equivalence obstacle is diagnosed by counting orders rather than asserted: 1076-1078 shows the drift \(\nu_t = -\theta_t v_x\sigma_x\) is linear in volatility, 1080-1083 shows the wedge \(-\theta_t v_x \sigma_x^2\) is quadratic (“halve \(\sigma_x\) and the wedge falls by a factor of four”), 1085-1087 says what that costs (“no wedges, no belief shock, and nothing for the survey data to discipline”), and only then does 1089-1096 introduce the joint scaling - which arrives as the forced repair of a demonstrated problem.

  • The one figure whose axis is not what it appears to be is labelled as such three times over: 889-892 explains that the true drift is about \(-0.001\) and invisible, that the plot shifts each density by \(\nu_t/\sigma_x\), and that this magnifies by \(1/\sigma_x = 200\); the caption at 898-899 repeats it; the axis label at 921-924 is the scaled quantity itself; and the cell prints the true and scaled drifts side by side at 930-932.

  • All nine generated figures carry mystnb: figure: caption and a descriptive fig-sbbc-* name (325-331, 366-372, 894-901, 991-997, 1246-1252, 1458-1464, 1538-1544, 1633-1639, 1865-1871), with lowercase axis labels that state units - ‘unemployment wedge (pp)’, ‘forecast horizon \(\tau\) (quarters)’, ‘standard deviation (% or pp, ann.)’.

  • The four exercises are answered by argument, not by output: ex2’s solution derives the AR(1) variance \(\sigma^2/(1-\rho^2)\) to explain the upward slope (2318-2323), and ex4’s explains that \(v_x\) moves only by order \(10^{-5}\) because the quadratic Riccati term carries \(\sigma_x^2\), so the value function differs from its rational counterpart mainly through the constant \(v_q\) (2461-2468).

  • The hump in the multi-period wedge is explained by decomposing it rather than described: 1914-1919 attributes the blue line to the constant-term gap accumulating at the subjective persistence toward \(\tilde\psi_q/(1-\tilde\psi_x)\), and 1924-1934 attributes the red line’s hump to \((\tilde\psi_x^\tau - \psi_x^\tau)x_{1t}\), a difference of two geometric decays that is zero at both ends.