Merge pull request #894 from stan-dev/fix-655

fix triangle distribution equation

Author: bob-carpenter

src/stan-users-guide/custom-probability.qmd

@@ -12,28 +12,44 @@ the total log probability.  The rest of the chapter provides examples.
 
 ### Triangle distribution {-}
 
-A simple example is the triangle distribution,
+A simple example is the symmetric triangle distribution,
 whose density is shaped like an isosceles triangle with corners at
 specified bounds and height determined by the constraint that a
 density integrate to 1.  If $\alpha \in \mathbb{R}$ and $\beta \in \mathbb{R}$
 are the bounds, with $\alpha < \beta$, then $y \in (\alpha,\beta)$ has
-a density defined as follows.
+a density defined as
 $$
 \textsf{triangle}(y \mid \alpha,\beta)
 =
-\frac{2}{\beta - \alpha}
-\
-\left(
-1 -
-\left|
-y - \frac{\alpha + \beta}{\beta - \alpha}
-\right|
-\right)
+\frac{1}{(\beta - \alpha)^2}
+\cdot
+\textrm{min}(y - \alpha, \beta - y).
 $$
 
-If $\alpha = -1$, $\beta = 1$, and $y \in (-1,1)$, this reduces to
+The general form of triangle can be coded in Stan as follows.
+
+```stan
+data {
+  real alpha;
+  real<lower=alpha> beta;
+}
+parameters {
+  real<lower=alpha, upper=beta> y;
+}
+model {
+  target += -2 * log(beta - alpha)
+    + log(fmin(y - alpha, beta - y));
+}
+```
+
+Because the bounds are specified as data here, the term `-2 * log(beta
+- alpha)` could be dropped from the log density.  If either of the
+bounds depends on a parameter, then this term must be included.
+
+If $\alpha = -1$, $\beta = 1$, and $y \in (-1,1)$, then
+`fmin(y - alpha, beta - y)` is `fmin(y + 1, -1 - y)`, which is `fmin(y + 1, -(y + 1))`, which reduces to `1 - abs(y)`.  Therfore, the density, dropping constants, reduces to
 $$
-\textsf{triangle}(y \mid -1,1) = 1 - |y|.
+\textsf{triangle}(y \mid -1, 1) \propto 1 - |y|.
 $$
 Consider the following Stan implementation of
 $\textsf{triangle}(-1,1)$ for sampling.
@@ -49,11 +65,11 @@ model {
 ```
 
 The single scalar parameter `y` is declared as lying in the
-interval `(-1,1)`.  The total log probability is
+interval `(-1, 1)`.  The total log probability is
 incremented with the joint log probability of all parameters, i.e.,
-$\log \mathsf{Triangle}(y \mid -1,1)$.  This value is coded in Stan as
+$\log \mathsf{Triangle}(y \mid -1, 1)$.  This value is coded in Stan as
 `log1m(abs(y))`.  The function `log1m` is defined so
-that `log1m(x)` has the same value as $\log(1-x)$, but the
+that `log1m(x)` has the same value as $\log(1 - x)$, but the
 computation is faster, more accurate, and more stable.
 
 The constrained type `real<lower=-1, upper=1>` declared for `y` is
@@ -65,7 +81,7 @@ explored values of `y` outside of $(-1,1)$.
 
 Now suppose the log probability function were extended to all of
 $\mathbb{R}$ as follows by defining the probability to be `log(0.0)`,
-i.e., $-\infty$, for values outside of $(-1,1)$.
+i.e., $-\infty$, for values outside of $(-1, 1)$.
 
 ```stan
 target += log(fmax(0.0,1 - abs(y)));