20.3 User-defined Distributions

When a custom _lpdf or _lpmf function is defined, the compiler will automatically make available a _lupdf or _lupmf version of the function. It is only possible to define custom distributions in the normalized form in Stan. Any attempt to define an unnormalized distribution directly will result in an error.

The difference in the normalized and unnormalized versions of custom probability functions is how probability functions are treated inside these functions. Any internal unnormalized probability function call will be replaced with its normalized equivalent if the normalized version of the parent custom distribution is called.

The following code demonstrates the different behaviors:

functions {
  real custom1_lpdf(x) {
    return normal_lupdf(x | 0.0, 1.0)
  }
  real custom2_lpdf(x) {
    return normal_lpdf(x | 0.0, 1.0)
  }
}
parameters {
  real mu;
}
model {
  mu ~ custom1(); // Normalization constants dropped
  target += custom1_lupdf(mu); // Normalization constants dropped
  target += custom1_lpdf(mu);  // Normalization constants kept

  mu ~ custom2();  // Normalization constants kept
  target += custom2_lupdf(mu);  // Normalization constants kept
  target += custom2_lpdf(mu);  // Normalization constants kept
}