pricing_information#

  • Series: lecture-python.myst

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

  • Priority: LOW

Score breakdown#

Category

Score

One-line note

Writing

5.5/10

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

Math

4.5/10

qe-math-010 (proposed) ×6; qe-math-003 ×1; qe-math-014 (proposed) ×4, +1 more.

Code

5/10

qe-code-002 ×82; qe-code-001 ×5.

JAX

out of scope

JAX rules target lecture-jax.

Figures

6/10

qe-fig-003 ×3; qe-fig-004 ×3; qe-fig-005 ×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-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 5. Lines: 953, 946, 424, 486, 1081. Example: 953 writes title='revenue is linear in $\pi_2$, so the optimum is at an endpoint' in a plain string, so \p is an invalid escape sequence - flake8 reports it as W605 and CPython raises a SyntaxWarning on compile, which I confirmed by compiling the extracted cells with warnings enabled. Every other LaTeX-bearing string in the lecture is either raw (r'$\theta$' at 247, 329, 497) or double-escaped ('...$\\theta^H$' at 486-487), so this one line is the exception, and it is inside an exercise solution where a warning will surface in the built page. Nineteen lines exceed 79 characters, the worst being 963 at 90, 486 at 88, and 487 and 489 at 86. 946 writes 1/3 inside a list with no spaces around the division (E226) where the neighbouring literals are plain floats. On naming, two_type_revenue(pi1, pi2, tL, tH, gamma) at 423 uses tL/tH for the two types \(\theta^L,\theta^H\) while t_low/t_high in the same function body (427-428) are prices - and the lecture’s own notation makes \(t\) the price (358, 364), so the parameter names contradict the mathematics they implement. 1081 packs five initialisations onto one line, n_pairs, n_garble, n_unranked, n_disagree, violations = 4000, 0, 0, 0, 0.

  • [qe-code-002] — Use Unicode symbols for Greek letters in code. Count: 82. Lines: 181, 183, 184, 185, 186, 200, 202, 203, 204, 238, …. Example: spelled-out theta.

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 5. Lines: 90, 240, 484, 751, 814. Example: style override.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 6. Lines: 115, 160, 364, 374, 411. Example: non-blackboard \Pr.

