Refine statistical descriptions and code comments

Author: aloctavodia

Chapters/Distributions.qmd

@@ -144,30 +144,32 @@ To summarize a distribution we usually use some measure of central tendency and
 
 ```{python}
 #| code-fold: true
-#| label: point-estimates
-#| fig-cap: "A gamma distribution with its mean, median, and mode."
+#| label: fig-point-estimates
+#| fig-cap: "A gamma distribution with dashed lines representing its mean, median, and mode."
 dist = pz.Gamma(3, 2)
 mean = dist.mean()
 median = dist.median()
 mode = dist.mode()
 ax = dist.plot_pdf(figsize=(10, 3), legend="title")
 for idx, (stat, value) in enumerate(zip(
-    [f"mean    = {mean:.2f}", f"median = {median:.2f}", f"mode    = {mode:.2f}"], [mean, median, mode]
+    [f"mean    = {mean:.1f}", f"median = {median:.1f}", f"mode    = {mode:.1f}"], [mean, median, mode]
 )):
     ax.axvline(value, label=stat, color=f"C{idx+1}", ls="--")
 ax.legend();
 ```
 
-The mean is the average value of the distribution, the median is the value that divides the distribution into two equal halves, and the mode is the value with the highest probability density. In symmetric distributions like the `Normal`, these three measures are equal. But in skewed distributions like the `Gamma`, they can be quite different. The mean is probably the most commonly used measure of central tendency, but it can be sensitive to outliers. The median is more robust to outliers and is often preferred in skewed distributions. The mode is useful when we are interested in the most probable value of the distribution, the mode is usually less common than the other too. In practice, the choice of which measure to use depends on the context and the specific characteristics of the distribution being analyzed.
+The mean is the average value of the distribution, the median is the value that divides the distribution into two equal halves, and the mode is the value with the highest probability density. In symmetric distributions like the `Normal`, these three measures are equal. But in skewed distributions like the `Gamma`, they can be quite different.
 
-In ArviZ we can compute these point estimates from samples using the `azp.mean()`, `azp.median()`, and `azp.mode()` functions. 
+The mean is probably the most commonly used measure of central tendency, but it can be sensitive to outliers. The median is more robust to outliers and is often preferred in skewed distributions. The mode is useful when we are interested in the most probable value of the distribution. The mode is usually less common than the other too. In practice, the choice of which measure to use depends on the context and the specific characteristics of the distribution being analyzed.
+
+In ArviZ, we can compute these point estimates from samples using the `azp.mean()`, `azp.median()`, and `azp.mode()` functions. 
 
 ```{python}
 pois_data = dist.rvs(50_000, random_state=rng)
 azp.mean(pois_data), azp.median(pois_data), azp.mode(pois_data)
 ```
 
-Point estimates also show in other places in ArviZ, for example in the `plot_dist()` or when calling `summary()`, these functions has a `point_estimate` argument to choose which point estimate to use. The default value is controlled globally by:
+Point estimates also show in other places in ArviZ, for example, in the `plot_dist()` or when calling `summary()`. Some functions have a `point_estimate` argument to choose which point estimate to use. The default value is controlled globally by:
 
 ```{python}
 azp.rcParams["stats.point_estimate"]
@@ -177,14 +179,14 @@ azp.rcParams["stats.point_estimate"]
 
 To describe the uncertainty in our estimates, we usually want to complement point estimates with some measure of dispersion. A common approach is to use the standard deviation or the variance. The standard deviation is usually preferred over the variance because it is in the same units as the original data. However, both measures can be misleading for skewed distributions or distributions with heavy tails. Hence, other measures of dispersion are often preferred like the median absolute deviation [MAD](https://en.wikipedia.org/wiki/Median_absolute_deviation) or the interquartile range [IQR](https://en.wikipedia.org/wiki/Interquartile_range).
 
-One issue with using a single number to summarize uncertainty is that it does not provide information about the shape of the distribution. For example two distributions can have the same standard deviation but very different shapes. Or for bounded distributions like the `Gamma`, the standard deviation can be misleading as it does not take into account that negative values are not allowed.
+One issue with using a single number to summarize uncertainty is that it does not provide information about the shape of the distribution. For example, two distributions can have the same standard deviation but very different shapes. Or for bounded distributions like the `Gamma`, the standard deviation can be misleading, as it does not take into account that negative values are not allowed.
 
-One popular way to summarize the uncertainty in a distribution is to use intervals. For example, we may want to report that 90% of the values lie within a certain range. In Bayesian statistics, these often called `credible intervals`. In principle we can defined infinite intervals containing a given mass. Then we need to add some other constraint to build useful intervals. Two common types of credible intervals are the `equal-tailed interval` (ETI) and the `highest-density interval` (HDI).
+One popular way to summarize the uncertainty in a distribution is to use intervals. For example, we may want to report that 90% of the values lie within a certain range. In Bayesian statistics, these are often called `credible intervals`. In principle, we can defined infinite intervals containing a given mass. Then we need to add some other constraint to build useful intervals. Two common types of credible intervals are:
 
-* ETI: The interval that contains a given percentage of the distribution, with equal probability in both tails. For example, a 90% equal-tailed interval
+* The `equal-tailed interval` (ETI): The interval that contains a given percentage of the distribution, with equal probability in both tails. For example, a 90% equal-tailed interval
 has 90% of the distribution between the lower and upper bounds, with 5% of the distribution in each tail. 
 
-* HDI: The interval that contains a given mass and where all points inside the interval have a higher density than any point outside the interval. Alternatively, we can think of it as the shortest interval containing a given portion of the probability density.
+* The `highest-density interval` (HDI): The interval that contains a given mass and where all points inside the interval have a higher density than any point outside the interval. Alternatively, we can think of it as the shortest interval containing a given portion of the probability density.
 
 For some distributions like asymmetric ones, the HDI is usually preferred over the ETI because it better represents the most credible values of the distribution.