stm (version 1.3.3)

plot.estimateEffect: Plot effect of covariates on topics

Description

Plots the effect of a covariate on a set of topics selected by the user. Different effect types available depending on type of covariate. Before running this, the user should run a function to simulate the necessary confidence intervals. See estimateEffect.

Usage

# S3 method for estimateEffect
plot(x, covariate, model = NULL, topics = x$topics,
  method = c("pointestimate", "difference", "continuous"),
  cov.value1 = NULL, cov.value2 = NULL, moderator = NULL,
  moderator.value = NULL, npoints = 100, nsims = 100, ci.level = 0.95,
  xlim = NULL, ylim = NULL, xlab = "", ylab = NULL, main = "",
  printlegend = T, labeltype = "numbers", n = 7, frexw = 0.5, add = F,
  linecol = NULL, width = 25, verbose.labels = T, family = NULL,
  custom.labels = NULL, omit.plot = FALSE, ...)

Arguments

x

Output of estimateEffect, which calculates simulated betas for plotting.

covariate

String of the name of the main covariate of interest. Must be enclosed in quotes. All other covariates within the formula specified in estimateEffect will be kept at their median.

model

Model output, only necessary if labeltype is "prob", "frex", "score", or "lift". Models with more than one spline cannot be used for plot.estimateEffect.

topics

Topics to plot.

method

Method used for plotting. "pointestimate" estimates mean topic proportions for each value of the covariate. "difference" estimates the mean difference in topic proportions for two different values of the covariate (cov.value1 and cov.value2 must be specified). "continuous" estimates how topic proportions vary over the support of a continuous covariate.

cov.value1

For method "difference", the value or set of values of interest at which to set the covariate. In the case of calculating a treatment/control contrast, set the treatment to cov.value1.

cov.value2

For method "difference", the value or set of values which will be set as the comparison group. cov.value1 and cov.value2 must be vectors of the same length.

moderator

When two terms are interacted and one variable in the interaction is the covariate of interest, the user can specify the value of the interaction with moderator.value, and the name of the moderator with moderator.

moderator.value

When two terms are interacted and one variable in the interaction is the covariate of interest, the user can specify the value of the interaction term.

npoints

Number of unique points to use for simulation along the support of a continuous covariate. For method "continuous" only.

nsims

Number of simulations for estimation.

ci.level

Confidence level for confidence intervals.

xlim

Vector of x axis minimum and maximum values.

ylim

Vector of y axis minimum and maximum values.

xlab

Character string that is x axis title.

ylab

Character string that is y axis title.

main

Character string that is plot title.

printlegend

Whether to plot a topic legend in the case of a continuous covariate.

labeltype

Determines the labeltype for the topics. The default is "number" which prints the topic number. Other options are "prob", which prints the highest probability words, "score", "lift", and "frex", from labeltopics (see labeltopics() for more details). The user can also select "custom" for custom labels, which should be inputted under custom.labels. Labels appear in the legend for continous covariates.

n

Number of words to print if "prob", "score", "lift", or "frex" is chosen.

frexw

If "frex" labeltype is used, this will be the frex weight.

add

Logical parameter for whether the line should be added to the plot, or a new plot should be drawn.

linecol

For continuous covariates only. A vector that specifies the colors of the lines within the plot. If NULL, then colors will be randomly generated.

width

Number that specifies width of the character string. Smaller numbers will have smaller-width labels. Default is 25.

verbose.labels

For method "difference" -- verboselabels will specify the comparison covariate values of the covariate on the plot.

family

Font family.

custom.labels

A vector of custom labels if labeltype is equal to "custom".

omit.plot

Defaults to FALSE. When set to TRUE returns everything invisibly but doesn't do any plotting.

...

Other plotting parameters

Value

Values returned invisibly will depend on the method

For pointestimate:

uvals

Values of the covariate at which means and ci's were evaluated.

topics

Topics for which means and ci's were evaluated.

means

For each topic, means for each unique value.

cis

For each topic, confidence intervals for each unique value.

labels

Labels for each topic and unique value.

For difference:

topics

Topics for which difference in means and ci's were evaluated

means

For each topic, difference in means.

cis

For each topic, confidence intervals for difference in means.

labels

Labels for each topic.

For continuous:

x

Individual values of the covariate at which means and ci's were evaluated.

topics

Topics for which means and ci's were evaluated

means

For each topic and each x, means.

cis

For each topic and each x, confidence intervals for difference in means.

labels

Labels for each topic.

Examples

# NOT RUN {
# }
# NOT RUN {
prep <- estimateEffect(1:3 ~ treatment, gadarianFit, gadarian)
plot(prep, "treatment", model=gadarianFit,
method="pointestimate")
plot(prep, "treatment", model=gadarianFit,
method="difference",cov.value1=1,cov.value2=0)

#If the covariate were a binary factor, 
#the factor labels can be used to  
#specify the values of cov.value1 (e.g., cov.value1="treat"). 

# String variables must be turned to factors prior to plotting. 
#If you see this error, Error in rep.int(c(1, numeric(n)), n - 1L) : 
# invalid 'times' value, then you likely have not done this.

#Example of binary times binary interaction
gadarian$binaryvar <- sample(c(0,1), nrow(gadarian), replace=T)
temp <- textProcessor(gadarian$open.ended.response,metadata=gadarian)
out <- prepDocuments(temp$documents, temp$vocab, temp$meta)
stm1 <- stm(out$documents, out$vocab, 3, prevalence=~treatment*binaryvar,
 data=gadarian)
prep <- estimateEffect(c(2) ~ treatment*binaryvar, stmobj=stm1,
metadata=gadarian)

par(mfrow=c(1,2))
plot(prep, "treatment", method="pointestimate",
cov.value1=1, cov.value2=0, xlim=c(-1,1), moderator="binaryvar", moderator.value=1)
plot(prep, "treatment", method="pointestimate",
cov.value1=1, cov.value2=0, xlim=c(-1,1), moderator="binaryvar",
moderator.value=0)
# }