Rename get_moment to moment

Author: ricardoV94

docs/source/contributing/developer_guide_implementing_distribution.md

@@ -4,7 +4,7 @@ This guide provides an overview on how to implement a distribution for version 4
 It is designed for developers who wish to add a new distribution to the library.
 Users will not be aware of all this complexity and should instead make use of helper methods such as `~pymc.distributions.DensityDist`.
 
-PyMC {class}`~pymc.distributions.Distribution` builds on top of Aesara's {class}`~aesara.tensor.random.op.RandomVariable`, and implements `logp`, `logcdf` and `get_moment` methods as well as other initialization and validation helpers.
+PyMC {class}`~pymc.distributions.Distribution` builds on top of Aesara's {class}`~aesara.tensor.random.op.RandomVariable`, and implements `logp`, `logcdf` and `moment` methods as well as other initialization and validation helpers.
 Most notably `shape/dims` kwargs, alternative parametrizations, and default `transforms`.
 
 Here is a summary check-list of the steps needed to implement a new distribution.
@@ -13,7 +13,7 @@ Each section will be expanded below:
 1. Creating a new `RandomVariable` `Op`
 1. Implementing the corresponding `Distribution` class
 1. Adding tests for the new `RandomVariable`
-1. Adding tests for `logp` / `logcdf` and `get_moment` methods
+1. Adding tests for `logp` / `logcdf` and `moment` methods
 1. Documenting the new `Distribution`.
 
 This guide does not attempt to explain the rationale behind the `Distributions` current implementation, and details are provided only insofar as they help to implement new "standard" distributions.
@@ -119,7 +119,7 @@ After implementing the new `RandomVariable` `Op`, it's time to make use of it in
 PyMC 4.x works in a very {term}`functional <Functional Programming>` way, and the `distribution` classes are there mostly to facilitate porting the `PyMC3` v3.x code to the new `PyMC` v4.x version, add PyMC API features and keep related methods organized together.
 In practice, they take care of:
 
-1. Linking ({term}`Dispatching`) a rv_op class with the corresponding `get_moment`, `logp` and `logcdf` methods.
+1. Linking ({term}`Dispatching`) a rv_op class with the corresponding `moment`, `logp` and `logcdf` methods.
 1. Defining a standard transformation (for continuous distributions) that converts a bounded variable domain (e.g., positive line) to an unbounded domain (i.e., the real line), which many samplers prefer.
 1. Validating the parametrization of a distribution and converting non-symbolic inputs (i.e., numeric literals or numpy arrays) to symbolic variables.
 1. Converting multiple alternative parametrizations to the standard parametrization that the `RandomVariable` is defined in terms of.
@@ -154,9 +154,9 @@ class Blah(PositiveContinuous):
         # the rv_op needs in order to be instantiated
         return super().dist([param1, param2], **kwargs)
 
-    # get_moment returns a symbolic expression for the stable moment from which to start sampling
+    # moment returns a symbolic expression for the stable moment from which to start sampling
     # the variable, given the implicit `rv`, `size` and `param1` ... `paramN`
-    def get_moment(rv, size, param1, param2):
+    def moment(rv, size, param1, param2):
         moment, _ = at.broadcast_arrays(param1, param2)
         if not rv_size_is_none(size):
             moment = at.full(size, moment)
@@ -198,25 +198,25 @@ Some notes:
    overriding `__new__`.
 1. As mentioned above, `PyMC` v4.x works in a very {term}`functional <Functional Programming>` way, and all the information that is needed in the `logp` and `logcdf` methods is expected to be "carried" via the `RandomVariable` inputs. You may pass numerical arguments that are not strictly needed for the `rng_fn` method but are used in the `logp` and `logcdf` methods. Just keep in mind whether this affects the correct shape inference behavior of the `RandomVariable`. If specialized non-numeric information is needed you might need to define your custom`_logp` and `_logcdf` {term}`Dispatching` functions, but this should be done as a last resort.
 1. The `logcdf` method is not a requirement, but it's a nice plus!
