R: Model's 'log_prob' and 'grad_log_prob' functions

log_prob-methods {rstan} | R Documentation

## Model's `log_prob` and `grad_log_prob` functions

### Description

Using model's `log_prob` and `grad_log_prob` take values from the unconstrained space of model parameters and (by default) return values in the same space. Sometimes we need to convert the values of parameters from their support defined in the parameters block (which might be constrained, and for simplicity, we call it the constrained space) to the unconstrained space and vice versa. The `constrain_pars` and `unconstrain_pars` functions are used for this purpose.

### Usage

      ## S4 method for signature 'stanfit'
    log_prob(object, upars, adjust_transform = TRUE, gradient = FALSE)

      ## S4 method for signature 'stanfit'
    grad_log_prob(object, upars, adjust_transform = TRUE)

      ## S4 method for signature 'stanfit'
    get_num_upars(object)

      ## S4 method for signature 'stanfit'
    constrain_pars(object, upars)

      ## S4 method for signature 'stanfit'
    unconstrain_pars(object, pars)

### Arguments

`object` | An object of class `stanfit`.
`pars` | An list specifying the values for all parameters on the constrained space.
`upars` | A numeric vector for specifying the values for all parameters on the unconstrained space.
`adjust_transform` | Logical to indicate whether to adjust the log density since Stan transforms parameters to unconstrained space if it is in constrained space. Set to `FALSE` to make the function return the same values as Stan's `lp__` output.
`gradient` | Logical to indicate whether gradients are also computed as well as the log density.

### Details

Stan requires that parameters be defined along with their support. For example, for a variance parameter, we must define it on the positive real line. But inside Stan's samplers, all parameters defined on the constrained space are transformed to unconstrained space, so the log density function need be adjusted (i.e., adding the log of the absolute value of the Jacobian determinant). With the transformation, Stan's samplers work on the unconstrained space and once a new iteration is drawn, Stan transforms the parameters back to their supports. All the transformation are done by Stan without interference from the users. However, when using the log density function for a model exposed to R, we need to be careful. For example, if we are interested in finding the mode of parameters on the constrained space, we then do not need the adjustment. For this reason, the `log_prob` and `grad_log_prob` functions accept an `adjust_transform` argument.

### Value

`log_prob` returns a value (up to an additive constant) the log posterior. If `gradient` is `TRUE`, the gradients are also returned as an attribute with name `gradient`.

`grad_log_prob` returns a vector of the gradients. Additionally, the vector has an attribute named `log_prob` being the value the same as `log_prob` is called for the input parameters.

`get_num_upars` returns the number of parameters on the unconstrained space.

`constrain_pars` returns a list and `unconstrain_pars` returns a vector.

### Methods

log_prob

  `signature(object = "stanfit")`

Compute the log posterior (`lp__`) for the model represented by a `stanfit` object. Note that, by default, `log_prob` returns the log posterior in the unconstrained space; set `adjust_transform = FALSE` to make the values match Stan's output.

grad_log_prob

  `signature(object = "stanfit")`

Compute the gradients for `log_prob` as well as the log posterior. The latter is returned as an attribute.

get_num_upars

  `signature(object = "stanfit")`

Get the number of unconstrained parameters.

constrain_pars

  `signature(object = "stanfit")`

Convert values of the parameter from unconstrained space (given as a vector) to their constrained space (returned as a named list).

unconstrain_pars

  `signature(object = "stanfit")`

Contrary to `constrained`, conert values of the parameters from constrained to unconstrained space.

### References

The Stan Development Team Stan Modeling Language User's Guide and Reference Manual. http://mc-stan.org.

### See Also

`stanfit`

### Examples

    ## Not run:
    # see the examples in the help for stanfit as well
    # do a simple optimization problem
    opcode <- "
    parameters {
      real y;
    }
    model {
      target += log(square(y - 5) + 1);
    }
    "
    opfit <- stan(model_code = opcode, chains = 0)
    tfun <- function(y) log_prob(opfit, y)
    tgrfun <- function(y) grad_log_prob(opfit, y)
    or <- optim(1, tfun, tgrfun, method = 'BFGS')
    print(or)

    # return the gradient as an attribute
    tfun2 <- function(y) {
      g <- grad_log_prob(opfit, y)
      lp <- attr(g, "log_prob")
      attr(lp, "gradient") <- g
      lp
    }

    or2 <- nlm(tfun2, 10)
    or2

    ## End(Not run)

[Package rstan version 2.17.3 Index]