star.nominal {EffectStars}  R Documentation 
The package EffectStars2 provides a more uptodate implementation of effect stars!
The function computes and visualizes multinomial logit models. The computation is done with help of
the package VGAM. The visualization is based on the function stars
from the package graphics.
star.nominal(formula, data, xij = NULL, conf.int = FALSE, symmetric = TRUE,
pred.coding = "reference", printpvalues = TRUE, test.rel = TRUE, refLevel = 1,
maxit = 100, scale = TRUE, nlines = NULL, select = NULL, catstar = TRUE,
dist.x = 1, dist.y = 1, dist.cov = 1, dist.cat = 1, xpd = TRUE, main = "",
lwd.stars = 1, col.fill = "gray90", col.circle = "black", lwd.circle = 1,
lty.circle = "longdash", lty.conf = "dotted", cex.labels = 1, cex.cat = 0.8,
xlim = NULL, ylim = NULL)
formula 
An object of class “formula”. Formula for the multinomial logit model to be fitted and visualized. 
data 
An object of class “data.frame” containing the covariates used in 
xij 
An object of class list, used if categoryspecific covariates are to be inlcuded. Every element is a formula referring to one of the categoryspecific covariates. For details see help for 
conf.int 
If 
symmetric 
Which side constraint for the coefficients in the multinomial logit model shall be used for the plot?
Default 
pred.coding 
Which coding for categorical predictors with more than two categories is to be used?
Default 
printpvalues 
If 
test.rel 
Provides a LikelihoodRatioTest to test the relevance of the explanatory covariates.
The corresponding pvalues will be printed behind the covariates labels. 
refLevel 
Reference category for multinomial logit model. Ignored if 
maxit 
Maximal number of iterations to fit the multinomial logit model. See also

scale 
If 
nlines 
If specified, 
select 
Numeric vector to choose only a subset of the stars to be plotted. Default is to plot all stars. Numbers refer to total amount of predictors, including intercept and dummy variables. 
catstar 
A logical argument to specify if all categoryspecific effects in the model should be visualized with an additional star. Ignored if 
dist.x 
Optional factor to increase/decrease distances between the centers of the stars on the xaxis. Values greater than 1 increase, values smaller than 1 decrease the distances. 
dist.y 
Optional factor to increase/decrease distances between the centers of the stars on the yaxis. Values greater than 1 increase, values smaller than 1 decrease the distances. 
dist.cov 
Optional factor to increase/decrease distances between the stars and the covariates labels above the stars. Values greater than 1 increase, values smaller than 1 decrease the distances. 
dist.cat 
Optional factor to increase/decrease distances between the stars and the category labels around the stars. Values greater than 1 increase, values smaller than 1 decrease the distances. 
xpd 
If 
main 
An overall title for the plot. See also 
lwd.stars 
Line width of the stars. See also 
col.fill 
Color of background of the circle. See also 
col.circle 
Color of margin of the circle. See also 
lwd.circle 
Line width of the circle. See also 
lty.circle 
Line type of the circle. See also 
lty.conf 
Line type of confidence intervals. Ignored, if 
cex.labels 
Size of labels for covariates placed above the corresponding star. See also 
cex.cat 
Size of labels for categories placed around the corresponding star. See also 
xlim 
Optional specification of the x coordinates ranges. See also 
ylim 
Optional specification of the y coordinates ranges. See also 
The underlying models are fitted with the function vglm
from the package VGAM. The family argument
for vglm
is multinomial(parallel=FALSE)
.
The stars show the exponentials of the estimated coefficients. In multinomial logit models the exponential coefficients can
be interpreted as odds. More precisely, for the model with symmetric side constraints, the exponential e^{\gamma_{rj}}, r=1,\ldots,k
represents the multiplicative effect of the covariate j on the odds \frac{P(Y=rx)}{GM(x)}
if x_j
increases by one unit and GM(x)
is the median response. For the model with reference category k, the exponential e^{\gamma_{rj}}, r=1,\ldots,k1
represents the multiplicative effect of the covariate j on the odds \frac{P(Y=rx)}{P(Y=kx)}
if x_j
increases by one unit.
In addition to the stars, we plot a cirlce that refers to the case where the coefficients of the corresponding star are zero. Therefore, the radii of these circles are always exp(0)=1
. If scale=TRUE
, the stars are scaled so that they all have the same maximal ray length. In this case, the actual appearances of the circles differ, but they still refer to the noeffects case where all the coefficients are zero. Now the circles can be used to compare different stars based on their respective circles radii. The distances between the rays of a star and the cirlce correspond to the pvalues that are printed beneath the category levels if printpvalues=TRUE
. The closer a star ray lies to the no–effects circle, the more the pvalue is increased.
The pvalues beneath the covariate labels, which are given if test.rel=TRUE
, correspond to the distance between the circle and the star as a whole. They refer to a likelihood ratio test if all the coefficients from one covariate are zero (i.e. the variable is left out completely) and thus would lie exactly upon the cirlce.
The appearance of the circles can be modified by col.circle
, lwd.circle
and lty.circle
.
The argument xij
is important because it has to be used to include categoryspecific covariates. If its default xij=NULL
is kept, an ordinary multinomial logit model without categoryspecific covariates is fitted. If categoryspecific covariates are to be included, attention has to be paid to the exact usage of xij
. Our xij
argument is identical to the xij
argument used in the embedded vglm
function. For details see also vglm.control
. The data are thought to be present in a wide format, i.e. a categoryspecific covariate consists of k columns. Before calling star.nominal
, the values for the reference category (defined by refLevel
) have to be subtracted from the values of the further categories. Additionally, the resulting variable for the first response category (but not the reference category) has to be duplicated. This duplicate should be denoted by an appropriate name for the categoryspecific variable, independent from the different response categories. It will be used as an assignment variable for the corresponding coefficient of the covariate and has to be included in to the formula
. For every categoryspecific covariate, a formula has to be specified in the xij
argument. On the left hand side of that formula, the assignment variable has to be placed. On the right hand side, the variables containing the differences from the values for the reference category are written. So the left hand side of the formula contains k1 terms. The order of these terms has to be chosen according to the order of the response categories, ignoring the reference category. Examples for effect stars for models with categoryspecific covariates are recieved by typing vignette("election")
or vignette("plebiscite")
.
It is strongly recommended to standardize metric covariates, display of effect stars can benefit greatly as in general differences between the coefficients are increased.
Pvalues are only available if the corresponding option is set TRUE
.
catspec
and catspecse
are only available if xij
is specified.
odds 
Odds or exponential coefficients of the multinomial logit model 
coefficients 
Coefficients of the multinomial logit model 
se 
Standard errors of the coefficients 
pvalues 
Pvalues of Wald tests for the respective coefficients 
catspec 
Coefficients for the categoryspecific covariates 
catspecse 
Standard errors for the coefficients for the categoryspecific covariates 
p_rel 
Pvalues of LikelihoodRatioTests for the relevance of the explanatory covariates 
xlim 

