pymc.Potential#
- pymc.Potential(name, var, model=None, dims=None)[source]#
Add an arbitrary factor potential to the model likelihood
The Potential function is used to add arbitrary factors (such as constraints or other likelihood components) to adjust the probability density of the model.
- Parameters
- name
str
Name of the potential variable to be registered in the model.
- vartensor_like
Expression to be added to the model joint logp.
- model
Model
, optional The model object to which the potential function is added. If
None
is provided, the current model in the context stack is used.- dims
str
ortuple
ofstr
, optional Dimension names for the variable.
- name
- Returns
- vartensor_like
The registered, named model variable.
Warning
Potential functions only influence logp-based sampling. Therefore, they are applicable for sampling with
pm.sample
but notpm.sample_prior_predictive
orpm.sample_posterior_predictive
.Examples
Have a look at the following example:
In this example, we define a constraint on
x
to be greater or equal to 0 via thepm.Potential
function. We passpm.math.log(pm.math.switch(constraint, 1, 0))
as second argument which will return an expression depending on if the constraint is met or not and which will be added to the likelihood of the model. The probablity density that this model produces agrees strongly with the constraint thatx
should be greater than or equal to 0. All the cases who do not satisfy the constraint are strictly not considered.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", pm.math.log(pm.math.switch(constraint, 1, 0)))
However, if we use
pm.math.log(pm.math.switch(constraint, 1.0, 0.5))
the potential again penalizes the likelihood when constraint is not met but with some deviations allowed. Here, Potential function is used to pass a soft constraint. A soft constraint is a constraint that is only partially satisfied. The effect of this is that the posterior probability for the parameters decreases as they move away from the constraint, but does not become exactly zero. This allows the sampler to generate values that violate the constraint, but with lower probability.with pm.Model() as model: x = pm.Normal("x", mu=0.1, sigma=1) y = pm.Normal("y", mu=x, sigma=1, observed=data) constraint = x >= 0 potential = pm.Potential("x_constraint", pm.math.log(pm.math.switch(constraint, 1.0, 0.5)))
In this example, Potential is used to obtain an arbitrary prior. This prior distribution refers to the prior knowledge that the values of
max_items
are likely to be small rather than being large. The prior probability ofmax_items
is defined using a Potential object with the log of the inverse ofmax_items
as its value. This means that larger values ofmax_items
have a lower prior probability density, while smaller values ofmax_items
have a higher prior probability density. When the model is sampled, the posterior distribution ofmax_items
given the observed value ofn_items
will be influenced by the power-law prior defined in the Potential objectwith pm.Model(): # p(max_items) = 1 / max_items max_items = pm.Uniform("max_items", lower=1, upper=100) pm.Potential("power_prior", pm.math.log(1/max_items)) n_items = pm.Uniform("n_items", lower=1, upper=max_items, observed=60)
In the next example, the
soft_sum_constraint
potential encouragesx
andy
to have a small sum, effectively adding a soft constraint on the relationship between the two variables. This can be useful in cases where you want to ensure that the sum of multiple variables stays within a certain range, without enforcing an exact value. In this case, the larger the deviation, larger will be the negative value (-((x + y)**2)) which the MCMC sampler will attempt to minimize. However, the sampler might generate values for some small deviations but with lower probability hence this is a soft constraint.with pm.Model() as model: x = pm.Normal("x", mu=0.1, sigma=1) y = pm.Normal("y", mu=x, sigma=1, observed=data) soft_sum_constraint = pm.Potential("soft_sum_constraint", -((x + y)**2))
The potential value is incorporated into the model log-probability, so it should be -inf (or very negative) when a constraint is violated, so that those draws are rejected. 0 won’t have any effect and positive values will make the proposals more likely to be accepted.