R: Optimize Document

optimizeDocument {stm} | R Documentation

## Optimize Document

### Description

A primarily internal use function for optimizing the document-level parameters of the variational distribution. Included here for advanced users who want to design new post-processing features. This help file assumes knowledge of our notation which follows the mathematical notation used in our vignette and other papers.

### Usage

    optimizeDocument(
      document,
      eta,
      mu,
      beta,
      sigma = NULL,
      sigmainv = NULL,
      sigmaentropy = NULL,
      method = "BFGS",
      control = list(maxit = 500),
      posterior = TRUE
    )

### Arguments

`document` | a single matrix containing the document in the `stm` format
`eta` | a vector of length K-1 containing the initial starting value for eta
`mu` | a vector of length K-1 containing the prevalence prior
`beta` | a matrix containing the complete topic-word distribution for the document. If using a content covariate model it is presumed that you have already passed the correct content covariate level's beta.
`sigma` | a K-1 by K-1 matrix containing the covariance matrix of the MVN prior. If you supply this you do not need to supply `sigmainv` or `sigmaentropy`. See below.
`sigmainv` | a K-1 by K-1 matrix containing the precision matrix of the MVN prior. If you supplied `sigma` you do not need to supply this. See below.
`sigmaentropy` | the entropy term calculated from sigma. If you supplied `sigma` you do not need to supply this. See below.
`method` | the method passed to `optim`. Uses "BFGS" by default.
`control` | the control argument passed to `optim`. Sets the maximum number of observations to 500 but can be used to set other aspects of the optimization per the instructions in `optim`
`posterior` | should the full posterior be returned? If TRUE (as it is by default) returns the full variational posterior. Otherwise just returns the point estimate.

### Details

This function is a small wrapper around the internal function used to complete the E-step for each document.

Regarding the arguments `sigma`, `sigmainv` and `sigmaentropy`. In the internal version of the code we calculate `sigmainv` and `sigmaentropy` once each E-step because it is shared by all documents. If you supply the original value to `sigma` it will calculate these for you. If you are going to be using this to run a bunch of documents and speed is a concern, peek at the underlying code and do the calculation yourself once and then just pass the result to the function so it isn't repeated with every observation.

### Value

a list

`phis` | A K by V* matrix containing the variational distribution for each token (where V* is the number of unique words in the given document. They are in the order of appearance in the document. For words repeated more than once the sum of the column is the number of times that token appeared.
`lambda` | A (K-1) by 1 matrix containing the mean of the variational distribution for eta. This is actually just called eta in the output of `stm` as it is also the point estimate.
`nu` | A (K-1) by (K-1) matrix containing the covariance matrix of the variational distribution for eta. This is also the inverse Hessian matrix.
`bound` | The value of the document-level contribution to the global approximate evidence lower bound.

### See Also

`thetaPosterior`

### Examples

    # fitting to a nonsense word distribution
    V <- length(poliblog5k.voc)
    K <- 50
    beta <- matrix(rgamma(V*K,shape = .1), nrow=K, ncol=V)
    beta <- beta/rowSums(beta)
    doc <- poliblog5k.docs[[1]]
    mu <- rep(0, K-1)
    sigma <- diag(1000, nrow=K-1)
    optimizeDocument(doc, eta=rep(0, K-1), mu=mu, beta=beta, sigma=sigma)

[Package stm version 1.3.6 Index]