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=r|x)}{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,k-1\) represents the multiplicative effect of the covariate j on the odds \(\frac{P(Y=r|x)}{P(Y=k|x)}\) 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 no-effects 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 p-values that are printed beneath the category levels if printpvalues=TRUE. The closer a star ray lies to the no--effects circle, the more the p-value is increased.
The p-values 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 category-specific covariates. If its default xij=NULL is kept, an ordinary multinomial logit model without category-specific covariates is fitted. If category-specific 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 category-specific 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 category-specific 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 category-specific 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 k-1 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 category-specific 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.