Document poisson-binomial distribution

src/functions-reference/bounded_discrete_distributions.qmd

@@ -353,6 +353,99 @@ 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}
+
+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}$, $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
+
+
+`n ~ ` **`poisson_binomial`**`(theta)`
+
+Increment target log probability density with `poisson_binomial_lupmf(n | theta)`.
+{{< since 2.40 >}}
+<!-- real; poisson_binomial ~; -->
+\index{{\tt \bfseries poisson\_binomial }!distribution statement|hyperpage}
+
+### Stan functions
+
+<!-- real; poisson_binomial_lpmf; (ints n | vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_lpmf }!{\tt (ints n \textbar vectors theta): real}|hyperpage}
+
+`real` **`poisson_binomial_lpmf`**`(ints n | vectors theta)`<br>\newline
+
+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 >}}
+
+
+<!-- real; poisson_binomial_lupmf; (ints n | vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_lupmf }!{\tt (ints n \textbar vectors theta): real}|hyperpage}
+
+`real` **`poisson_binomial_lupmf`**`(ints n | vectors theta)`<br>\newline
+
+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 >}}
+
+
+<!-- real; poisson_binomial_cdf; (ints n | vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_cdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage}
+
+`real` **`poisson_binomial_cdf`**`(ints n | vectors theta)`<br>\newline
+
+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 >}}
+
+
+<!-- real; poisson_binomial_lcdf; (ints n | vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_lcdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage}
+
+`real` **`poisson_binomial_lcdf`**`(ints n | vectors theta)`<br>\newline
+
+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 >}}
+
+
+<!-- real; poisson_binomial_lccdf; (ints n | vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_lccdf }!{\tt (ints n \textbar vectors theta): real}|hyperpage}
+
+`real` **`poisson_binomial_lccdf`**`(ints n | vectors theta)`<br>\newline
+
+The log of the poisson-binomial complementary cumulative distribution function
+of `n` successes in `N = size(theta)` independent trials with probabilities of
+success `theta[1]`, ..., `theta[N]`
+{{< since 2.40 >}}
+
+
+<!-- int; poisson_binomial_rng; (vectors theta); -->
+\index{{\tt \bfseries poisson\_binomial\_rng }!{\tt (vectors theta): int}|hyperpage}
+
+`int` **`poisson_binomial_rng`**`(vectors theta)`<br>\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