-1. Currently only one moment is supported in the `get_moment` method, and probably the "higher-order" one is the most useful (that is `mean` > `median` > `mode`)... You might need to truncate the moment if you are dealing with a discrete distribution.
-1. When creating the `get_moment` method, we have to be careful with `size != None` and broadcast properly when some parameters that are not used in the moment may nevertheless inform about the shape of the distribution. E.g. `pm.Normal.dist(mu=0, sigma=np.arange(1, 6))` returns a moment of `[mu, mu, mu, mu, mu]`.
+1. Currently only one moment is supported in the `moment` method, and probably the "higher-order" one is the most useful (that is `mean` > `median` > `mode`)... You might need to truncate the moment if you are dealing with a discrete distribution.
+1. When creating the `moment` method, we have to be careful with `size != None` and broadcast properly when some parameters that are not used in the moment may nevertheless inform about the shape of the distribution. E.g. `pm.Normal.dist(mu=0, sigma=np.arange(1, 6))` returns a moment of `[mu, mu, mu, mu, mu]`.
 
 For a quick check that things are working you can try the following:
 
 ```python
 
 import pymc as pm
-from pymc.distributions.distribution import get_moment
+from pymc.distributions.distribution import moment
 
 # pm.blah = pm.Normal in this example
-blah = pm.blah.dist(mu = 0, sigma = 1)
+blah = pm.blah.dist(mu=0, sigma=1)
 
 # Test that the returned blah_op is still working fine
 blah.eval()
 # array(-1.01397228)
 
-# Test the get_moment method
-get_moment(blah).eval()
+# Test the moment method
+moment(blah).eval()
 # array(0.)
 
 # Test the logp method
@@ -367,9 +367,9 @@ def test_blah_logcdf(self):
 
 ```
 
-## 5. Adding tests for the `get_moment` method
+## 5. Adding tests for the `moment` method
 
-Tests for the `get_moment` method are contained in `pymc/tests/test_distributions_moments.py`, and make use of the function `assert_moment_is_expected`
+Tests for the `moment` method are contained in `pymc/tests/test_distributions_moments.py`, and make use of the function `assert_moment_is_expected`
 which checks if:
 1. Moments return the `expected` values
 1. Moments have the expected size and shape

pymc/distributions/censored.py

@@ -18,7 +18,7 @@
 from aesara.tensor import TensorVariable
 from aesara.tensor.random.op import RandomVariable
 
-from pymc.distributions.distribution import SymbolicDistribution, _get_moment
+from pymc.distributions.distribution import SymbolicDistribution, _moment
 from pymc.util import check_dist_not_registered
 
 
@@ -124,8 +124,8 @@ def graph_rvs(cls, rv):
         return (rv.tag.dist,)
 
 
