organization_capital#

  • Series: lecture-python.myst

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

  • Priority: LOW

Score breakdown#

Category

Score

One-line note

Writing

4.5/10

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

Math

7/10

qe-math-010 (proposed) ×4; qe-math-009 ×4.

Code

8.5/10

qe-code-001 ×4.

JAX

out of scope

JAX rules target lecture-jax.

Figures

9/10

qe-fig-001 ×10.

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-fig-001] — Do not set figure size unless necessary. Count: 10. Lines: 208, 280, 362, 390, 483, 560, 604, 691, 769, 862. Example: figsize=.

  • [qe-math-010 (proposed)] — Blackboard \mathbb{P}, \mathbb{E}, \mathbb{V} with braces. Count: 4. Lines: 243, 258. Example: bare expectation E\{.

Medium severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 4. Lines: 284, 466, 880, 563. Example: 284 and 773 rebind module-level names as loop variables inside figure cells: for π in [0.5, 1.0, 2.0, 5.0] leaves π = 5.0 in the notebook namespace, and for α in [0.5, 0.7, 1.0, 1.5] leaves α = 1.5. That is why 392 and 556 have to re-declare π = 1.0; a reader running cells out of order gets silently wrong numbers, and ρ is likewise set at 349 and again at 481. 466-476 declares a parameter it never uses - simulate_firm_growth(T, γ, ρ, q0, seed=42) has no ρ in its body, and callers at 488 and 498 pass it. 880-881 adds ax.axvline(γ, ..., label=r'$\gamma$') after ax.legend() at 879, so that label never reaches the legend. And two variables are computed and discarded: misassignment_rates is accumulated at 563 and 567 and never used - the following cell rebuilds the identical list as mis_rates at 607-610 - and mis at 580 is assigned and never read (F841). Smaller items: the continuation indents at 487 and 497 are off by one from the opening bracket (E128), and 488-489 and 498-499 recompute the same three paths for the two panels.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 4. Lines: 253, 105, 243, 320. Example: \(\pi\) is the prior precision and the circle constant, four lines apart. 105 defines it: “The population distribution of \(\theta\) is normal with mean zero and precision (inverse of variance) \(\pi\)”, and 108 writes \(\theta \sim N(0, 1/\pi)\); {eq}`eq:cost_n` at 250 uses that reading, \(c(n) = c - 0.7978\,n/(\pi(\pi+n))\). Then 253 writes \(0.7978 = 2\int_0^\infty \frac{t}{\sqrt{2\pi}} e^{-t^2/2}\,dt\) and 256 writes \(0.7978 \approx \sqrt{2/\pi}\) - both of which are the constant \(3.14159\ldots\) (I checked: \(\sqrt{2/\pi} = 0.7979\), and the integral evaluates to the same). The code inherits the collision: π is the precision at 194, 284, 392, 556, 694 and np.sqrt(π) at 538 and 677 is the precision, so a reader who substitutes the wrong reading anywhere in this stretch gets a wrong number and no diagnostic. Renaming the precision \(h_0\) - the lecture already uses \(h\) for posterior precision at 166 - would fix it. Second, the conditional expectation is written two ways in fifteen lines: E\{\theta \mid m > 0\} with braces in {eq}`eq:unit_cost` (243) and E[\theta \mid m > 0] with brackets in the note at 258, for literally the same quantity. Third, \(h\) is the posterior precision at 166 and 658 and the human-capital increment in the axis label at 779 ($\Delta h$). And {eq}`eq:cutoff` at 323 and {eq}`eq:n_gamma` at 329 carry a \(\varphi_1 + 2\varphi\) term that 123 has already set to \(1\), so the denominator of 323 and the \(-\log(\varphi_1 + 2\varphi)\) of 329 are identically zero-valued decoration - the code at 344 computes np.log(φ1 + 2 * φ) = log(1) = 0 every time.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 3. Lines: 82, 418, 895. Example: 82-85 compresses a counterfactual to the point of obscurity: “without a cost penalty to rapid growth, the first firm to discover a previously untapped market would preempt competition by usurping all profitable investments as they appear, thus implying monopoly more prevalent than it is” - 38 words, and the closing clause has to be unpacked as “implying that monopoly would be more prevalent than it is”. 418-421 is 38 words with the comparison (\(\underline k\) a vector rather than a scalar) arriving after two subordinate clauses. And 895-897 closes the lecture on a 36-word sentence whose payload, “less costly than in possible alternative institutions”, is three hedges deep.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 4. Lines: 752, 445, 243, 480. Example: the section named “Concave transformation frontier” (752) plots frontiers that are not concave. transformation_frontier (761-766) returns \((1 - q^\alpha)^{1/\alpha}\), i.e. the curve \(q^\alpha + h^\alpha = 1\), which is concave only for \(\alpha > 1\). Evaluating at the midpoint \(q = 0.5\) against the chord value \(0.5\): \(\alpha = 0.5\) gives \(0.086\), \(\alpha = 0.7\) gives \(0.255\), \(\alpha = 1.0\) gives \(0.500\), \(\alpha = 1.5\) gives \(0.748\). So of the four curves drawn at 773, two are convex, one is linear, and only \(\alpha = 1.5\) is concave - and the function’s default is \(\alpha = 0.7\), the convex case. The prose then reads concavity off the picture (788-790: “moving from an extremely unbalanced bundle of production and learning activity to a more balanced bundle entails little sacrifice”), which is true of the \(\alpha = 1.5\) curve and exactly false of the two convex ones; and 746-750 needs concavity for the technology set to be “a closed convex cone”. Second, {eq}`eq:surplus` at 445 cannot be read: \(a_{i2t}\), \(a_{i3t}\), \(b\), \(w\) and \(c(i)\) all appear (448-449 refers to summing the first three) and none of the five is ever defined, the cost function is \(c(n)\) everywhere else, and the trailing \sum_i (A_{i2t} + A_{i3t}) c(i) / \sum_i (A_{i2t} + A_{i3t}) leaves the scope of the / to the reader where a \frac{}{} would settle it. The equation is labelled and never cited. Third, \(c_1\), \(c_2\) and \(c_3\) appear for the first time inside {eq}`eq:unit_cost` (243) with no introduction; 253 then says “where \(c = c_1 + c_2 + c_3\)” without saying what any of the three is. Fourth, the industry section is about the equilibrium growth rate, and 480 hard-codes γ_eq = 0.05 - the object the section exists to determine is never determined, and \(c(n(\gamma))\) from 396, which is the input a determination would need, is not used again.

  • [qe-writing-004] — Avoid unnecessary capitalization in narrative text. Count: 3. Lines: 428, 513, 886. Example: mid-sentence ‘Law’.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 4. Lines: 513, 38, 371, 893. Example: “Gibrat’s Law” is styled four ways: plain at 33 (“(Gibrat’s Law)”) and 428 (“this is Gibrat’s Law”), bold at 513 (“This is Gibrat’s Law”), and italic at 838 (“Gibrat’s Law — growth rates independent of firm size”). The lecture’s own title term goes the same way: organization capital in bold where it is defined at 21, then organization capital in italic at 893. The three examples are italicised as they are named at 38-40 (Personnel information, Team information, Firm-specific human capital) while the third gets human capital in bold when its own section opens at 724, and the two list-item terms at 809 and 812 (Moving is disruptive, Information is firm-specific) are italic definitions in the same idiom. Separately, italic is used as a key-result highlighter on whole sentences and clauses rather than for word-level emphasis: 371 (“faster growth forces shorter screening periods”), 406 (“increasing costs of rapid adjustment arise endogenously”), 457 (“growth rates are independent of firm size”), 886-887 (“same mean growth rate”, “less variance”) - which is a legitimate device but not the one the rule assigns to italic, and it competes with the word-level italics at 130, 261, 590 and 807.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 2. Lines: 459, 843. Example: two of the ten figures demonstrate arithmetic identities rather than the model, and both are then read as confirmations of the model’s predictions. simulate_firm_growth (466-476) sets output[t] = output[t-1] * (1 + γ + shock) with the same \(\gamma\) for all three firms, so the parallel log paths in the right-hand panel are true by construction; 510-513 nonetheless reads them as evidence - “all firms grow at the same rate regardless of initial size … This is Gibrat’s Law”. Nothing about organization capital, screening or \(n(\gamma)\) enters the simulation, and the function’s ρ argument is passed but never used, so even the quit rate that drives \(n(\gamma)\) is inert. Similarly simulate_growth_rate_distribution (850-859) averages iid normal draws over subunits and over 100 periods and returns one number per firm, so the variance falls like \(\sigma/\sqrt{n_{\text{sub}} \cdot T}\); 886-888 reads the result as the model’s prediction that “large firms display less variance in realized growth rates because they are effectively portfolios of independent subunits”, and 890 attaches it to empirical work on period-by-period growth rates, which is not the quantity plotted. Both figures could be built from the model that the lecture has already coded: screening_time (339) and cost_per_unit (272) give \(c(n(\gamma))\), and a firm choosing \(\gamma\) against that cost schedule and a demand price would produce a genuine growth path and a genuine equilibrium \(\gamma\) - which would also fill the gap at 480.

Low severity#

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

Strengths#

  • Heading capitalisation is exactly right throughout: the H1 at 14 is Title Case (“# Organization Capital”) and every one of the eighteen H2s and H3s is sentence case (19, 61, 88, 96, 115, 140, 233, 305, 378, 413, 452, 515, 622, 636, 719, 752, 796, 824), including the two that carry colons.

  • All ten figure cells carry mystnb: figure: caption and name metadata (185-189, 266-270, 333-337, 384-388, 460-464, 526-530, 598-602, 664-668, 755-759, 844-848), so every figure in the lecture is captioned and cross-referenceable.

  • The screening-and-assignment scatter (525-587) is the strongest figure in the lecture and does something prose cannot: it plots true \(\theta\) against posterior mean for 5000 workers at six screening lengths, colours the misassigned ones, and draws the two decision axes - so the reader watches the sign errors concentrate near the origin and thin out as \(n\) grows, which is the mechanism the whole cost function rests on.

  • The central composition is built one factor at a time and each factor is plotted before they are combined: \(c(n)\) at 265-293, \(n(\gamma)\) at 332-368, then \(c(n(\gamma))\) at 383-403, with the reading given at 406-410 - so “increasing costs of rapid adjustment arise endogenously” is a conclusion the reader has seen assembled rather than an assertion.

  • The magic constant is explained rather than dropped in: 253 gives the integral it comes from and the note at 255-259 identifies it as the mean of the standard half-normal and says which difference of conditional expectations produces it.

  • The Bayesian machinery is written once and reused correctly: bayesian_update (172-179) implements {eq}`eq:post_mean` and {eq}`eq:post_prec` exactly, and the team version at 681 implements the shifted formula of 655 exactly - \(\mu + n(\bar z - \mu)/(\pi + n)\) is algebraically the sum form written there.

  • The paper’s three examples get three parallel sections and the parallel is made explicit rather than left implicit: 660-661 says the team model “has the same mathematical structure as the personnel information model” when the accrued information dies with the team, which is the condition that makes the claim true.

  • Citations are in-text {cite:t} throughout with no parenthetical errors (22, 46 twice, 76, 420, 440, 731, 890 twice), and each one is attached to the specific claim it supports rather than clustered at a section head.