From b0b088d3a059d04b5821afbf010f8a3fab5e5ac8 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Fri, 6 Oct 2023 08:39:09 +0300
Subject: [PATCH 1/3] Document new binomial_logit_glm distribution

---
 .../bounded_discrete_distributions.Rmd        | 126 ++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/src/functions-reference/bounded_discrete_distributions.Rmd b/src/functions-reference/bounded_discrete_distributions.Rmd
index bdaea5c80..5aa10e520 100644
--- a/src/functions-reference/bounded_discrete_distributions.Rmd
+++ b/src/functions-reference/bounded_discrete_distributions.Rmd
@@ -155,6 +155,132 @@ The log binomial probability mass of n successes in N trials given
 logit-scaled chance of success alpha dropping constant additive terms
 `r since("2.25")`
 
+## Binomial-logit generalized linear model (Logistic Regression) {#binomial-logit-glm}
+
+Stan also supplies a single function for a generalized linear model
+with Binomial likelihood and logit link function, i.e. a function
+for logistic regression with aggregated outcomes. This provides a more efficient
+implementation of logistic regression than a manually written
+regression in terms of a Binomial likelihood and matrix
+multiplication.
+
+### Probability mass function
+
+Suppose $N \in \mathbb{N}$, $x\in \mathbb{R}^{n\cdot m}, \alpha \in \mathbb{R}^n, \beta \in \mathbb{R}^m$, and $n \in
+\{0,\ldots,N\}$.  Then \begin{align*}
+&\text{BinomialLogitGLM}(n~|~N, x, \alpha, \beta) = \text{Binomial}(n~|~N,\text{logit}^{-1}(\alpha_i + x_i\cdot
+\beta)) \\ &= \binom{N}{n} \left( \text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{n}  \left( 1 -
+\text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{N - n}.  \end{align*}
+
+### Sampling statement
+
+`n ~ ` **`binomial_logit_glm`**`(N, x, alpha, beta)`
+
+Increment target log probability density with `binomial_logit_glm_lupmf(n | N, x, alpha, beta)`.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm ~; -->
+\index{{\tt \bfseries binomial\_logit\_glm }!sampling statement|hyperpage}
+
+### Stan Functions
+
+<!-- real; binomial_logit_glm_lpmf; (int n | int N, matrix x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (int n \textbar\ int N, matrix x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(int n | int N, matrix x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lupmf; (int n | int N, matrix x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (int n \textbar\ int N, matrix x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(int n | int N, matrix x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lpmf; (int n | int N, matrix x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (int n \textbar\ int N, matrix x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(int n | int N, matrix x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lupmf; (int n | int N, matrix x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (int n \textbar\ int N, matrix x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(int n | int N, matrix x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lpmf; (array[] int n | array[] int N, row_vector x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, row_vector x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, row_vector x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, row_vector x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lpmf; (array[] int n | array[] int N, row_vector x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, row_vector x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, row_vector x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, row_vector x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
+
+<!-- real; binomial_logit_glm_lpmf; (array[] int n | array[] int N, matrix x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.18")`
+
+<!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, matrix x, real alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, real alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, matrix x, real alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
+<!-- real; binomial_logit_glm_lpmf; (array[] int n | array[] int N, matrix x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)`.
+`r since("2.18")`
+
+<!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, matrix x, vector alpha, vector beta); -->
+\index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, vector alpha, vector beta): real}|hyperpage}
+
+`real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, matrix x, vector alpha, vector beta)`<br>\newline
+The log Binomial probability mass of n given N trials and chance of success
+`inv_logit(alpha + x * beta)` dropping constant additive terms.
+`r since("2.34")`
+
 ## Beta-binomial distribution
 
 ### Probability mass function

From 9f7e9a55016c1d3e82c0a81bff04c77fa845c9d3 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Fri, 6 Oct 2023 08:44:57 +0300
Subject: [PATCH 2/3] Missed versioning

---
 src/functions-reference/bounded_discrete_distributions.Rmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/functions-reference/bounded_discrete_distributions.Rmd b/src/functions-reference/bounded_discrete_distributions.Rmd
index 5aa10e520..a97d9bb39 100644
--- a/src/functions-reference/bounded_discrete_distributions.Rmd
+++ b/src/functions-reference/bounded_discrete_distributions.Rmd
@@ -255,7 +255,7 @@ The log Binomial probability mass of n given N trials and chance of success
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, real alpha, vector beta)`<br>\newline
 The log Binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
-`r since("2.18")`
+`r since("2.34")`
 
 <!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, matrix x, real alpha, vector beta); -->
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, real alpha, vector beta): real}|hyperpage}
@@ -271,7 +271,7 @@ The log Binomial probability mass of n given N trials and chance of success
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, vector alpha, vector beta)`<br>\newline
 The log Binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
-`r since("2.18")`
+`r since("2.34")`
 
 <!-- real; binomial_logit_glm_lupmf; (array[] int n | array[] int N, matrix x, vector alpha, vector beta); -->
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, vector alpha, vector beta): real}|hyperpage}

From ba7cdc285b01a1071fd8345104b451fc608bba80 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Fri, 12 Jan 2024 13:33:01 +0200
Subject: [PATCH 3/3] Capitalisation and eqn formatting

---
 .../bounded_discrete_distributions.Rmd        | 35 ++++++++++---------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/src/functions-reference/bounded_discrete_distributions.Rmd b/src/functions-reference/bounded_discrete_distributions.Rmd
index a97d9bb39..152694ed0 100644
--- a/src/functions-reference/bounded_discrete_distributions.Rmd
+++ b/src/functions-reference/bounded_discrete_distributions.Rmd
@@ -158,7 +158,7 @@ logit-scaled chance of success alpha dropping constant additive terms
 ## Binomial-logit generalized linear model (Logistic Regression) {#binomial-logit-glm}
 
 Stan also supplies a single function for a generalized linear model
-with Binomial likelihood and logit link function, i.e. a function
+with binomial likelihood and logit link function, i.e., a function
 for logistic regression with aggregated outcomes. This provides a more efficient
 implementation of logistic regression than a manually written
 regression in terms of a Binomial likelihood and matrix
@@ -167,10 +167,11 @@ multiplication.
 ### Probability mass function
 
 Suppose $N \in \mathbb{N}$, $x\in \mathbb{R}^{n\cdot m}, \alpha \in \mathbb{R}^n, \beta \in \mathbb{R}^m$, and $n \in
-\{0,\ldots,N\}$.  Then \begin{align*}
-&\text{BinomialLogitGLM}(n~|~N, x, \alpha, \beta) = \text{Binomial}(n~|~N,\text{logit}^{-1}(\alpha_i + x_i\cdot
-\beta)) \\ &= \binom{N}{n} \left( \text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{n}  \left( 1 -
-\text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{N - n}.  \end{align*}
+\{0,\ldots,N\}$.  Then
+\begin{align*}
+  &\text{BinomialLogitGLM}(n~|~N, x, \alpha, \beta) = \text{Binomial}(n~|~N,\text{logit}^{-1}(\alpha_i + x_i \cdot \beta)) \\
+  &= \binom{N}{n} \left( \text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{n}  \left( 1 - \text{logit}^{-1}(\alpha_i + \sum_{1\leq j\leq m}x_{ij}\cdot \beta_j) \right)^{N - n}.
+\end{align*}
 
 ### Sampling statement
 
@@ -188,7 +189,7 @@ Increment target log probability density with `binomial_logit_glm_lupmf(n | N, x
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (int n \textbar\ int N, matrix x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(int n | int N, matrix x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -196,7 +197,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (int n \textbar\ int N, matrix x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(int n | int N, matrix x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`
 
@@ -204,7 +205,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (int n \textbar\ int N, matrix x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(int n | int N, matrix x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -212,7 +213,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (int n \textbar\ int N, matrix x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(int n | int N, matrix x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`
 
@@ -220,7 +221,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, row_vector x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -228,7 +229,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, row_vector x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`
 
@@ -236,7 +237,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, row_vector x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -244,7 +245,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, row\_vector x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, row_vector x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`
 
@@ -253,7 +254,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -261,7 +262,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, real alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, matrix x, real alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`
 
@@ -269,7 +270,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lpmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lpmf`**`(array[] int n | array[] int N, matrix x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)`.
 `r since("2.34")`
 
@@ -277,7 +278,7 @@ The log Binomial probability mass of n given N trials and chance of success
 \index{{\tt \bfseries binomial\_logit\_glm\_lupmf  }!{\tt (array[] int n \textbar\ array[] int N, matrix x, vector alpha, vector beta): real}|hyperpage}
 
 `real` **`binomial_logit_glm_lupmf`**`(array[] int n | array[] int N, matrix x, vector alpha, vector beta)`<br>\newline
-The log Binomial probability mass of n given N trials and chance of success
+The log binomial probability mass of n given N trials and chance of success
 `inv_logit(alpha + x * beta)` dropping constant additive terms.
 `r since("2.34")`