optimizeDocument: 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

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.

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 appearence 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.

A (K-1) by (K-1) matrix containg 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.

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 youself once and then just pass the result to the function so it isn't repeated with every observation.

Examples

Run this code

# NOT RUN {
# 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)
# }