Modules

class VonMisesDistribution(Continuous2PiInterval):
    r"""von Mises distribution.

    The von Mises distribution is a continuous probability distribution on the
    circle. It is a close approximation to the wrapped normal distribution,
    which is the circular analogue of the normal distribution.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_2pi_interval import (
        ... VonMisesDistribution
        ... )
        >>> x = np.linspace(-np.pi, np.pi, 1000)
        >>> y_05 = VonMisesDistribution(x, mu=0, kappa=0.5).__eval__
        >>> y_07 = VonMisesDistribution(x, mu=0, kappa=0.7).__eval__
        >>> y_09 = VonMisesDistribution(x, mu=0, kappa=0.9).__eval__
        >>> fig = plt.figure()
        >>> ax = plt.subplot()
        >>> _  = ax.plot(x, y_05, label=r"$\kappa=0.5$")
        >>> _  = ax.plot(x, y_07, label=r"$\kappa=0.7$")
        >>> _  = ax.plot(x, y_09, label=r"$\kappa=0.9$")
        >>> _  = ax.set_xlabel("x")
        >>> _  = ax.set_ylabel("f(x)")
        >>> _  = ax.legend()
        >>> plt.savefig("VonMisesDistribution.png", dpi=300, transparent=True)


    Notes:
        The von Mises distribution is defined as follows for probability density:

        $$
        f(x;\mu,\kappa) = \frac{e^{\kappa \cos(x-\mu)}}{2\pi I_0(\kappa)}
        $$

        where $x \in [-\pi, \pi]$ and $\mu \in [-\pi, \pi]$. The parameter
        $\kappa \in [0, \infty)$ controls the concentration of the distribution
        around $\mu$. The function $I_0$ is the modified Bessel function of the
        first kind and order zero.


    Args:
        *x (UniversalArray): The points at which to evaluate the distribution.
        mu (float): The mean of the distribution. Defaults to 0.
        kappa (float): The concentration of the distribution around mu.
            Defaults to 1.
    """

    def probability_density_function(self) -> UniversalArray:
        """Probability density function of the von Mises distribution."""
        return np.exp(self.kappa * np.cos(self._x - self.mu)) / (
            2 * np.pi * special.i0(self.kappa)
        )

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Summary statistics of the von Mises distribution."""

        def _mode() -> float | tuple[float, float]:
            """Mode of the von Mises distribution."""
            return self.mu

        return SummaryStatisticsAPI(
            mean=self.mu,
            variance=1 - special.i1(self.kappa) / special.i0(self.kappa),
            mode=_mode(),
            doc=self.__doc__,
        )

class WrappedAsymLaplaceDistribution(Continuous2PiInterval):
    r"""Wrapped asymmetric Laplace distribution.

    The wrapped (asymmetric) Laplace distribution is a continuous probability
    distribution on the circle. It is a close approximation to the wrapped normal
    distribution, which is the circular analogue of the normal distribution.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_2pi_interval import (
        ... WrappedAsymLaplaceDistribution
        ... )
        >>> x = np.linspace(-np.pi, np.pi, 1000)
        >>> y_05 = WrappedAsymLaplaceDistribution(
        ... x,
        ... mu=0,
        ... lambda_=0.5,
        ... kappa=0.5,
        ... ).__eval__
        >>> y_07 = WrappedAsymLaplaceDistribution(
        ... x,
        ... mu=0,
        ... lambda_=0.7,
        ... kappa=0.7,
        ... ).__eval__
        >>> y_09 = WrappedAsymLaplaceDistribution(
        ... x,
        ... mu=0,
        ... lambda_=0.9,
        ... kappa=0.9,
        ... ).__eval__
        >>> fig = plt.figure()
        >>> ax = plt.subplot()
        >>> _  = ax.plot(x, y_05, label=r"$\lambda=0.5$")
        >>> _  = ax.plot(x, y_07, label=r"$\lambda=0.7$")
        >>> _  = ax.plot(x, y_09, label=r"$\lambda=0.9$")
        >>> _  = ax.set_xlabel("x")
        >>> _  = ax.set_ylabel("f(x)")
        >>> _  = ax.legend()
        >>> plt.savefig("WrappedAsymLaplaceDistribution.png", dpi=300, transparent=True)

    Notes:
        The wrapped Laplace distribution is defined as follows for probability
        density:

        $$
        \begin{aligned}f_{WAL}(\theta ;m,\lambda ,\kappa )&=
        \sum _{k=-\infty }^{\infty }f_{AL}(\theta +2\pi k,m,\lambda ,\kappa )\\[10pt]
        &={\dfrac {\kappa \lambda }{\kappa ^{2}+1}}{\begin{cases}
        {\dfrac {e^{-(\theta -m)\lambda \kappa }}
        {1-e^{-2\pi \lambda \kappa }}}-{\dfrac {e^{(\theta -m)\lambda /\kappa }}
        {1-e^{2\pi \lambda /\kappa }}}&{\text{if }}
        \theta \geq m\\[12pt]{\dfrac {e^{-(\theta -m)\lambda \kappa }}
        {e^{2\pi \lambda \kappa }-1}}-{\dfrac {e^{(\theta -m)\lambda /\kappa }}
        {e^{-2\pi \lambda /\kappa }-1}}&{\text{if }}\theta <m\end{cases}}\end{aligned}
        $$

        where $x \in [-\pi, \pi]$ and $\mu \in [-\pi, \pi]$. The parameter
        $\kappa \in [0, \infty)$ controls the concentration of the distribution
        around $\mu$. The function $I_0$ is the modified Bessel function of the
        first kind and order zero.[^1]

        [^1]: Wrapped asymmetric Laplace distribution. (2022, January 24).
            _In Wikipedia._
            https://en.wikipedia.org/wiki/Wrapped_asymmetric_Laplace_distribution

    Args:
        x: The points at which to evaluate the distribution.
        mu: The mean of the distribution.
        lambda_: The scale parameter of the distribution.
        kappa: The concentration of the distribution around mu.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        lambda_: float = 1,
        kappa: float = 1,
    ) -> None:
        r"""Initialize a wrapped Laplace distribution.

        Args:
            *x (UniversalArray): The points at which to evaluate the distribution.
            mu (float): The mean of the distribution. Defaults to 0.
            lambda_ (float): The scale parameter of the distribution. Defaults to 1.
            kappa (float): The concentration of the distribution around mu.
                Defaults to 1.
        """
        super().__init__(*x, mu=mu, kappa=kappa)
        self.lambda_ = lambda_

    def probability_density_function(self) -> UniversalArray:
        """Probability density function of the wrapped Laplace distribution."""
        part_1 = (
            self.kappa
            * self.lambda_
            / (self.kappa**2 + 1)
            * (
                np.exp(-(self._x - self.mu) * self.lambda_ * self.kappa)
                / (1 - np.exp(-2 * np.pi * self.lambda_ * self.kappa))
                - np.exp((self._x - self.mu) * self.lambda_ / self.kappa)
                / (1 - np.exp(2 * np.pi * self.lambda_ / self.kappa))
            )
        )
        part_2 = (
            self.kappa
            * self.lambda_
            / (self.kappa**2 + 1)
            * (
                np.exp(-(self._x - self.mu) * self.lambda_ * self.kappa)
                / (np.exp(2 * np.pi * self.lambda_ * self.kappa) - 1)
                - np.exp((self._x - self.mu) * self.lambda_ / self.kappa)
                / (np.exp(-2 * np.pi * self.lambda_ / self.kappa) - 1)
            )
        )

        # Combine the two parts
        return np.where(self._x >= self.mu, part_1, part_2)

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Summary statistics of the wrapped Laplace distribution."""
        return SummaryStatisticsAPI(
            mean=self.mu,
            variance=1
            - self.lambda_**2
            / np.sqrt(
                (1 / self.kappa**2 + self.lambda_**2)
                * (self.kappa**2 + self.lambda_**2),
            ),
            mode=None,
            doc=self.__doc__,
        )

class KumaraswamyDistribution(ContinuousBoundedInterval):
    r"""Kumaraswamy distribution.

    The Kumaraswamy distribution is a continuous probability distribution with
    support on the interval [0, 1]. It is a generalization of the beta
    distribution.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_bounded_interval import (
        ... KumaraswamyDistribution
        ... )
        >>> x = np.linspace(0, 1, 1000)
        >>> kumaraswamy_a1_b1 = KumaraswamyDistribution(x, a=1, b=1).__eval__
        >>> kumaraswamy_a2_b2 = KumaraswamyDistribution(x, a=2, b=2).__eval__
        >>> kumaraswamy_a1_b2 = KumaraswamyDistribution(x, a=1, b=2).__eval__
        >>> kumaraswamy_a2_b1 = KumaraswamyDistribution(x, a=2, b=1).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, kumaraswamy_a1_b1, label=r"$a=1, b=1$")
        >>> _ = ax.plot(x, kumaraswamy_a2_b2, label=r"$a=2, b=2$")
        >>> _ = ax.plot(x, kumaraswamy_a1_b2, label=r"$a=1, b=2$")
        >>> _ = ax.plot(x, kumaraswamy_a2_b1, label=r"$a=2, b=1$")
        >>> _ = ax.legend()
        >>> plt.savefig("KumaraswamyDistribution.png", dpi=300, transparent=True)
        >>> plt.close()

        >>> # CDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_bounded_interval import (
        ... KumaraswamyDistribution
        ... )
        >>> x = np.linspace(0, 1, 1000)
        >>> kumaraswamy_a1_b1 = KumaraswamyDistribution(
        ... x,
        ... a=1,
        ... b=1,
        ... cumulative=True,
        ... ).__eval__
        >>> kumaraswamy_a2_b2 = KumaraswamyDistribution(
        ... x,
        ... a=2,
        ... b=2,
        ... cumulative=True,
        ... ).__eval__
        >>> kumaraswamy_a1_b2 = KumaraswamyDistribution(
        ... x,
        ... a=1,
        ... b=2,
        ... cumulative=True,
        ... ).__eval__
        >>> kumaraswamy_a2_b1 = KumaraswamyDistribution(
        ... x,
        ... a=2,
        ... b=1,
        ... cumulative=True,
        ... ).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, kumaraswamy_a1_b1, label=r"$a=1, b=1$")
        >>> _ = ax.plot(x, kumaraswamy_a2_b2, label=r"$a=2, b=2$")
        >>> _ = ax.plot(x, kumaraswamy_a1_b2, label=r"$a=1, b=2$")
        >>> _ = ax.plot(x, kumaraswamy_a2_b1, label=r"$a=2, b=1$")
        >>> _ = ax.legend()
        >>> plt.savefig(
        ... "KumaraswamyDistribution-cml.png",
        ... dpi=300,
        ... transparent=True
        ... )

    Notes:
        The Kumaraswamy distribution is generally defined for the PDF as:

        $$
        f(x; a, b) = abx^{a-1}(1-x^a)^{b-1}
        $$

        where $a, b > 0$ and $0 \leq x \leq 1$. The CDF is given by:

        $$
        F(x; a, b) = 1 - (1 - x^a)^b
        $$

    Args:
        *x (UniversalArray): Input data, which can be only one  dimensional.
        a (float): The first shape parameter, which must be positive. Default is 1.
        b (float): The second shape parameter, which must be positive. Default is 1.
        cumulative (bool): If True, the cumulative distribution function is returned.
    """

    def __init__(
        self,
        *x: UniversalArray,
        a: float = 1,
        b: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the Kumaraswamy distribution."""
        if a <= 0:
            msg = "a"
            raise NotAPositiveNumberError(msg, a)
        if b <= 0:
            msg = "b"
            raise NotAPositiveNumberError(msg, b)
        super().__init__(*x, start=0, end=1, cumulative=cumulative)
        self.a = a
        self.b = b

    def probability_density_function(self) -> UniversalArray:
        """Calculate the probability density function of the Kumaraswamy distribution.

        Returns:
            UniversalArray: The value of the probability density function of the
                Kumaraswamy distribution.
        """
        return (
            self.a
            * self.b
            * self._x ** (self.a - 1)
            * (1 - self._x**self.a) ** (self.b - 1)
        )

    def cumulative_distribution_function(self) -> UniversalArray:
        """Calculate the cumulative distribution function of the Kumaraswamy distribution.

        Returns:
            UniversalArray: The value of the cumulative distribution function of the
                Kumaraswamy distribution.
        """  # noqa: E501
        return 1 - (1 - self._x**self.a) ** self.b

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Calculate the summary statistics of the Kumaraswamy distribution.

        Returns:
            SummaryStatisticsAPI: The summary statistics of the Kumaraswamy
                distribution.
        """
        mode = (
            (self.a - 1) / (self.a + self.b - 2) if self.a > 1 and self.b > 1 else None
        )
        mean = (self.b * gamma(1 + 1 / self.a) * gamma(self.a - 1)) / (
            self.a * gamma(self.a + self.b)
        )
        return SummaryStatisticsAPI(
            mean=mean,
            mode=mode,
            variance=None,
            doc=self.__doc__,
        )

class ChiSquaredDistribution(SemiContinuous):
    r"""Chi-square distribution.

    The chi-square distribution is a semi continuous probability distribution that is
    commonly used in statistics to model variables that are the sum of the squares of
    independent standard normal random variables. It is a transformation of the normal
    distribution, where the logarithm of the variable is normally distributed. The
    chi-square distribution has applications in various fields, such as finance,
    biology, and engineering.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_semi_infinite_interval import (
        ... ChiSquaredDistribution
        ... )
        >>> x = np.linspace(0, 15, 1000)
        >>> y_k_1 = ChiSquaredDistribution(x, k=1).__eval__
        >>> y_k_2 = ChiSquaredDistribution(x, k=2).__eval__
        >>> y_k_3 = ChiSquaredDistribution(x, k=3).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, y_k_1, label="k=1")
        >>> _ = ax.plot(x, y_k_2, label="k=2")
        >>> _ = ax.plot(x, y_k_3, label="k=3")
        >>> _ = ax.legend()
        >>> plt.savefig("ChiSquaredDistribution.png", dpi=300, transparent=True)

        >>> # CDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_semi_infinite_interval import (
        ... ChiSquaredDistribution
        ... )
        >>> x = np.linspace(0, 15, 1000)
        >>> y_k_1 = ChiSquaredDistribution(
        ... x,
        ... k=1,
        ... cumulative=True,
        ... ).__eval__
        >>> y_k_2 = ChiSquaredDistribution(
        ... x,
        ... k=2,
        ... cumulative=True,
        ... ).__eval__
        >>> y_k_3 = ChiSquaredDistribution(
        ... x,
        ... k=3,
        ... cumulative=True,
        ... ).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, y_k_1, label="k=1")
        >>> _ = ax.plot(x, y_k_2, label="k=2")
        >>> _ = ax.plot(x, y_k_3, label="k=3")
        >>> _ = ax.legend()
        >>> plt.savefig("ChiSquaredDistribution-cml.png", dpi=300, transparent=True)

    Notes:
        The chi-square distribution is generally defined for the PDF as:

        $$
        f(x | k) = \frac{1}{2^{k/2} \Gamma(k/2)} x^{k/2 - 1} \exp(-x/2)
        $$

        and for the CDF as:

        $$
        F(x | k) = \frac{1}{\Gamma(k/2)} \gamma(k/2, x/2)
        $$

        where $k$ is the degrees of freedom.

    Args:
        *x (UniversalArray): Input data, which can be only one  dimensional.
        k (float): Degrees of freedom. Defaults to 1.
        cumulative (bool): If True, the CDF is returned. Defaults to False.
    """

    def __init__(
        self,
        *x: UniversalArray,
        k: float = 1.0,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        if k <= 0:
            raise NotLargerThanZeroError(k)

        super().__init__(*x, cumulative=cumulative)
        self.k = k

    def probability_density_function(self) -> UniversalArray:
        """Return the probability density function."""
        return (
            1
            / (2 ** (self.k / 2) * gamma(self.k / 2))
            * self._x ** (self.k / 2 - 1)
            * np.exp(-self._x / 2)
        )

    def cumulative_distribution_function(self) -> UniversalArray:
        """Return the cumulative distribution function."""
        return 1 / gamma(self.k / 2) * gammainc(self.k / 2, self._x / 2)

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Return the summary statistics."""
        return SummaryStatisticsAPI(
            mean=self.k,
            variance=2 * self.k,
            mode=self.k - 2 if self.k > 2 else 0,  # noqa: PLR2004
            doc=self.__doc__,
        )

