[additive_functionals] Style guide review

lectures/additive_functionals.md

@@ -35,15 +35,17 @@ In addition to what's in Anaconda, this lecture will need the following librarie
 
 ## Overview
 
-Many economic time series display persistent growth that prevents them from being  asymptotically stationary and ergodic.
+Many economic time series display persistent growth that prevents them from being asymptotically stationary and ergodic.
 
-For example, outputs, prices, and dividends typically display  irregular but persistent growth.
+For example, outputs, prices, and dividends typically display irregular but persistent growth.
 
 Asymptotic stationarity and ergodicity are key assumptions needed to make it possible to learn by applying statistical methods.
 
-But  there are good ways to model time series that have persistent growth that still enable statistical learning based on a law of large numbers for an asymptotically stationary and ergodic process.
+However, there are good ways to model time series with persistent growth.
 
-Thus, {cite}`Hansen_2012_Eca`  described  two classes of time series models that accommodate growth.
+These models still enable statistical learning based on a law of large numbers for an asymptotically stationary and ergodic process.
+
+Thus, {cite}`Hansen_2012_Eca` described two classes of time series models that accommodate growth.
 
 They are
 
@@ -54,7 +56,9 @@ These two classes of processes are closely connected.
 
 If a process $\{y_t\}$ is an additive functional and $\phi_t = \exp(y_t)$, then $\{\phi_t\}$ is a multiplicative functional.
 
-In this lecture, we describe both  additive functionals and multiplicative functionals.
+If a process $\{y_t\}$ is an additive functional and $\phi_t = \exp(y_t)$, then $\{\phi_t\}$ is a multiplicative functional.
+
+In this lecture, we describe both additive functionals and multiplicative functionals.
 
 We also describe and compute decompositions of additive and multiplicative processes into four components:
 
@@ -83,8 +87,7 @@ from scipy.stats import norm, lognorm
 
 This lecture focuses on a subclass of these: a scalar process $\{y_t\}_{t=0}^\infty$ whose increments are driven by a Gaussian vector autoregression.
 
-Our special additive functional displays interesting time series behavior while also being easy to construct, simulate, and analyze
-by using linear state-space tools.
+Our special additive functional displays interesting time series behavior while being easy to construct, simulate, and analyze using linear state-space tools.
 
 We construct our  additive functional from two pieces, the first of which is a **first-order vector autoregression** (VAR)
 
@@ -193,6 +196,7 @@ But here we will use a different set of code for simulation, for reasons describ
 Let's run some simulations to build intuition.
 
 (addfunc_eg1)=
+
 In doing so we'll assume that $z_{t+1}$ is scalar and that $\tilde x_t$ follows a 4th-order scalar autoregression.
 
 ```{math}
@@ -221,11 +225,11 @@ $$
 
 with an initial condition for $y_0$.
 
-While {eq}`ftaf` is not a first order system like {eq}`old1_additive_functionals`, we know that it can be mapped  into a first order system.
+While {eq}`ftaf` is not a first order system like {eq}`old1_additive_functionals`, we know that it can be mapped into a first order system.
 
 * For an example of such a mapping, see [this example](https://python.quantecon.org/linear_models.html#second-order-difference-equation).
 
-In fact, this whole model can be mapped into the additive functional system definition in {eq}`old1_additive_functionals` -- {eq}`old2_additive_functionals`  by appropriate selection of the matrices $A, B, D, F$.
+In fact, this whole model can be mapped into the additive functional system definition in {eq}`old1_additive_functionals` -- {eq}`old2_additive_functionals` by appropriate selection of the matrices $A, B, D, F$.
 
 You can try writing these matrices down now as an exercise --- correct expressions appear in the code below.
 
@@ -733,7 +737,7 @@ $$
 \end{aligned}
 $$
 
-Then the Hansen {cite}`Hansen_2012_Eca`, {cite}`Hans_Sarg_book` decomposition is
+The Hansen {cite}`Hansen_2012_Eca`, {cite}`Hans_Sarg_book` decomposition is:
 
 $$
 \begin{aligned}
@@ -745,6 +749,8 @@ $$
 \end{aligned}
 $$
 
+Consider adding a flow diagram showing how these four components combine to form the additive functional.
+
 At this stage, you should pause and verify that $y_{t+1} - y_t$ satisfies {eq}`old2_additive_functionals`.
 
 It is convenient for us to introduce the following notation:
@@ -755,7 +761,7 @@ It is convenient for us to introduce the following notation:
 
 We want to characterize and simulate components $\tau_t, m_t, s_t$ of the decomposition.
 
-A convenient way to do this is to construct an appropriate instance of a [linear state space system](https://python-intro.quantecon.org/linear_models.html) by using [LinearStateSpace](https://github.com/QuantEcon/QuantEcon.py/blob/master/quantecon/lss.py) from [QuantEcon.py](http://quantecon.org/quantecon-py).
+We can do this by constructing a [linear state space system](https://python-intro.quantecon.org/linear_models.html) using [LinearStateSpace](https://github.com/QuantEcon/QuantEcon.py/blob/master/quantecon/lss.py) from [QuantEcon.py](http://quantecon.org/quantecon-py).
 
 This will allow us to use the routines in [LinearStateSpace](https://github.com/QuantEcon/QuantEcon.py/blob/master/quantecon/lss.py) to study dynamics.
 
@@ -844,17 +850,17 @@ interest.
 
 The class `AMF_LSS_VAR` mentioned {ref}`above <amf_lss>` does all that we want to study our additive functional.
 
-In fact, `AMF_LSS_VAR` does more
-because it allows us to study  an associated multiplicative functional as well.
+In fact, `AMF_LSS_VAR` does more: it allows us to study an associated multiplicative functional.
+
+The class name hints at this broader functionality: AMF stands for "additive and multiplicative functional."
 
-(A hint that it does more is the name of the class -- here AMF stands for
-"additive and multiplicative functional" -- the code computes and displays objects associated with
-multiplicative functionals too.)
+The code computes and displays objects associated with both types of functionals.
 
 Let's use this code (embedded above) to explore the {ref}`example process described above <addfunc_eg1>`.
 
-If you run {ref}`the code that first simulated that example <addfunc_egcode>` again and then the method call
-you will generate (modulo randomness) the plot
+To generate the decomposition plot, run {ref}`the code that first simulated that example <addfunc_egcode>` followed by the method call below.
+
+The plot will show (modulo randomness):
 
 ```{code-cell} ipython3
 plot_additive(amf, T)
