Skip to content

Commit

Permalink
Distribution Gallery: Add HalfStudentT (arviz-devs#541)
Browse files Browse the repository at this point in the history
  • Loading branch information
aleicazatti authored Sep 26, 2024
1 parent fcae8d1 commit 097d880
Show file tree
Hide file tree
Showing 7 changed files with 157 additions and 7 deletions.
Binary file added docs/audios/halfstudentt.mp3
Binary file not shown.
4 changes: 2 additions & 2 deletions docs/examples/gallery/halfcauchy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down
2 changes: 1 addition & 1 deletion docs/examples/gallery/halfnormal.md
Original file line number Diff line number Diff line change
Expand Up @@ -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$.
```

Expand Down
149 changes: 149 additions & 0 deletions docs/examples/gallery/halfstudentt.md
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 1 addition & 1 deletion docs/gallery_content.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/pronuanciation.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"Exponential",
"HalfCauchy",
"HalfNormal",
"HalfStudentT",
"Hurdle",
"InverseGamma",
"Logistic",
Expand Down
6 changes: 3 additions & 3 deletions preliz/distributions/halfstudentt.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 097d880

Please sign in to comment.