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,
  ...
)

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.

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 continuous 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

Examples

Run this code


# \donttest{

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=TRUE)
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)
# }

Run the code above in your browser using DataLab