@@ -863,7 +869,9 @@ plt.show()
 
 When we plot multiple realizations of a component in the 2nd, 3rd, and 4th panels, we also plot the population 95% probability coverage sets computed using the LinearStateSpace class.
 
-We have chosen to simulate many paths, all starting from the *same* non-random initial conditions $x_0, y_0$ (you can tell this from the shape of the 95% probability coverage shaded areas).
+We simulate many paths starting from the same non-random initial conditions $x_0, y_0$.
+
+The shape of the 95% probability coverage shaded areas reflects this choice.
 
 Notice tell-tale signs of these probability coverage shaded areas
 
@@ -905,7 +913,7 @@ $$
 \tilde e(x) = \exp[g(x)] = \exp \bigl[ D (I - A)^{-1} x \bigr]
 $$
 
-An instance of class `AMF_LSS_VAR` ({ref}`above <amf_lss>`)  includes this associated multiplicative functional as an attribute.
+An instance of class `AMF_LSS_VAR` ({ref}`above <amf_lss>`) includes this associated multiplicative functional as an attribute.
 
 Let's plot this multiplicative functional for our example.
 
@@ -919,30 +927,24 @@ plt.show()
 
 As before, when we plotted multiple realizations of a component in the 2nd, 3rd, and 4th panels, we also plotted population 95% confidence bands computed using the LinearStateSpace class.
 
-Comparing this figure and the last also helps show how geometric growth differs from
-arithmetic growth.
+Comparing this figure and the last also helps show how geometric growth differs from arithmetic growth.
 
-The top right panel of the above graph shows a panel of martingales associated with the panel of $M_t = \exp(y_t)$ that we have generated
-for a limited horizon $T$.
+The top right panel shows martingales associated with $M_t = \exp(y_t)$ generated for a limited horizon $T$.
 
-It is interesting to how the martingale behaves as $T \rightarrow +\infty$.
+It is interesting to see how the martingale behaves as $T \rightarrow +\infty$.
 
-Let's see what happens when we set $T = 12000$ instead of $150$.
+To investigate this, let's set $T = 12000$ instead of $150$.
 
 ### Peculiar large sample property
 
-Hansen and Sargent {cite}`Hans_Sarg_book` (ch. 8) describe the following two properties of the  martingale component
-$\widetilde M_t$ of the multiplicative decomposition
+Hansen and Sargent {cite}`Hans_Sarg_book` (ch. 8) describe two properties of the martingale component $\widetilde M_t$:
 
-* while $E_0 \widetilde M_t = 1$ for all $t \geq 0$,
-  nevertheless $\ldots$
-* as $t \rightarrow +\infty$, $\widetilde M_t$ converges to
-  zero almost surely
+* $E_0 \widetilde M_t = 1$ for all $t \geq 0$
+* as $t \rightarrow +\infty$, $\widetilde M_t$ converges to zero almost surely
 
