Distribution Gallery: Add HalfStudentT (#541)

docs/examples/gallery/halfcauchy.md

@@ -68,8 +68,8 @@ $$
 
 **Common Alternatives:**
 
-- [Half-Student's t](half_students_t.md) - The Half-Cauchy distribution is a special case of the Half-Student's t-distribution with $\nu=1$.
-- [Half-Normal](half_normal.md) - A distribution that considers only the positive half of the normal distribution.
+- [Half-Student's t](halfstudentt.md) - The Half-Cauchy distribution is a special case of the Half-Student's t-distribution with $\nu=1$.
+- [Half-Normal](halfnormal.md) - A distribution that considers only the positive half of the normal distribution.
 
 **Related Distributions:**
 

docs/examples/gallery/halfnormal.md

@@ -121,7 +121,7 @@ where erf is the [error function](https://en.wikipedia.org/wiki/Error_function).
 **Related Distributions:**
 
 - [Normal](normal.md) - The parent distribution from which the Half-Normal is derived.
-- [Half-Student's t](half_students_t.md) - As $\nu \to \infty$, the Half-Student's t-distribution converges to the Half-Normal distribution.
+- [Half-Student's t](halfstudentt.md) - As $\nu \to \infty$, the Half-Student's t-distribution converges to the Half-Normal distribution.
 - [Truncated Normal](truncated_normal.md) - A Half-Normal distribution can be considered a special case of the Truncated Normal distribution with mean $0$ and lower bound $0$.
 ```
 

docs/examples/gallery/halfstudentt.md

@@ -0,0 +1,149 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+# Half-Student's t Distribution
+
+<audio controls> <source src="../../_static/halfstudentt.mp3" type="audio/mpeg"> This browser cannot play the pronunciation audio file for this distribution. </audio>
+
+The Half-Student's t distribution, also known as the half-t distribution, is a continuous probability distribution that is derived from the Student's t distribution but is restricted to only positive values. It is characterized by two parameters: the degrees of freedom ($\nu$) and the scale parameter ($\sigma$), which determines the width of the distribution. The smaller the value of $\nu$, the heavier the tails of the distribution.
+
+In Bayesian statistics, the Half-Student's t distribution is often used as a prior for scale parameters.
+
+## Parametrization
+
+The Half-Student's t distribution has 2 alternative parameterizations. In terms of $\nu$ and $\sigma$, or in terms of $\nu$ and $\lambda$.
+
+The link between the 2 alternatives is given by:
+
+$$
+\begin{align*}
+\lambda & = \frac{1}{\sigma^2}
+\end{align*}
+$$
+
+where $\sigma$ is the standard deviation as $\nu$ increases, and $\lambda$ is the precision as $\nu$ increases.
+
+## Probability Density Function (PDF):
+
+::::::{tab-set}
+:class: full-width
+
+:::::{tab-item} Parameters $\nu$ and $\sigma$
+:sync: nu_sigma
+```{jupyter-execute}
+:hide-code:
+
+from preliz import HalfStudentT, style
+style.use('preliz-doc')
+nus = [2., 5., 5.]
+sigmas = [1., 1., 2.]
+
+for nu, sigma in zip(nus, sigmas):
+    HalfStudentT(nu, sigma).plot_pdf(support=(0, 5))
+```
+:::::
+
+:::::{tab-item} Parameters $\nu$ and $\lambda$
+:sync: nu_lambda
+
+```{jupyter-execute}
+:hide-code:
+
+lambdas = [1., 1., 0.25]
+for nu, lam in zip(nus, lambdas):
+    HalfStudentT(nu, lam=lam).plot_pdf(support=(0, 5))
+```
+:::::
+::::::
+
+## Cumulative Distribution Function (CDF):
+
+::::::{tab-set}
+:class: full-width
+
+:::::{tab-item} Parameters $\nu$ and $\sigma$
+:sync: nu_sigma
+```{jupyter-execute}
+:hide-code:
+
+for nu, sigma in zip(nus, sigmas):
+    HalfStudentT(nu, sigma).plot_cdf(support=(0, 5))
+```
+:::::
+
+:::::{tab-item} Parameters $\nu$ and $\lambda$
+:sync: nu_lambda
+
+```{jupyter-execute}
+:hide-code:
+
+for nu, lam in zip(nus, lambdas):
+    HalfStudentT(nu, lam=lam).plot_cdf(support=(0, 5))
+```
+:::::
+::::::
+
+## Key properties and parameters:
+
+```{eval-rst}
+========  ==========================================
+Support   :math:`x \in [0, \infty)`
+Mean      .. math::
+                2\sigma\sqrt{\frac{\nu}{\pi}}\
+                \frac{\Gamma\left(\frac{\nu+1}{2}\right)}
+                {\Gamma\left(\frac{\nu}{2}\right)(\nu-1)}\, \text{for } \nu > 2
+Variance  .. math::
+                \sigma^2\left(\frac{\nu}{\nu - 2}-\
+                \frac{4\nu}{\pi(\nu-1)^2}\left(\frac{\Gamma\left(\frac{\nu+1}{2}\right)}
+                {\Gamma\left(\frac{\nu}{2}\right)}\right)^2\right) \text{for } \nu > 2\, \infty\
+                \text{for } 1 < \nu \le 2\, \text{otherwise undefined}
+========  ==========================================
+```
+
+**Probability Density Function (PDF):**
+
+$$
+f(x \mid \sigma,\nu) =
+    \frac{2\;\Gamma\left(\frac{\nu+1}{2}\right)}
+    {\Gamma\left(\frac{\nu}{2}\right)\sqrt{\nu\pi\sigma^2}}
+    \left(1+\frac{1}{\nu}\frac{x^2}{\sigma^2}\right)^{-\frac{\nu+1}{2}}
+$$
+
+where $\Gamma$ is the [gamma function](https://en.wikipedia.org/wiki/Gamma_function).
+
+**Cumulative Distribution Function (CDF):**
+
+$$
+F(x \mid \sigma,\nu) = 
+\begin{cases} 
+\frac{1}{2} \cdot I_{\frac{\nu}{x^2 + \nu}}\left(\frac{\nu}{2}, \frac{1}{2}\right) & \text{if } x \geq 0 \\
+0 & \text{if } x < 0
+\end{cases}
+$$
+
+where $I_x(a, b)$ denotes the [regularized incomplete beta function](https://en.wikipedia.org/wiki/Beta_function#Incomplete_beta_function).
+
+```{seealso}
+:class: seealso
+
+**Common Alternatives:**
+
+- [Half-Cauchy](halfcauchy.md) - The Half-Cauchy distribution is a special case of the Half-Student's t distribution with $\nu = 1$.
+- [Half-Normal](halfnormal.md) - As $\nu \to \infty$, the Half-Student's t distribution approaches the Half-Normal distribution.
+
+**Related Distributions:**
+
+- [Student's t](studentt.md) - The Student's t distribution is the parent distribution from which the Half-Student's t distribution is derived.
+```
+
+## References
+
+- [Wikipedia - Folded-t and Half-t Distributions](https://en.wikipedia.org/wiki/Folded-t_and_half-t_distributions)
+- [Wikipedia - Student's t-distribution](https://en.wikipedia.org/wiki/Student%27s_t-distribution)

docs/gallery_content.rst

@@ -139,7 +139,7 @@ Continuous Distributions
       Half-Normal
 
    .. grid-item-card::
-      :link: ./api_reference.html#preliz.distributions.halfstudentt.HalfStudentT
+      :link: ./examples/gallery/halfstudentt.html
       :text-align: center
       :shadow: none
       :class-card: example-gallery

docs/pronuanciation.py

@@ -10,6 +10,7 @@
         "Exponential",
         "HalfCauchy",
         "HalfNormal",
+        "HalfStudentT",
         "Hurdle",
         "InverseGamma",
         "Logistic",

preliz/distributions/halfstudentt.py

@@ -46,17 +46,17 @@ class HalfStudentT(Continuous):
     Support   :math:`x \in [0, \infty)`
     Mean      .. math::
                   2\sigma\sqrt{\frac{\nu}{\pi}}\
-                  \frac{\Gamma\left(\frac{\nu+1}{2}\right)}\
+                  \frac{\Gamma\left(\frac{\nu+1}{2}\right)}
                   {\Gamma\left(\frac{\nu}{2}\right)(\nu-1)}\, \text{for } \nu > 2
     Variance  .. math::
                   \sigma^2\left(\frac{\nu}{\nu - 2}-\
-                  \frac{4\nu}{\pi(\nu-1)^2}\left(\frac{\Gamma\left(\frac{\nu+1}{2}\right)}\
+                  \frac{4\nu}{\pi(\nu-1)^2}\left(\frac{\Gamma\left(\frac{\nu+1}{2}\right)}
                   {\Gamma\left(\frac{\nu}{2}\right)}\right)^2\right) \text{for } \nu > 2\, \infty\
                   \text{for } 1 < \nu \le 2\, \text{otherwise undefined}
     ========  ==========================================
 
     HalfStudentT distribution has 2 alternative parameterizations. In terms of nu and
-    sigma (standard deviation as nu increases) or nu lam (precision as nu increases).
+    sigma (standard deviation as nu increases) or nu and lam (precision as nu increases).
 
     The link between the 2 alternatives is given by