From 8eb38c8ad242c3030559bf770c69212b9637b670 Mon Sep 17 00:00:00 2001 From: Dhruvanshu Joshi Date: Sat, 28 Jan 2023 17:48:07 +0530 Subject: [PATCH] Docstring for Potential function updated --- pymc/model.py | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/pymc/model.py b/pymc/model.py index a9c38e738eb..d9003a41e53 100644 --- a/pymc/model.py +++ b/pymc/model.py @@ -2035,10 +2035,43 @@ def Deterministic(name, var, model=None, dims=None): def Potential(name, var, model=None): """Add an arbitrary factor potential to the model likelihood + Potential function is used to add arbitrary factors i.e. constraints that we define to the likelihood function of a model to adjust the probablity density of the model. + + .. code:: python + + with pm.Model() as my_model: + x = pm.Normal('x', mu=0, tau=1) + y = pm.Normal('y', mu=x, tau=1) + + constraint = x + y < 1 + potential = pm.Potential('constraint', constraint, my_model) + + In this example, we define a constraint on the sum of x and y that it can only be lesser than 1. We pass this constraint to the pm.Potential function. + Now the pm.Potential function takes in a expression, a scalar value and the model name as argument. + Now, the probablity density that the model produces takes into consideration the constraint that the sum of x and y should be lesser than 1. + + The Potential function here acts as a gatekeeper allowing only samples that satisfy the constraint to contribute to the likelihood. This ensures that the sample generated by the sampler are consistent with the constraint. + + Have a look at the following example: + + .. code:: python + + with pm.Model() as model: + x = pm.Normal('x', mu=0, sigma=1) + y = pm.Normal('y',mu=x, sigma=1,observed=data) + constraint = x>= 0 + potential = pm.Potential('x_constraint',-tt.log(tt.switch(constraint, 1, 1e-30))) + + In this example, we define a constraint on x that it can be either greater than or equal to 0 and pass this constraint to the pm.Potential function. + Now the pm.Potential function takes in a string expression and a scalar value as argument. Hence we pass '-tt.log(tt.switch(constraint, 1, 1e-30))' as second argument which will return a scalar value depending on the constraint and will add to the likelihood function of the model. + This is done because PyMC3 uses an energy-based model, which means that the probability of a variable configuration is proportional to the negative of the energy of that configuration. So, the negative logarithm of the switch function ensures that the energy is high (i.e. close to negative infinity) when the constraint is not met, and low (i.e. close to zero) when the constraint is met. + The probablity density that this model produces agrees with the constraint that x should be greater than or equal to 0. + Parameters ---------- name: str - var: PyTensor variables + var: PyTensor or Scalar variables with the same shape as input to the likelihood + model: The model object to which the potential function is added. If none is provided, current model is used Returns -------