From 0ddeac3cb818f7aac95472de45957c5e13d97a45 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 2 Sep 2026 11:20:38 -0400 Subject: [PATCH 1/2] Document poisson-binomial --- .../bounded_discrete_distributions.qmd | 86 +++++++++++++++++++ src/functions-reference/functions_index.qmd | 35 ++++++++ 2 files changed, 121 insertions(+) diff --git a/src/functions-reference/bounded_discrete_distributions.qmd b/src/functions-reference/bounded_discrete_distributions.qmd index 209671602..13a713651 100644 --- a/src/functions-reference/bounded_discrete_distributions.qmd +++ b/src/functions-reference/bounded_discrete_distributions.qmd @@ -353,6 +353,92 @@ For a description of argument and return types, see section [vectorized PRNG functions](conventions_for_probability_functions.qmd#prng-vectorization). {{< since 2.18 >}} +## Poisson-binomial distribution {#poisson-binomial} + +### Probability mass function + +Suppose $N \in \mathbb{N}$, $y \in \{0,\ldots,N\}$, and $\theta \in [0,1]^N$. Let +$F_y$ denote the set of all length-$y$ subsets of $\{0,\ldots,N\}$. +Then, \begin{equation*} \text{PoissonBinomial}(y~|~\theta) = \sum\limits_{A\in F_y} \prod\limits_{i\in A} \theta_i \prod\limits_{j\in A^c} (1-\theta_j). \end{equation*} + + +### Distribution statement + + +`y ~ ` **`poisson_binomial`**`(theta)` + +Increment target log probability density with `poisson_binomial_lupmf(y | theta)`. +{{< since 2.40 >}} + +\index{{\tt \bfseries poisson\_binomial }!distribution statement|hyperpage} + +### Stan functions + + +\index{{\tt \bfseries poisson\_binomial\_lpmf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +`real` **`poisson_binomial_lpmf`**`(ints y | vectors theta)`
\newline + +The log poisson-binomial probability mass of `y` successes in +`N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., +`theta[N]` +{{< since 2.40 >}} + + + +\index{{\tt \bfseries poisson\_binomial\_lupmf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +`real` **`poisson_binomial_lupmf`**`(ints y | vectors theta)`
\newline + +The log poisson-binomial probability mass of `y` successes in +`N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., +`theta[N]` dropping constant additive terms +{{< since 2.40 >}} + + + +\index{{\tt \bfseries poisson\_binomial\_cdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +`real` **`poisson_binomial_cdf`**`(ints y | vectors theta)`
\newline + +The poisson-binomial cumulative distribution function of `y` successes in +`N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., +`theta[N]` +{{< since 2.40 >}} + + + +\index{{\tt \bfseries poisson\_binomial\_lcdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +`real` **`poisson_binomial_lcdf`**`(ints y | vectors theta)`
\newline + +The log of the poisson-binomial cumulative distribution function of `y` successes in +`N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., +`theta[N]` +{{< since 2.40 >}} + + + +\index{{\tt \bfseries poisson\_binomial\_lccdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +`real` **`poisson_binomial_lccdf`**`(ints y | vectors theta)`
\newline + +The log of the poisson-binomial complementary cumulative distribution function +of `y` successes in `N = size(theta)` independent trials with probabilities of +success `theta[1]`, ..., `theta[N]` +{{< since 2.40 >}} + + + +\index{{\tt \bfseries poisson\_binomial\_rng }!{\tt (vectors theta): int}|hyperpage} + +`int` **`poisson_binomial_rng`**`(vectors theta)`
\newline + +Generate a poisson-binomial variant of `N = size(theta)` independent trials with +probabilities of success `theta[1]`, ..., `theta[N]`; may only be used in +transformed data and generated quantities blocks. +{{< since 2.40 >}} + ## Hypergeometric distribution ### Probability mass function diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index 952ebe1e7..3ada60705 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -3289,6 +3289,41 @@ pagetitle: Alphabetical Index -
[distribution statement](unbounded_discrete_distributions.qmd#index-entry-149c7a2f2ae0aede0ae6b19854be4a72ba136d10) (unbounded_discrete_distributions.html)
+**poisson_binomial**: + + -
[distribution statement](bounded_discrete_distributions.qmd#index-entry-dbff3b80596957f04c6b36c11f676843500a2197) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_cdf**: + + -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-de5136ae9ac628c68b411470f4a3b6f5ab2714b1) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_lccdf**: + + -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-3ab93b8f233feb6f17d02d52bc1b2ad26499e09e) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_lcdf**: + + -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-2a4c06b205deaf2e48771b8ef9bda88f34064c18) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_lpmf**: + + -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-bc556ef2af9faa87adcc083eda16f4da652a6c62) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_lupmf**: + + -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-a7269ded0d2437bb4b6077732487389a37e21af4) (bounded_discrete_distributions.html)
+ + +**poisson_binomial_rng**: + + -
[`(vectors theta) : int`](bounded_discrete_distributions.qmd#index-entry-1c84520e678c328dd081b4c4362b854b86cee004) (bounded_discrete_distributions.html)
+ + **poisson_cdf**: -
[`(ints n | reals lambda) : real`](unbounded_discrete_distributions.qmd#index-entry-b9228882bc1807740bfbe2278fe3865895ddc14f) (unbounded_discrete_distributions.html)
From 9ee3efbabdb0f8dbb225269c2cb2fabe1c1b388a Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 2 Sep 2026 13:04:00 -0400 Subject: [PATCH 2/2] Update based on review --- .../bounded_discrete_distributions.qmd | 57 +++++++++++-------- src/functions-reference/functions_index.qmd | 10 ++-- 2 files changed, 37 insertions(+), 30 deletions(-) diff --git a/src/functions-reference/bounded_discrete_distributions.qmd b/src/functions-reference/bounded_discrete_distributions.qmd index 13a713651..862f5daf1 100644 --- a/src/functions-reference/bounded_discrete_distributions.qmd +++ b/src/functions-reference/bounded_discrete_distributions.qmd @@ -355,76 +355,83 @@ For a description of argument and return types, see section ## Poisson-binomial distribution {#poisson-binomial} +Also known as the "generalized Binomial distribution", the Poission-binomial +distribution models the distribution of successes in a set of trials with +different probabilities for each trial. + ### Probability mass function -Suppose $N \in \mathbb{N}$, $y \in \{0,\ldots,N\}$, and $\theta \in [0,1]^N$. Let -$F_y$ denote the set of all length-$y$ subsets of $\{0,\ldots,N\}$. -Then, \begin{equation*} \text{PoissonBinomial}(y~|~\theta) = \sum\limits_{A\in F_y} \prod\limits_{i\in A} \theta_i \prod\limits_{j\in A^c} (1-\theta_j). \end{equation*} +Suppose $N \in \mathbb{N}$, $n \in \{0,\ldots,N\}$, and $\theta \in [0,1]^N$. Let +$Sub_n$ denote the set of all size-$n$ subsets of $\{0,\ldots,N\}$^[In practice, +the calculation of this density can be done much quicker than the $\binom{N}{n}$ +the formula suggests.]. +Then, \begin{equation*} \text{PoissonBinomial}(y~|~\theta) = \sum_{A\in Sub_n} \prod_{i\in A} \theta_i \prod_{j\in A^c} (1-\theta_j). \end{equation*} + ### Distribution statement -`y ~ ` **`poisson_binomial`**`(theta)` +`n ~ ` **`poisson_binomial`**`(theta)` -Increment target log probability density with `poisson_binomial_lupmf(y | theta)`. +Increment target log probability density with `poisson_binomial_lupmf(n | theta)`. {{< since 2.40 >}} \index{{\tt \bfseries poisson\_binomial }!distribution statement|hyperpage} ### Stan functions - -\index{{\tt \bfseries poisson\_binomial\_lpmf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +\index{{\tt \bfseries poisson\_binomial\_lpmf }!{\tt (ints n \textbar vectors theta): real}|hyperpage} -`real` **`poisson_binomial_lpmf`**`(ints y | vectors theta)`
\newline +`real` **`poisson_binomial_lpmf`**`(ints n | vectors theta)`
\newline -The log poisson-binomial probability mass of `y` successes in +The log poisson-binomial probability mass of `n` successes in `N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., `theta[N]` {{< since 2.40 >}} - -\index{{\tt \bfseries poisson\_binomial\_lupmf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +\index{{\tt \bfseries poisson\_binomial\_lupmf }!{\tt (ints n \textbar vectors theta): real}|hyperpage} -`real` **`poisson_binomial_lupmf`**`(ints y | vectors theta)`
\newline +`real` **`poisson_binomial_lupmf`**`(ints n | vectors theta)`
\newline -The log poisson-binomial probability mass of `y` successes in +The log poisson-binomial probability mass of `n` successes in `N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., `theta[N]` dropping constant additive terms {{< since 2.40 >}} - -\index{{\tt \bfseries poisson\_binomial\_cdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +\index{{\tt \bfseries poisson\_binomial\_cdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage} -`real` **`poisson_binomial_cdf`**`(ints y | vectors theta)`
\newline +`real` **`poisson_binomial_cdf`**`(ints n | vectors theta)`
\newline -The poisson-binomial cumulative distribution function of `y` successes in +The poisson-binomial cumulative distribution function of `n` successes in `N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., `theta[N]` {{< since 2.40 >}} - -\index{{\tt \bfseries poisson\_binomial\_lcdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +\index{{\tt \bfseries poisson\_binomial\_lcdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage} -`real` **`poisson_binomial_lcdf`**`(ints y | vectors theta)`
\newline +`real` **`poisson_binomial_lcdf`**`(ints n | vectors theta)`
\newline -The log of the poisson-binomial cumulative distribution function of `y` successes in +The log of the poisson-binomial cumulative distribution function of `n` successes in `N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., `theta[N]` {{< since 2.40 >}} - -\index{{\tt \bfseries poisson\_binomial\_lccdf }!{\tt (ints y \textbar vectors theta): real}|hyperpage} + +\index{{\tt \bfseries poisson\_binomial\_lccdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage} -`real` **`poisson_binomial_lccdf`**`(ints y | vectors theta)`
\newline +`real` **`poisson_binomial_lccdf`**`(ints n | vectors theta)`
\newline The log of the poisson-binomial complementary cumulative distribution function -of `y` successes in `N = size(theta)` independent trials with probabilities of +of `n` successes in `N = size(theta)` independent trials with probabilities of success `theta[1]`, ..., `theta[N]` {{< since 2.40 >}} diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index 3ada60705..d1c8c2c97 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -3296,27 +3296,27 @@ pagetitle: Alphabetical Index **poisson_binomial_cdf**: - -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-de5136ae9ac628c68b411470f4a3b6f5ab2714b1) (bounded_discrete_distributions.html)
+ -
[`(ints n | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-e66030c1892345418de30c136c86a2da5b8ac9a5) (bounded_discrete_distributions.html)
**poisson_binomial_lccdf**: - -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-3ab93b8f233feb6f17d02d52bc1b2ad26499e09e) (bounded_discrete_distributions.html)
+ -
[`(ints n | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-a59f57b0982b1a3044bf546046af18d15789e43d) (bounded_discrete_distributions.html)
**poisson_binomial_lcdf**: - -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-2a4c06b205deaf2e48771b8ef9bda88f34064c18) (bounded_discrete_distributions.html)
+ -
[`(ints n | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-8569a8fe8196ab50641a92b8210303262a07971b) (bounded_discrete_distributions.html)
**poisson_binomial_lpmf**: - -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-bc556ef2af9faa87adcc083eda16f4da652a6c62) (bounded_discrete_distributions.html)
+ -
[`(ints n | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-3057454ff3ac5b4c322ec8929fdd63b132235e75) (bounded_discrete_distributions.html)
**poisson_binomial_lupmf**: - -
[`(ints y | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-a7269ded0d2437bb4b6077732487389a37e21af4) (bounded_discrete_distributions.html)
+ -
[`(ints n | vectors theta) : real`](bounded_discrete_distributions.qmd#index-entry-971c6a169fb16a00281fd6392974034022d228dc) (bounded_discrete_distributions.html)
**poisson_binomial_rng**: