From e613494ab540145a42dd6e0dea948540a4fcca1a Mon Sep 17 00:00:00 2001
From: Alejandro Icazatti <ale.icazatti@gmail.com>
Date: Thu, 31 Oct 2024 08:50:10 -0300
Subject: [PATCH] Distributions Gallery: Add VonMises (#574)

---
 docs/examples/gallery/vonmises.md | 89 +++++++++++++++++++++++++++++++
 docs/gallery_content.rst          |  2 +-
 2 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/gallery/vonmises.md

diff --git a/docs/examples/gallery/vonmises.md b/docs/examples/gallery/vonmises.md
new file mode 100644
index 00000000..bfa54646
--- /dev/null
+++ b/docs/examples/gallery/vonmises.md
@@ -0,0 +1,89 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+# Von Mises Distribution
+
+<audio controls> <source src="../../_static/vonmises.mp3" type="audio/mpeg"> This browser cannot play the pronunciation audio file for this distribution. </audio>
+
+The Von Mises distribution is a continuous probability distribution on the unit circle. It is characterized by two parameters: $\mu$ and $\kappa$, which are the mean direction and concentration parameter, respectively.
+
+The Von Mises distribution is the circular analogue of the normal distribution, and it is used to model circular data, such as wind directions, compass bearings, or angles. 
+
+## Probability Density Function (PDF):
+
+```{code-cell}
+---
+tags: [remove-input]
+mystnb:
+  image:
+    alt: Von Mises Distribution PDF
+---
+import numpy as np
+
+from preliz import style, VonMises
+style.use('preliz-doc')
+mus = [0., 0., 0.,  -2.5]
+kappas = [.01, 0.5, 4., 2.]
+for mu, kappa in zip(mus, kappas):
+    VonMises(mu, kappa).plot_pdf(support=(-np.pi,np.pi))
+```
+
+## Cumulative Distribution Function (CDF):
+
+```{code-cell}
+---
+tags: [remove-input]
+mystnb:
+  image:
+    alt: Von Mises Distribution CDF
+---
+
+for mu, kappa in zip(mus, kappas):
+    VonMises(mu, kappa).plot_cdf(support=(-np.pi,np.pi))
+```
+
+## Key properties and parameters:
+
+```{eval-rst}
+========  ==========================================
+Support   :math:`x \in (-\pi, \pi)`
+Mean      :math:`\mu`
+Variance  :math:`1 - I_1(\kappa) / I_0(\kappa)`
+========  ==========================================
+```
+
+**Probability Density Function (PDF):**
+
+$$
+f(x|\mu, \kappa) = \frac{e^{\kappa \cos(x - \mu)}}{2\pi I_0(\kappa)}
+$$
+
+where $I_0(\kappa)$ is the [modified Bessel function of the first kind](https://en.wikipedia.org/wiki/Bessel_function#Modified_Bessel_functions:_I%CE%B1,_K%CE%B1).
+
+**Cumulative Distribution Function (CDF):**
+
+The Von Mises distribution does not have an analytical expression for the CDF. However, it can be evaluated numerically by integrating the PDF in the interval $(-\pi, x)$:
+
+$$
+F(x|\mu, \kappa) = \frac{1}{2\pi I_0(\kappa)} \int_{-\pi}^{x} e^{\kappa \cos(t - \mu)} dt
+$$
+
+```{seealso}
+:class: seealso
+
+**Related Distributions:**
+
+- [Normal Distribution](normal.md) - When $\kappa \to \infty$, the Von Mises distribution approximates the normal distribution.
+- [Uniform Distribution](uniform.md) - When $\kappa = 0$, the Von Mises distribution converges to the uniform distribution in the interval $(-\pi, \pi)$.
+```
+
+## References
+
+- [Wikipedia - Von Mises distribution](https://en.wikipedia.org/wiki/Von_Mises_distribution)
diff --git a/docs/gallery_content.rst b/docs/gallery_content.rst
index e9a0ff94..a76e5d7b 100644
--- a/docs/gallery_content.rst
+++ b/docs/gallery_content.rst
@@ -355,7 +355,7 @@ Continuous Distributions
       Uniform
 
    .. grid-item-card::
-      :link: ./api_reference.html#preliz.distributions.vonmises.VonMises
+      :link: ./examples/gallery/vonmises.html
       :text-align: center
       :shadow: none
       :class-card: example-gallery