Update example

examples/plot_stockdon.py

@@ -5,33 +5,35 @@
 
 
 In this example, we will evaluate the accuracy of the Stockdon et al (2006) runup
-model, using the Power et al (2018) dataset.
+model. To do this, we will use the compiled wave runup observations provided by Power
+et al (2018).
 
-The Stockdon et al (2006) model looks like:
-
-For dissipative beaches (i.e. :math:`\\zeta < 0.3`) Eqn (18) from the paper is used:
+The Stockdon et al (2006) wave runup model comprises of two relationships, one for
+dissipative beaches (i.e. :math:`\\zeta < 0.3`) Eqn (18):
 
 .. math:: R_{2} = 0.043(H_{s}L_{p})^{0.5}
 
-For intermediate and reflective beaches (i.e. :math:`\\zeta > 0.3`), the function
-returns the result from Eqn (19):
+and a seperate relationship for intermediate and reflective beaches (i.e.
+:math:`\\zeta > 0.3`):
 
 .. math::
 
  R_{2} = 1.1 \\left( 0.35 \\beta (H_{s}L_{p})^{0.5} + \\frac{H_{s}L_{p}(
  0.563 \\beta^{2} +0.004)^{0.5}}{2} \\right)
 
-First, let's import the Power et al (2018) runup data, which is included in this
-package.
+First, let's import our required packages:
 """
 #############################################
-# Let's now make a plot of observed vs. modelled R2 to assess performance
 import matplotlib.pyplot as plt
 import numpy as np
 from sklearn.metrics import mean_squared_error, r2_score
 
 import py_wave_runup
 
+#############################################
+# Let's import the Power et al (2018) runup data, which is included in this
+# package.
+
 df = py_wave_runup.datasets.load_power18()
 print(df.head())
 
@@ -50,7 +52,10 @@
 # Check the first few rows of observed vs. modelled R2
 print(df[["r2", "sto06_r2"]].head())
 
+#############################################
+# Now let's create a plot of observed R2 values vs. predicted R2 values:
 
+# Plot data
 fig, ax1 = plt.subplots(1, 1, figsize=(4, 4), dpi=300)
 ax1.plot(df.r2, df.sto06_r2, "b.", markersize=2, linewidth=0.5)
 
@@ -65,8 +70,11 @@
 plt.tight_layout()
 
 #############################################
+# We can see there is a fair amount of scatter, especially as we get larger wave
+# runup heights. This indicates that the model might not be working as well as we
+# might have hoped.
+#
 # Let's also check RMSE and coefficient of determination values:
 
-
 print(f"R2 Score: {r2_score(df.r2, df.sto06_r2):.2f}")
 print(f"RMSE: {np.sqrt(mean_squared_error(df.r2, df.sto06_r2)):.2f} m")