-The first property follows from the fact that $\widetilde M_t$ is a multiplicative martingale with initial condition
-$\widetilde M_0 = 1$.
+The first property follows from $\widetilde M_t$ being a multiplicative martingale with initial condition $\widetilde M_0 = 1$.
 
-The second is a **peculiar property** noted and proved by Hansen and Sargent {cite}`Hans_Sarg_book`.
+The second property is peculiar and was first proved by Hansen and Sargent {cite}`Hans_Sarg_book`.
 
 The following simulation of many paths of $\widetilde M_t$ illustrates both properties
 
@@ -960,10 +962,9 @@ The purple 95 percent frequency coverage interval collapses around zero, illustr
 
 ## More about the multiplicative martingale
 
-Let's drill down and study probability distribution of the multiplicative martingale  $\{\widetilde M_t\}_{t=0}^\infty$  in
-more detail.
+Let's study the probability distribution of the multiplicative martingale $\{\widetilde M_t\}_{t=0}^\infty$ in detail.
 
-As we  have seen, it has representation
+As we have seen, it has representation
 
 $$
 \widetilde M_t = \exp \biggl( \sum_{j=1}^t \biggl(H \cdot z_j -\frac{ H \cdot H }{2} \biggr) \biggr),  \quad \widetilde M_0 =1
@@ -977,8 +978,7 @@ It follows that $\log {\widetilde M}_t \sim {\mathcal N} ( -\frac{t H \cdot H}{2
 
 Next, we want a program to simulate the likelihood ratio process $\{ \tilde{M}_t \}_{t=0}^\infty$.
 
-In particular, we want to simulate 5000 sample paths of length $T$ for the case in which $x$ is a scalar and
-$[A, B, D, F] = [0.8, 0.001, 1.0, 0.01]$ and $\nu = 0.005$.
+We simulate 5000 sample paths of length $T$ where $x$ is scalar, $[A, B, D, F] = [0.8, 0.001, 1.0, 0.01]$, and $\nu = 0.005$.
 
 After accomplishing this, we want to display and study histograms of $\tilde{M}_T^i$ for various values of  $T$.
 
@@ -1142,8 +1142,7 @@ def population_means(amf, T=150):
     return xmean, ymean
 ```
 
-Now that we have these functions in our toolkit, let's apply them to run some
-simulations.
+Let's apply these functions to run simulations.
 
 ```{code-cell} ipython3
 def simulate_martingale_components(amf, T=1000, I=5000):
@@ -1181,10 +1180,9 @@ in period T is")
 print(f"\t ({np.min(mmcT)}, {np.mean(mmcT)}, {np.max(mmcT)})")
 ```
 
-Let's plot the probability density functions for $\log {\widetilde M}_t$ for
-$t=100, 500, 1000, 10000, 100000$.
+Let's plot the probability density functions for $\log {\widetilde M}_t$ for $t=100, 500, 1000, 10000, 100000$.
 
-Then let's use the plots to  investigate how these densities evolve through time.
+We use these plots to investigate how the densities evolve over time.
 
 We will plot the densities of $\log {\widetilde M}_t$ for different values of $t$.
 
@@ -1248,21 +1246,18 @@ plt.tight_layout()
 plt.show()
 ```
 
-These probability density functions help us understand mechanics underlying the  **peculiar property** of our multiplicative martingale
+These probability density functions help us understand mechanics underlying the **peculiar property** of our multiplicative martingale
 
 * As $T$ grows, most of the probability mass shifts leftward toward zero.
-* For example, note that most  mass is near $1$ for $T =10$ or $T = 100$ but
-  most of it is near $0$ for $T = 5000$.
+* For example, note that most mass is near $1$ for $T =10$ or $T = 100$ but most of it is near $0$ for $T = 5000$.
 * As $T$ grows, the tail of the density of $\widetilde M_T$ lengthens toward the right.
-* Enough mass moves toward the right tail to keep $E \widetilde M_T = 1$
-  even as most mass in the distribution of $\widetilde M_T$ collapses around $0$.
+* Enough mass moves toward the right tail to maintain $E \widetilde M_T = 1$ even as most of the distribution collapses around $0$.
 
 ### Multiplicative martingale as likelihood ratio process
 
-[This lecture](https://python.quantecon.org/likelihood_ratio_process.html) studies **likelihood processes**
-and **likelihood ratio processes**.
+[This lecture](https://python.quantecon.org/likelihood_ratio_process.html) studies **likelihood processes** and **likelihood ratio processes**.
 
-A **likelihood ratio process** is  a  multiplicative  martingale with mean unity.
+A **likelihood ratio process** is a multiplicative martingale with mean unity.
 
 Likelihood ratio processes exhibit the peculiar property that naturally also appears
 [here](https://python.quantecon.org/likelihood_ratio_process.html).