class DagumDistribution(ContinuousPure):
    r"""Dagum distribution.

    The Dagum distribution is a continuous probability distribution that is defined on
    the semi-infinite interval 0, ∞). It is a three-parameter distribution that is
    characterized by its shape, scale, and shape parameters. The Dagum distribution is
    used in various fields, including economics, finance, and engineering, to model
    data that is non-negative and skewed to the right. It has a probability density
    function (PDF) and a cumulative distribution function (CDF) that can be used to
    calculate various statistical measures, such as mean, variance, and mode.

    Notes:
        The Dagum distribution is generally defined for the PDF as:

        $$
        f(x | p, a, b) = \frac{p a^{p}}{x^{p + 1} \left[1 + \left(\frac{a}{b}
        x\right)^{p}\right]^{(p+1)/p}}
        $$

        and for the CDF as:

        $$
        F(x | p, a, b) = 1 - \left[1 + \left(\frac{a}{b} x\right)^{p}\right]^{-p}
        $$

        where $p$ is the shape parameter, $a$ is the scale parameter, and $b$ is the
        shape parameter.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_semi_infinite_interval import (
        ... DagumDistribution
        ... )
        >>> x = np.linspace(0, 10, 1000)
        >>> y_p_1_a_1_b_1 = DagumDistribution(x, p=1, a=1, b=1).__eval__
        >>> y_p_2_a_1_b_1 = DagumDistribution(x, p=2, a=1, b=1).__eval__
        >>> y_p_3_a_1_b_1 = DagumDistribution(x, p=3, a=1, b=1).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, y_p_1_a_1_b_1, label="p=1, a=1, b=1")
        >>> _ = ax.plot(x, y_p_2_a_1_b_1, label="p=2, a=1, b=1")
        >>> _ = ax.plot(x, y_p_3_a_1_b_1, label="p=3, a=1, b=1")
        >>> _ = ax.legend()
        >>> plt.savefig("DagumDistribution.png", dpi=300, transparent=True)

    Args:
        *x (UniversalArray): Input data, which can be only one  dimensional.
        p (float): Shape parameter. Must be greater than 0. Defaults to 1.
        a (float): Scale parameter. Must be greater than 0. Defaults to 1.
        b (float): Shape parameter. Must be greater than 0. Defaults to 1.

    Raises:
        NotLargerThanZeroError: If p, a, or b is not larger than 0.
    """

    def __init__(
        self,
        *x: UniversalArray,
        p: float = 1.0,
        a: float = 1.0,
        b: float = 1.0,
    ) -> None:
        """Initialize the function."""
        if p <= 0:
            msg = "p"
            raise NotLargerThanZeroError(msg, p)
        if a <= 0:
            msg = "a"
            raise NotLargerThanZeroError(msg, a)
        if b <= 0:
            msg = "b"
            raise NotLargerThanZeroError(msg, b)
        super().__init__(*x)
        self.p = p
        self.a = a
        self.b = b

    def probability_density_function(self) -> np.ndarray:
        """Return the probability density function."""
        return (
            self.p
            * self.a**self.p
            / (
                self._x ** (self.p + 1)
                * (1 + (self.a / self.b) ** self.p * self._x**self.p)
                ** ((self.p + 1) / self.p)
            )
        )

    def cumulative_distribution_function(self) -> np.ndarray:
        """Return the cumulative distribution function."""
        return 1 - (1 + (self.a / self.b) ** self.p * self._x**self.p) ** (-self.p)

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Return the summary statistics."""
        return SummaryStatisticsAPI(
            mean=self.a
            * gamma((self.p - 1) / self.p)
            * gamma((self.p + 1) / self.p)
            / gamma(self.p / self.p),
            variance=self.a**2
            * (
                gamma((self.p - 2) / self.p)
                * gamma((self.p + 1) / self.p)
                / gamma(self.p / self.p)
                - (
                    self.a
                    * gamma((self.p - 1) / self.p)
                    * gamma((self.p + 1) / self.p)
                    / gamma(self.p / self.p)
                )
                ** 2
            ),
            mode=self.a
            * ((self.p / self.b) ** (1 / self.p))
            * ((self.p - 1) / self.p) ** (1 / self.p),
            doc=self.__doc__,
        )

class LogNormalDistribution(SemiContinuousWSigma):
    r"""Log-normal distribution.

    The log-normal distribution is a semi continuous probability distribution that is
    commonly used in statistics to model variables that are the product of many small,
    independent factors. It is a transformation of the normal distribution, where the
    logarithm of the variable is normally distributed. The log-normal distribution has
    applications in various fields, such as finance, biology, and engineering.

    Examples:
        >>> # PDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_semi_infinite_interval import (
        ... LogNormalDistribution
        ... )
        >>> x = np.linspace(0, 5, 1000)
        >>> y_sigma_1 = LogNormalDistribution(x, sigma=1).__eval__
        >>> y_sigma_2 = LogNormalDistribution(x, sigma=2).__eval__
        >>> y_sigma_3 = LogNormalDistribution(x, sigma=3).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, y_sigma_1, label="sigma=1")
        >>> _ = ax.plot(x, y_sigma_2, label="sigma=2")
        >>> _ = ax.plot(x, y_sigma_3, label="sigma=3")
        >>> _ = ax.legend()
        >>> plt.savefig("LogNormalDistribution.png", dpi=300, transparent=True)

        >>> # CDF Example
        >>> import matplotlib.pyplot as plt
        >>> import numpy as np
        >>> from umf.functions.distributions.continuous_semi_infinite_interval import (
        ... LogNormalDistribution
        ... )
        >>> x = np.linspace(0, 5, 1000)
        >>> y_sigma_1 = LogNormalDistribution(
        ... x,
        ... sigma=1,
        ... cumulative=True,
        ... ).__eval__
        >>> y_sigma_2 = LogNormalDistribution(
        ... x,
        ... sigma=2,
        ... cumulative=True,
        ... ).__eval__
        >>> y_sigma_3 = LogNormalDistribution(
        ... x,
        ... sigma=3,
        ... cumulative=True,
        ... ).__eval__
        >>> fig = plt.figure()
        >>> ax = fig.add_subplot(111)
        >>> _ = ax.plot(x, y_sigma_1, label="sigma=1")
        >>> _ = ax.plot(x, y_sigma_2, label="sigma=2")
        >>> _ = ax.plot(x, y_sigma_3, label="sigma=3")
        >>> _ = ax.legend()
        >>> plt.savefig("LogNormalDistribution-cml.png", dpi=300, transparent=True)

    Notes:
        The log-normal distribution is generally defined for the PDF as:

        $$
        f(x | \mu, \sigma) = \frac{1}{x \sigma \sqrt{2\pi}}
          \exp\left(-\frac{(\ln x - \mu)^2}{2\sigma^2}\right)
        $$

        and for the CDF as:

        $$
        F(x | \mu, \sigma) = \frac{1}{2} \left[1 + \mathrm{erf}
        \left(\frac{\ln x - \mu}{\sigma \sqrt{2}}\right)\right]
        $$

        where $\mu$ is the mean and $\sigma$ is the standard deviation.

    Args:
        *x (UniversalArray): Input data, which can be only one  dimensional.
        sigma (float): Standard deviation. Defaults to 1.
        mu (float): Mean. Defaults to 0.
        cumulative (bool): If True, the CDF is returned. Defaults to False.
    """

    def probability_density_function(self) -> UniversalArray:
        """Return the probability density function."""
        return (
            1
            / (self._x * self.sigma * np.sqrt(2 * np.pi))
            * np.exp(-((np.log(self._x) - self.mu) ** 2) / (2 * self.sigma**2))
        )

    def cumulative_distribution_function(self) -> UniversalArray:
        """Return the cumulative distribution function."""
        return 0.5 * (1 + erf((np.log(self._x) - self.mu) / (self.sigma * np.sqrt(2))))

    @property
    def __summary__(self) -> SummaryStatisticsAPI:
        """Return the summary statistics."""
        return SummaryStatisticsAPI(
            mean=np.exp(self.mu + self.sigma**2 / 2),
            variance=(np.exp(self.sigma**2) - 1) * np.exp(2 * self.mu + self.sigma**2),
            mode=np.exp(self.mu - self.sigma**2),
            doc=self.__doc__,
        )