Change name of LogNormalPositiveParam

[cetagostini]

Hey, I was checking this in #1945

I feel we should rename to something more descriptive, and align to other class. I feel the original name LogNormalExp was better, and as consequence something like LogNormalExpPrior will sound and look nicer.

Plus, I was thinking on make the docstring a bit verbose, showing the formula under the hood already. That way users don't need to go to the blog to find out whats different in this LogNormal:

class LogNormalExpPrior:
    """
    A lognormal prior parameterized by mean and standard deviation
    on the positive domain, with optional centered or non-centered
    parameterization.

    This prior differs from the standard ``LogNormal`` distribution,
    which takes log-scale parameters (``mu_log``, ``sigma_log``).
    Instead, it is parameterized directly in terms of the mean and
    standard deviation on the positive scale, making it more intuitive
    and suitable for hierarchical modeling.

    To achieve this, the lognormal parameters are computed internally
    from the positive-domain parameters:

    .. math::

        \mu_{\log} &= \ln \left( \frac{\mu^2}{\sqrt{\mu^2 + \sigma^2}} \right) \\
        \sigma_{\log} &= \sqrt{ \ln \left( 1 + \frac{\sigma^2}{\mu^2} \right) }

    where :math:`\mu > 0` and :math:`\sigma > 0`.

    The prior is then defined as:

    .. math::

        \phi &\sim \text{LogNormal}(\mu_{\log}, \sigma_{\log})

    This construction ensures that the resulting random variable
    has approximately the intended mean and variance on the positive scale,
    even when :math:`\mu` and :math:`\sigma` are themselves random variables.

    Parameters
    ----------
    mu : Prior, float, int, array-like
        The mean of the distribution on the positive scale.
    sigma : Prior, float, int, array-like
        The standard deviation of the distribution on the positive scale.
    dims : tuple[str, ...], optional
        The dimensions of the distribution, by default None.
    centered : bool, optional
        Whether to use the centered parameterization, by default True.

    Examples
    --------
    Build a non-centered hierarchical model where information is shared across groups:

    .. code-block:: python

        from pymc_marketing.special_priors import LogNormalExpPrior

        prior = LogNormalExpPrior(
            mu=Prior("Gamma", mu=1.0, sigma=1.0),
            sigma=Prior("HalfNormal", sigma=1.0),
            dims=("geo",),
            centered=False,
        )
    
    References
    ----------
    - D. Saunders, *A positive constrained non-centered prior that sparks joy*.
    - Wikipedia, *Log-normal distribution — Definitions*.
    """
. . . . 

Should I make a PR @daniel-saunders-phil ?

[daniel-saunders-phil]

Thanks Carlos, yeah I like the doc string we should definitely update to that.

As for the name, I could use some input. I moved away from LogNormalExp because it's a bit misleading about the math involved. The LogNormal distribution already involves exponentiation. It is just exp(normal()). So telling the user that an exponentiation is involved doesn't tell them much. I picked PositiveParam because that is what is actually distinctive against the LogNormal - the parameters are specified in over the positive numbers. I agree it's not as catchy but not sure what is a good alternative. Any idea on that end?

[cetagostini]

I see, and I agree. Question, I feel this is just an alternative parametrization.

• AlternativeLogNormalPrior ?
• PositiveLogNormalPrior ?

Any of those sounds better, @daniel-saunders-phil ?

[daniel-saunders-phil]

Yeah that's the right way to think about it - as an alternative parameterization. I don't love PositiveLogNormal because the ordinary LogNormal is positive. Alternative isn't informative about what it does and we don't have a LogNormalPrior class so it's also like "alternative to what"?

Maybe another route might work: we use the name LogNormalPrior but we change the names of the parameters from mu -> mean and sigma -> std. This way the arguments are informative as to what the parameterization is. The name of the class doesn't indicate the parameterization but maybe that's fine - all PyMC distributions use names that don't indicate how the distribution is parameterized so we aren't violating any reasonable expectation.