Skip to content

Rename mean constructor parameter to mu on BetaProportion and NegativeBinomial2 #1

Description

@tillahoffmann

Problem

Two distributions take a constructor parameter literally named mean, which collides with the .mean statistic property every distribution exposes:

  • BetaProportion(mean, concentration)continuous.py:3408; "mean" in arg_constraints (open_interval(0, 1)).
  • NegativeBinomial2(mean, concentration)conjugate.py:533; "mean" in arg_constraints (positive). The name also propagates to the ZeroInflatedNegativeBinomial2 and HurdleNegativeBinomial2 factory functions.

Neither class stores self.mean. The constructor immediately reparameterizes the argument (BetaProportion → concentration1/concentration0; NegativeBinomial2 → rate = concentration / mean) and stores those instead. So arg_constraints["mean"] validation reads getattr(self, "mean"), which resolves to the inherited .mean statistic property (Beta.mean / GammaPoisson.mean). That happens to equal the input only by the reparameterization algebra:

  • BetaProportion: μφ / (μφ + (1−μ)φ) = μ
  • NegativeBinomial2: α / (α/μ) = μ

Why it matters

Validation of the mean parameter is silently piggybacking on the .mean statistic, relying on an algebraic coincidence rather than checking the actual input. This is fragile: when Beta.mean was narrowed to return a jax.Array (jnp.asarray(...)), the property became a tracer under jax.jit, so Distribution.validate_args(strict=False) skipped value validation and test_distribution_constraints' under-jit assertion broke for BetaProportion. (Worked around in the array-output PR by relaxing that test assertion.)

Proposed fix

Rename the constructor parameter meanmu on both distributions (and the two NB2 factory functions), updating arg_constraints, reparametrized_params, docstrings, and any examples/tests. mu matches both distributions' references (Ferrari & Cribari-Neto 2004 for BetaProportion; the NB2 docstring already writes μ) and removes the attribute-name collision. The .mean property continues to compute the statistic; there is no longer a parameter shadowing it.

loc was considered and rejected: these parameters are the mean of a bounded/count distribution, not an additive location shift, so loc would misrepresent the parameterization.

Compatibility

This is a breaking public API change (both classes are exported and documented). It needs a deprecation path — accept mu as the new name, keep mean working with a DeprecationWarning for at least one release.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions