[commod_price] Update editorial suggestions (#443)

* [commod_price] Update editorial suggestions

* [commod_price] Update the internal link

* [commod_price] Update the plotting code

* [commod_price] Update code

* Update commod_price.md

* fix a small typo in doc ref

* Update lectures/commod_price.md

Co-authored-by: Matt McKay <mmcky@users.noreply.github.com>

* Update lectures/monte_carlo.md

Co-authored-by: Matt McKay <mmcky@users.noreply.github.com>

* Update the link of Monte Carlo

* Update commod_price.md

* misc

---------

Co-authored-by: Humphrey Yang <u6474961@anu.edu.au>
Co-authored-by: Matt McKay <mmcky@users.noreply.github.com>
Co-authored-by: John Stachurski <john.stachurski@gmail.com>

lectures/commod_price.md

@@ -32,8 +32,7 @@ We will solve an equation where the price function is the unknown.
 
 This is harder than solving an equation for an unknown number, or vector.
 
-The lecture will discuss one way to solve a "functional equation" for an unknown
-function 
+The lecture will discuss one way to solve a [functional equation](https://en.wikipedia.org/wiki/Functional_equation) (an equation where the unknown object is a function).
 
 For this lecture we need the `yfinance` library.
 
@@ -70,7 +69,7 @@ s = yf.download('CT=F', '2016-1-1', '2023-4-1')['Adj Close']
 fig, ax = plt.subplots()
 
 ax.plot(s, marker='o', alpha=0.5, ms=1)
-ax.set_ylabel('price', fontsize=12)
+ax.set_ylabel('cotton price in USD', fontsize=12)
 ax.set_xlabel('date', fontsize=12)
 
 plt.show()
@@ -134,13 +133,12 @@ $p_t$.
 
 The harvest of the commodity at time $t$ is $Z_t$.
 
-We assume that the sequence $\{ Z_t \}_{t \geq 1}$ is IID with common
-density function $\phi$.
+We assume that the sequence $\{ Z_t \}_{t \geq 1}$ is IID with common density function $\phi$, where $\phi$ is nonnegative.
 
 Speculators can store the commodity between periods, with $I_t$ units
 purchased in the current period yielding $\alpha I_t$ units in the next.
 
-Here $\alpha \in (0,1)$ is a depreciation rate for the commodity.
+Here the parameter $\alpha \in (0,1)$ is a depreciation rate for the commodity.
 
 For simplicity, the risk free interest rate is taken to be
 zero, so expected profit on purchasing $I_t$ units is
@@ -175,6 +173,7 @@ $$
   \alpha \mathbb{E}_t \, p_{t+1}  - p_t \leq 0
 $$ (eq:arbi)
 
+This means that if the expected price is lower than the current price, there is no room for arbitrage.
 
 Profit maximization gives the additional condition
 
@@ -183,7 +182,7 @@ $$
 $$ (eq:pmco)
 
 
-We also require that the market clears in each period.
+We also require that the market clears, with supply equaling demand in each period.
 
 We assume that consumers generate demand quantity $D(p)$ corresponding to
 price $p$.
@@ -193,12 +192,12 @@ Let $P := D^{-1}$ be the inverse demand function.
 
 Regarding quantities,
 
-* supply is the sum of carryover by speculators and the current harvest
+* supply is the sum of carryover by speculators and the current harvest, and
 * demand is the sum of purchases by consumers and purchases by speculators.
 
 Mathematically,
 
-* supply $ = X_t = \alpha I_{t-1} + Z_t$, which takes values in $S := \mathbb R_+$, while
+* supply is given by $X_t = \alpha I_{t-1} + Z_t$, which takes values in $S := \mathbb R_+$, while
 * demand $ = D(p_t) + I_t$
 
 Thus, the market equilibrium condition is
@@ -220,6 +219,8 @@ How can we find an equilibrium?
 Our path of attack will be to seek a system of prices that depend only on the
 current state.
 
+(Our solution method involves using an [ansatz](https://en.wikipedia.org/wiki/Ansatz), which is an educated guess --- in this case for the price function.)
+
 In other words, we take a function $p$ on $S$ and set $p_t = p(X_t)$ for every $t$.
 
 Prices and quantities then follow
@@ -235,8 +236,6 @@ conditions above.
 More precisely, we seek a $p$ such that [](eq:arbi) and [](eq:pmco) hold for
 the corresponding system [](eq:eosy).
 
-To this end, suppose that there exists a function $p^*$ on $S$
-satisfying
 
 $$
   p^*(x) = \max
@@ -285,7 +284,7 @@ But then $D(p^*(X_t)) = X_t$ and $I_t = I(X_t) = 0$.
 
 As a consequence, both [](eq:arbi) and [](eq:pmco) hold.
 
-We have found an equilibrium.
+We have found an equilibrium, which verifies the ansatz.
 
 
 ### Computing the equilibrium
@@ -347,7 +346,7 @@ The code below implements this iterative process, starting from $p_0 = P$.
 The distribution $\phi$ is set to a shifted Beta distribution (although many
 other choices are possible).
 
-The integral in [](eq:dopf3) is computed via Monte Carlo.
+The integral in [](eq:dopf3) is computed via {ref}`Monte Carlo <monte-carlo>`.
 
 
 ```{code-cell} ipython3
@@ -395,7 +394,8 @@ while error > tol:
 
 ax.plot(grid, price, 'k-', alpha=0.5, lw=2, label=r'$p^*$')
 ax.legend()
-ax.set_xlabel('$x$', fontsize=12)
+ax.set_xlabel('$x$')
+ax.set_ylabel("prices")
 
 plt.show()
 ```

lectures/monte_carlo.md

@@ -12,7 +12,7 @@ kernelspec:
 ---
 
 
-
+(monte-carlo)=
 # Monte Carlo and Option Pricing
 
 ## Overview
@@ -49,7 +49,6 @@ from numpy.random import randn
 ```
 
 
-
 ## An introduction to Monte Carlo
 
 In this section we describe how Monte Carlo can be used to compute