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
)

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.

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.

Examples

Run this code

# 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)