-@_get_moment.register(Clip)
-def get_moment_censored(op, rv, dist, lower, upper):
+@_moment.register(Clip)
+def moment_censored(op, rv, dist, lower, upper):
     moment = at.switch(
         at.eq(lower, -np.inf),
         at.switch(

pymc/distributions/continuous.py

@@ -305,7 +305,7 @@ def dist(cls, lower=0, upper=1, **kwargs):
         upper = at.as_tensor_variable(floatX(upper))
         return super().dist([lower, upper], **kwargs)
 
-    def get_moment(rv, size, lower, upper):
+    def moment(rv, size, lower, upper):
         lower, upper = at.broadcast_arrays(lower, upper)
         moment = (lower + upper) / 2
         if not rv_size_is_none(size):
@@ -370,7 +370,7 @@ def dist(cls, *, size=None, **kwargs):
         res = super().dist([], size=size, **kwargs)
         return res
 
-    def get_moment(rv, size):
+    def moment(rv, size):
         return at.zeros(size)
 
     def logp(value):
@@ -438,7 +438,7 @@ def dist(cls, *, size=None, **kwargs):
         res = super().dist([], size=size, **kwargs)
         return res
 
-    def get_moment(rv, size):
+    def moment(rv, size):
         return at.ones(size)
 
     def logp(value):
@@ -556,7 +556,7 @@ def dist(cls, mu=0, sigma=None, tau=None, no_assert=False, **kwargs):
 
         return super().dist([mu, sigma], **kwargs)
 
-    def get_moment(rv, size, mu, sigma):
+    def moment(rv, size, mu, sigma):
         mu, _ = at.broadcast_arrays(mu, sigma)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -716,7 +716,7 @@ def dist(
         upper = at.as_tensor_variable(floatX(upper)) if upper is not None else at.constant(np.inf)
         return super().dist([mu, sigma, lower, upper], **kwargs)
 
-    def get_moment(rv, size, mu, sigma, lower, upper):
+    def moment(rv, size, mu, sigma, lower, upper):
         mu, _, lower, upper = at.broadcast_arrays(mu, sigma, lower, upper)
         moment = at.switch(
             at.eq(lower, -np.inf),
@@ -865,7 +865,7 @@ def dist(cls, sigma=None, tau=None, *args, **kwargs):
 
         return super().dist([0.0, sigma], **kwargs)
 
-    def get_moment(rv, size, loc, sigma):
+    def moment(rv, size, loc, sigma):
         moment = loc + sigma
         if not rv_size_is_none(size):
             moment = at.full(size, moment)
@@ -1017,7 +1017,7 @@ def dist(
 
         return super().dist([mu, lam, alpha], **kwargs)
 
-    def get_moment(rv, size, mu, lam, alpha):
+    def moment(rv, size, mu, lam, alpha):
         mu, _, _ = at.broadcast_arrays(mu, lam, alpha)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -1225,7 +1225,7 @@ def dist(cls, alpha=None, beta=None, mu=None, sigma=None, *args, **kwargs):
 
         return super().dist([alpha, beta], **kwargs)
 
-    def get_moment(rv, size, alpha, beta):
+    def moment(rv, size, alpha, beta):
         mean = alpha / (alpha + beta)
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -1356,7 +1356,7 @@ def dist(cls, a, b, *args, **kwargs):
 
         return super().dist([a, b], *args, **kwargs)
 
-    def get_moment(rv, size, a, b):
+    def moment(rv, size, a, b):
         mean = at.exp(at.log(b) + at.gammaln(1 + 1 / a) + at.gammaln(b) - at.gammaln(1 + 1 / a + b))
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -1476,7 +1476,7 @@ def dist(cls, lam, *args, **kwargs):
         # Aesara exponential op is parametrized in terms of mu (1/lam)
         return super().dist([at.inv(lam)], **kwargs)
 
-    def get_moment(rv, size, mu):
+    def moment(rv, size, mu):
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
         return mu
@@ -1560,7 +1560,7 @@ def dist(cls, mu, b, *args, **kwargs):
         assert_negative_support(b, "b", "Laplace")
         return super().dist([mu, b], *args, **kwargs)
 
-    def get_moment(rv, size, mu, b):
+    def moment(rv, size, mu, b):
         mu, _ = at.broadcast_arrays(mu, b)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -1671,7 +1671,7 @@ def dist(cls, b, kappa, mu=0, *args, **kwargs):
 
         return super().dist([b, kappa, mu], *args, **kwargs)
 
-    def get_moment(rv, size, b, kappa, mu):
+    def moment(rv, size, b, kappa, mu):
         mean = mu - (kappa - 1 / kappa) / b
 
         if not rv_size_is_none(size):
@@ -1782,7 +1782,7 @@ def dist(cls, mu=0, sigma=None, tau=None, *args, **kwargs):
 
         return super().dist([mu, sigma], *args, **kwargs)
 
-    def get_moment(rv, size, mu, sigma):
+    def moment(rv, size, mu, sigma):
         mean = at.exp(mu + 0.5 * sigma**2)
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -1907,7 +1907,7 @@ def dist(cls, nu, mu=0, lam=None, sigma=None, *args, **kwargs):
 
         return super().dist([nu, mu, sigma], **kwargs)
 
-    def get_moment(rv, size, nu, mu, sigma):
+    def moment(rv, size, nu, mu, sigma):
         mu, _, _ = at.broadcast_arrays(mu, nu, sigma)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -2025,7 +2025,7 @@ def dist(
 
         return super().dist([alpha, m], **kwargs)
 
-    def get_moment(rv, size, alpha, m):
+    def moment(rv, size, alpha, m):
         median = m * 2 ** (1 / alpha)
         if not rv_size_is_none(size):
             median = at.full(size, median)
@@ -2121,7 +2121,7 @@ def dist(cls, alpha, beta, *args, **kwargs):
         assert_negative_support(beta, "beta", "Cauchy")
         return super().dist([alpha, beta], **kwargs)
 
-    def get_moment(rv, size, alpha, beta):
+    def moment(rv, size, alpha, beta):
         alpha, _ = at.broadcast_arrays(alpha, beta)
         if not rv_size_is_none(size):
             alpha = at.full(size, alpha)
@@ -2197,7 +2197,7 @@ def dist(cls, beta, *args, **kwargs):
         assert_negative_support(beta, "beta", "HalfCauchy")
         return super().dist([0.0, beta], **kwargs)
 
-    def get_moment(rv, size, loc, beta):
+    def moment(rv, size, loc, beta):
         if not rv_size_is_none(size):
             beta = at.full(size, beta)
         return beta
@@ -2320,7 +2320,7 @@ def get_alpha_beta(cls, alpha=None, beta=None, mu=None, sigma=None):
 
         return alpha, beta
 
-    def get_moment(rv, size, alpha, inv_beta):
+    def moment(rv, size, alpha, inv_beta):
         # The Aesara `GammaRV` `Op` inverts the `beta` parameter itself
         mean = alpha * inv_beta
         if not rv_size_is_none(size):
@@ -2415,7 +2415,7 @@ def dist(cls, alpha=None, beta=None, mu=None, sigma=None, *args, **kwargs):
 
         return super().dist([alpha, beta], **kwargs)
 
-    def get_moment(rv, size, alpha, beta):
+    def moment(rv, size, alpha, beta):
         mean = beta / (alpha - 1.0)
         mode = beta / (alpha + 1.0)
         moment = at.switch(alpha > 1, mean, mode)
@@ -2525,7 +2525,7 @@ def dist(cls, nu, *args, **kwargs):
         nu = at.as_tensor_variable(floatX(nu))
         return super().dist([nu], *args, **kwargs)
 
-    def get_moment(rv, size, nu):
+    def moment(rv, size, nu):
         moment = nu
         if not rv_size_is_none(size):
             moment = at.full(size, moment)
@@ -2620,7 +2620,7 @@ def dist(cls, alpha, beta, *args, **kwargs):
 
         return super().dist([alpha, beta], *args, **kwargs)
 
-    def get_moment(rv, size, alpha, beta):
+    def moment(rv, size, alpha, beta):
         mean = beta * at.gamma(1 + 1 / alpha)
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -2739,7 +2739,7 @@ def dist(cls, nu=1, sigma=None, lam=None, *args, **kwargs):
 
         return super().dist([nu, sigma], *args, **kwargs)
 
-    def get_moment(rv, size, nu, sigma):
+    def moment(rv, size, nu, sigma):
         sigma, _ = at.broadcast_arrays(sigma, nu)
         if not rv_size_is_none(size):
             sigma = at.full(size, sigma)
@@ -2871,7 +2871,7 @@ def dist(cls, mu=0.0, sigma=None, nu=None, *args, **kwargs):
 
         return super().dist([mu, sigma, nu], *args, **kwargs)
 
-    def get_moment(rv, size, mu, sigma, nu):
+    def moment(rv, size, mu, sigma, nu):
         mu, nu, _ = at.broadcast_arrays(mu, nu, sigma)
         moment = mu + nu
         if not rv_size_is_none(size):
@@ -3005,7 +3005,7 @@ def dist(cls, mu=0.0, kappa=None, *args, **kwargs):
         assert_negative_support(kappa, "kappa", "VonMises")
         return super().dist([mu, kappa], *args, **kwargs)
 
-    def get_moment(rv, size, mu, kappa):
+    def moment(rv, size, mu, kappa):
         mu, _ = at.broadcast_arrays(mu, kappa)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -3105,7 +3105,7 @@ def dist(cls, alpha=1, mu=0.0, sigma=None, tau=None, *args, **kwargs):
 
         return super().dist([mu, sigma, alpha], *args, **kwargs)
 
-    def get_moment(rv, size, mu, sigma, alpha):
+    def moment(rv, size, mu, sigma, alpha):
         mean = mu + sigma * (2 / np.pi) ** 0.5 * alpha / (1 + alpha**2) ** 0.5
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -3202,7 +3202,7 @@ def dist(cls, lower=0, upper=1, c=0.5, *args, **kwargs):
 
         return super().dist([lower, c, upper], *args, **kwargs)
 
-    def get_moment(rv, size, lower, c, upper):
+    def moment(rv, size, lower, c, upper):
         mean = (lower + upper + c) / 3
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -3309,7 +3309,7 @@ def dist(
 
         return super().dist([mu, beta], **kwargs)
 
-    def get_moment(rv, size, mu, beta):
+    def moment(rv, size, mu, beta):
         mean = mu + beta * np.euler_gamma
         if not rv_size_is_none(size):
             mean = at.full(size, mean)
@@ -3439,7 +3439,7 @@ def get_nu_b(cls, nu, b, sigma):
             return nu, b, sigma
         raise ValueError("Rice distribution must specify either nu" " or b.")
 
-    def get_moment(rv, size, nu, sigma):
+    def moment(rv, size, nu, sigma):
         nu_sigma_ratio = -(nu**2) / (2 * sigma**2)
         mean = (
             sigma
@@ -3538,7 +3538,7 @@ def dist(cls, mu=0.0, s=1.0, *args, **kwargs):
         s = at.as_tensor_variable(floatX(s))
         return super().dist([mu, s], *args, **kwargs)
 
-    def get_moment(rv, size, mu, s):
+    def moment(rv, size, mu, s):
         mu, _ = at.broadcast_arrays(mu, s)
         if not rv_size_is_none(size):
             mu = at.full(size, mu)
@@ -3643,7 +3643,7 @@ def dist(cls, mu=0, sigma=None, tau=None, **kwargs):
 
         return super().dist([mu, sigma], **kwargs)
 
-    def get_moment(rv, size, mu, sigma):
+    def moment(rv, size, mu, sigma):
         median, _ = at.broadcast_arrays(invlogit(mu), sigma)
         if not rv_size_is_none(size):
             median = at.full(size, median)
@@ -3793,7 +3793,7 @@ def dist(cls, x_points, pdf_points, *args, **kwargs):
 
         return super().dist([x_points, pdf_points, cdf_points], **kwargs)
 
-    def get_moment(rv, size, x_points, pdf_points, cdf_points):
+    def moment(rv, size, x_points, pdf_points, cdf_points):
         # cdf_points argument is unused
         moment = at.sum(at.mul(x_points, pdf_points))
 
@@ -3905,7 +3905,7 @@ def dist(cls, mu=0, sigma=1.0, *args, **kwargs):
 
         return super().dist([mu, sigma], *args, **kwargs)
 
-    def get_moment(rv, size, mu, sigma):
+    def moment(rv, size, mu, sigma):
         mean = mu + sigma * (np.euler_gamma + at.log(2))
 
         if not rv_size_is_none(size):
@@ -4119,7 +4119,7 @@ def dist(cls, h=1.0, z=0.0, **kwargs):
 
         return super().dist([h, z], **kwargs)
 
-    def get_moment(rv, size, h, z):
+    def moment(rv, size, h, z):
         mean = at.switch(at.eq(z, 0), h / 4, tanh(z / 2) * (h / (2 * z)))
         if not rv_size_is_none(size):
             mean = at.full(size, mean)