Medium severity#

  • [qe-fig-003] — No matplotlib embedded titles. Count: 3. Lines: 248, 497, 755. Example: .suptitle.

  • [qe-fig-004] — Caption formatting conventions. Count: 3. Lines: 314, 477, 805. Example: caption of 8 words.

  • [qe-math-003] — Use square brackets for matrix notation. Count: 1. Lines: 155. Example: pmatrix environment.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 3. Lines: 174, 364, 126. Example: \(V\) carries three different meanings distinguished only by how many arguments it takes, and two of them appear on one line. 174 defines \(V(E, \theta)\) as the buyer’s gross net-of-reservation value; 567 defines \(V(q, \theta)\) for the same quantity reparameterised by the scalar \(q\), so the first argument silently changes type from a \(2\times 2\) matrix to a real number; and 364 defines \(V(\theta) = V(E(\theta), \theta) - t(\theta)\) as the buyer’s rent, a different quantity - after which 374 writes V(\theta) \geq V(E(\theta'), \theta) - t(\theta'), using the rent and the gross value in the same inequality with the same letter. A separate letter for the rent (the paper’s \(u(\theta)\) or a \(W\)) would remove the whole ambiguity. \(u\) is likewise overloaded three ways: \(u(\omega_i, a_j)\) the payoff function of state and action (103), \(u_1, u_2\) the two scalar payoffs (106), and \(u(\theta)\) the buyer’s reservation utility (126) - so \(u\) of one argument and \(u\) of two arguments are unrelated functions. Minor by comparison, 776 writes \text{Beta}(8, 30) where qe-math-011 (proposed) asks for \mathrm{Beta}.

  • [qe-math-014 (proposed)] (reviewer) — Braces {…} for events, parentheses (…) for sets. Count: 4. Lines: 115, 160, 411. Example: every probability in the lecture is an event written with square brackets: \Pr[\omega = \omega_1] at 115, \Pr[s_1 \mid \omega_1] and \Pr[s_2 \mid \omega_2] at 160, and \Pr[\theta = \theta^H] at 411. All four arguments are logical conditions on random variables - two equalities and two conditional events - which is exactly the case the rule reserves braces for, so each should read \mathbb{P}\{\omega = \omega_1\} and so on. The lecture has no set-valued argument anywhere, so there is no site where parentheses would be right, and the fix is uniform. This is separate from the operator itself: qe-math-010 (proposed) already counts the four \Pr spellings that should be \mathbb{P}, and 3 of its 6 hits at 115, 160 and 411 are these same lines - the delimiter shape is the part a program cannot decide.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 3. Lines: 894, 396, 306. Example: the prose is otherwise tight - the longest paragraph in the lecture is 52 words - but one claim is made four times in nearly the same words: 59-60 “degrading information is not simply a matter of adding noise”, 396-397 “Optimal degradation never adds unbiased noise everywhere; it leaves one state perfectly detectable and blurs the other”, 851-853 “The partial experiment is not a noisier version of the same product; it is a differently positioned one”, and 868-870 “optimal degradation of information is structured rather than random: every experiment on the menu keeps one state perfectly detectable and blurs the other”. The horizontal/vertical distinction is likewise explained three times at 65-70, 306-312 and 341-354. And 894-899 is a single 52-word sentence carrying three {doc} cross-references and three separate reasons to follow them, where three short sentences would read better.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 3. Lines: 238, 754, 795. Example: three breaks, in rising order of consequence. (1) 754 labels a horizontal line $\lambda^* = 1/2$ in the left panel of {numref}`fig-pi-uniform`, and \(\lambda^*\) is never defined anywhere in the lecture: 679 mentions “the multiplier on {eq}`eq:pi_integral`” without naming it, and no equation or sentence gives it a symbol or the value \(1/2\), so the reader meets a Lagrange multiplier for the first time as an unexplained line on a chart. (2) 795-797 says the two-item menu is “in line with {prf:ref}`pi_prop_structure` and with the result that an optimal menu never contains more than two”, but {prf:ref}`pi_prop_structure` (382-391) states three properties - full information is offered, experiments are nondispersed, experiments are concentrated - and says nothing about a bound on the number of items; the two-item claim belongs to the Corollary 1 result quoted at 770-771, so the cross-reference points at the wrong proposition. (3) The global theta = np.linspace(0, 1, 1001) is created at 238 inside a figure cell, and five later analysis cells depend on it (321, 336-338, 592, and the value_q(q, theta) call at 592), so reordering or deleting a plotting cell breaks the computation - and the same name is the parameter of value (181), value_obedient (200) and value_q (577), where it means a scalar type rather than a grid.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 4. Lines: 255, 258, 262, 795. Example: bold is used well for definitions - matching (99), type (112), fully informative (165), net value of information (170), garbling (270), nondispersed and concentrated (388-389), congruent (413), differential informativeness (561), ironing (669), and the vertical/horizontal pair (65-66) - which makes the four emphasis uses stand out as inconsistent: 255 piecewise linear, 258 highest at \(\theta^*\), 262 nothing at all and 795 two are all emphasis on a claim, not terms being defined, and italic is what the rule asks for. 625 then bolds concave and piecewise linear for the same property that 255 bolded, so the reader cannot tell whether the bold at 255 was defining a term or stressing a fact.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 3. Lines: 65, 388, 527. Example: the lecture’s central idea is geometric and is never drawn. 65-70, 306-312 and 341-354 argue that information has a vertical dimension (quality) and a horizontal one (position), and that the seller lives in the region Blackwell’s order leaves unranked - and all of that is a picture of the unit square in \((\pi_1, \pi_2)\) with, for one chosen \(E\), the set of experiments it garbles shaded. The code to draw it already exists: experiment (281) and garbling (285) are exactly the two functions needed, and pi_ex3 (1077-1112) already samples 4,000 random pairs and counts how many are unranked - it reports the fraction as a printed number where the same loop would draw the region. Second, {prf:ref}`pi_prop_structure` parts 2 and 3 (388-390) say every menu item satisfies \(\pi_1 = 1\) or \(\pi_2 = 1\), i.e. lies on two edges of that same square; 393-397 explains this in words and no figure shows it, although it is the structural result the whole lecture confirms. Third, the two-type switch at \(\gamma = \theta^L/\theta^H\) is delivered as a five-row printed table (527-535) plus a sentence at 541; revenue plotted against \(\gamma\) for the three candidate menus, with the crossing marked, would show why the switch happens where it does.

Low severity#

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

Strengths#

  • Every analytic result the lecture quotes from {cite:t}`BergemannBonattiSmolin2018` is checked numerically against a brute-force alternative, and the check is shown rather than asserted: the closed form {eq}`eq:pi_optimal2type` against a \(301\times301\) grid search over all experiments (512-536), the uniform-type menu against the paper’s \([1/4, 3/4]\) interval and price of \(1/4\) (738-739), and the two-expression equivalence at 207-208 against a 51-by-51 sweep that reports the largest gap on each side of the normalization (210-223).

  • Solving the continuum problem as a linear program (623-665) is the lecture’s best pedagogical choice and it says why: 667-682 explains that the LP’s monotonicity constraint does the work of Myerson’s ironing, spells out what the manual alternative would require (form the virtual values, take derivatives of convex hulls of their integrals, find the multiplier), and attributes it to {cite:t}`Myerson1981` and {cite:t}`Toikka2011` - so the shortcut is presented as a substitute for something the reader can see the shape of.

  • The {note} at 137-146 turns the model’s least intuitive convention into the reader’s intuition: it explains where the interim belief \(\theta\) comes from, points at {doc}`likelihood_bayes` for the mechanism, and then states the consequence in one sentence - “So ‘high type’ in this lecture means badly informed, and it is the badly informed buyer who is willing to pay the most”.

  • Blackwell’s order is shown to be partial by exhibiting the failure rather than describing it: 295-301 tests five specific pairs and prints yes/no for each, 309 names the incomparable pair, and {numref}`fig-pi-blackwell` (314-333) plots the two value functions with the crossing shaded in both directions and prints four types’ preferences underneath.

  • menu_items (688-710) documents the one numerical judgment the results depend on - that values of \(q\) taken on a negligible set of types are grid artifacts rather than menu items - in its own docstring, and makes both thresholds arguments (tol=1e-4, min_width=0.01) rather than magic numbers buried in the body.

  • The three exercises each extend the lecture instead of rehearsing it: pi_ex1 (903-933) works the congruent case the body skipped and asks why the answer is extremal there and interior in the noncongruent case; pi_ex2 (992-1011) tests Corollary 1’s claim that uniform types need one item whatever the payoffs, over four asymmetric pairs with an assert on the result (1029); pi_ex3 (1047-1069) verifies Blackwell’s theorem itself on 4,000 random pairs and measures how often the order is silent.

  • The closing section (855-899) places the paper against three neighbours and says what differs in each - {cite:t}`AdmatiPfleiderer1986` where the seller creates the heterogeneity rather than screening on it (878-884), {cite:t}`BergemannBonatti2015` on the buyer’s side of the same market, and {cite:t}`KamenicaGentzkow2011` where the sender has no transfers and cares about the action - and 866-874 states the two lessons that survive outside the model.