ylim 

Gunther Schauberger
gunther.schauberger@tum.de
https://www.sg.tum.de/epidemiologie/team/schauberger/
Tutz, G. and Schauberger, G. (2012): Visualization of Categorical Response Models 
from Data Glyphs to Parameter Glyphs, Journal of Computational and Graphical Statistics 22(1), 156177.
Gerhard Tutz (2012): Regression for Categorical Data, Cambridge University Press
star.sequential
, star.cumulative
## Not run:
data(election)
# simple multinomial logit model
star.nominal(Partychoice ~ Age + Religion + Democracy + Pol.Interest +
Unemployment + Highschool + Union + West + Gender, election)
# Use effect coding for the categorical predictor religion
star.nominal(Partychoice ~ Age + Religion + Democracy + Pol.Interest +
Unemployment + Highschool + Union + West + Gender, election,
pred.coding = "effect")
# Use reference category "FDP" instead of symmetric side constraints
star.nominal(Partychoice ~ Age + Religion + Democracy + Pol.Interest +
Unemployment + Highschool + Union + West + Gender, election,
refLevel = 3, symmetric = FALSE)
# Use categoryspecific covariates, subtract values for reference
# category CDU
election[,13:16] < election[,13:16]  election[,12]
election[,18:21] < election[,18:21]  election[,17]
election[,23:26] < election[,23:26]  election[,22]
election[,28:31] < election[,28:31]  election[,27]
election$Social < election$Social_SPD
election$Immigration < election$Immigration_SPD
election$Nuclear < election$Nuclear_SPD
election$Left_Right < election$Left_Right_SPD
star.nominal(Partychoice ~ Social + Immigration + Nuclear + Left_Right + Age +
Religion + Democracy + Pol.Interest + Unemployment + Highschool + Union + West +
Gender, data = election,
xij = list(Social ~ Social_SPD + Social_FDP + Social_Greens + Social_Left,
Immigration ~ Immigration_SPD + Immigration_FDP + Immigration_Greens + Immigration_Left,
Nuclear ~ Nuclear_SPD + Nuclear_FDP + Nuclear_Greens + Nuclear_Left,
Left_Right ~ Left_Right_SPD + Left_Right_FDP + Left_Right_Greens + Left_Right_Left),
symmetric = FALSE)
## End(Not run)