From e4580b662cc311836f4011ad56df7cb91bfc00c0 Mon Sep 17 00:00:00 2001
From: Alejandro Icazatti <ale.icazatti@gmail.com>
Date: Wed, 18 Dec 2024 10:09:18 -0300
Subject: [PATCH] Distributions Gallery: Add Dirichlet (#608)

* Distributions Gallery: Add Dirichlet

* ignore warnings

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

* Update dirichlet.md

---------

Co-authored-by: Osvaldo A Martin <aloctavodia@gmail.com>
---
 docs/examples/gallery/dirichlet.md | 95 ++++++++++++++++++++++++++++++
 docs/gallery_content.rst           |  2 +-
 2 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/gallery/dirichlet.md

diff --git a/docs/examples/gallery/dirichlet.md b/docs/examples/gallery/dirichlet.md
new file mode 100644
index 00000000..4a1a38f4
--- /dev/null
+++ b/docs/examples/gallery/dirichlet.md
@@ -0,0 +1,95 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+# Dirichlet Distribution
+
+<audio controls> <source src="../../_static/dirichlet.mp3" type="audio/mpeg"> This browser cannot play the pronunciation audio file for this distribution. </audio>
+
+The Dirichlet distribution is a multivariate continuous probability distribution defined on the standard $K$-simplex, where $K \geq 2$. It is parameterized by a vector of positive concentration parameters $\alpha = (\alpha_1, \alpha_2, \ldots, \alpha_K)$, which control the shape of the distribution. The support of the Dirichlet distribution consists of vectors whose entries sum to one, making it particularly useful for modeling probabilities or proportions.
+
+A key property of the Dirichlet distribution is that it generalizes the Beta distribution to multiple dimensions. When used as a prior distribution in Bayesian statistics, it becomes the conjugate prior of both the categorical and multinomial distributions. This conjugacy simplifies inference, particularly in hierarchical models and Bayesian mixture models. For example, the posterior distribution of a categorical model with a Dirichlet prior remains Dirichlet after observing new data.
+
+## Key properties and parameters
+
+```{eval-rst}
+========  ===============================================
+Support   :math:`x_i \in (0, 1)` for :math:`i \in \{1, \ldots, K\}` such that :math:`\sum x_i = 1`
+Mean      :math:`\dfrac{a_i}{\sum a_i}`
+Variance  :math:`\dfrac{a_i - \sum a_0}{a_0^2 (a_0 + 1)}` where :math:`a_0 = \sum a_i`
+========  ===============================================
+```
+
+**Parameters:**
+
+- $\alpha$ : (array of floats) Concentration parameters $\alpha = (\alpha_1, \alpha_2, \ldots, \alpha_K)$ where $\alpha_i > 0$.
+
+### Probability Density Function (PDF)
+
+$$
+f(\mathbf{x}|\mathbf{a}) =
+    \frac{\Gamma(\sum_{i=1}^k a_i)}{\prod_{i=1}^k \Gamma(a_i)}
+    \prod_{i=1}^k x_i^{a_i - 1}
+$$
+
+```{code-cell}
+---
+tags: [remove-input]
+mystnb:
+  image:
+    alt: Dirichlet Distribution PDF
+---
+import logging
+import matplotlib.pyplot as plt
+from preliz import Dirichlet
+
+logger = logging.getLogger()
+logger.disabled = True
+
+_, axes = plt.subplots(2, 2)
+alphas = [[0.5, 0.5, 0.5], [1, 1, 1], [5, 5, 5], [5, 2, 1]]
+for alpha, ax in zip(alphas, axes.ravel()):
+    Dirichlet(alpha).plot_pdf(marginals=False, ax=ax)
+
+logger.disabled = False
+```
+
+### Cumulative Distribution Function (CDF)
+
+
+The Dirichlet joint CDF does not have a known analytical solution due to the complexity of integrating its multivariate density over the simplex. However, each marginal distribution is a Beta distribution with a well-defined CDF that can be computed directly.
+
+```{code-cell}
+---
+tags: [remove-input]
+mystnb:
+  image:
+    alt: Dirichlet Distribution CDF
+---
+
+for alpha in alphas:
+    Dirichlet(alpha).plot_cdf()
+```
+
+```{seealso}
+:class: seealso
+
+**Common Alternatives:**
+
+- [Beta Distribution](beta.md) - When $K = 2$, the Dirichlet distribution reduces to the Beta distribution with $\alpha = \alpha_1$ and $\beta = \alpha_2$.
+
+**Related Distributions:**
+
+- [Gamma Distribution](gamma.md) -  A Dirichlet distribution can be constructed from a normalized set of $K$ independent gamma-distributed random variables.
+- [Categorical Distribution](categorical.md) - A discrete distribution for modeling outcomes with multiple categories, often used in conjunction with a Dirichlet prior in Bayesian settings.
+```
+
+## References
+
+- [Wikipedia - Dirichlet distribution](https://en.wikipedia.org/wiki/Dirichlet_distribution)
diff --git a/docs/gallery_content.rst b/docs/gallery_content.rst
index 30decfac..1871d45f 100644
--- a/docs/gallery_content.rst
+++ b/docs/gallery_content.rst
@@ -557,7 +557,7 @@ Continuous Multivariate Distributions
    :gutter: 2 2 3 3
 
    .. grid-item-card::
-      :link: ./distributions.html#preliz.distributions.continuous_multivariate.Dirichlet
+      :link: ./examples/gallery/dirichlet.html
       :text-align: center
       :shadow: none
       :class-card: example-gallery