star.cumulative {EffectStars}

Effect stars for cumulative logit models

Description

The package EffectStars2 provides a more up-to-date implementation of effect stars!

The function computes and visualizes cumulative logit models. The computation is done with help of the package VGAM. The visualization is based on the function stars from the package graphics.

Usage

star.cumulative(formula, data, global = NULL, test.rel = TRUE, test.glob = FALSE, 
    partial = FALSE, globcircle = FALSE, maxit = 100, scale = TRUE, 
    nlines = NULL, select = NULL, dist.x = 1, dist.y = 1, dist.cov = 1, 
    dist.cat = 1, xpd = TRUE, main = "", col.fill = "gray90", 
    col.circle = "black", lwd.circle = 1, lty.circle = "longdash", 
    col.global = "black", lwd.global = 1, lty.global = "dotdash", cex.labels = 1, 
    cex.cat = 0.8, xlim = NULL, ylim = NULL)

Arguments

formula

An object of class “formula”. Formula for the cumulative logit model to be fitted and visualized.

data

An object of class “data.frame” containing the covariates used in formula.

global

Numeric vector to choose a subset of predictors to be included with global coefficients. Default is to include all coefficients category-specific. Numbers refer to total amount of predictors, including intercept and dummy variables.

test.rel

Provides a Likelihood-Ratio-Test to test the relevance of the explanatory covariates. The corresponding p-values will be printed as p-rel. test.rel=FALSE might save a lot of time. See also Details.

test.glob

Provides a Likelihood-Ratio-Test to test if a covariate has to be included as a category-specific covariate (in contrast to being global). The corresponding p-values will be printed as p-global. test.glob=FALSE and globcircle=FALSE might save a lot of time. See also Details.

partial

If partial=TRUE, partial proportional odds models with only one category-specific covariate are fitted. The resulting effects of the (sub)models are plotted. For further information see Details.

globcircle

If TRUE, additional circles that represent the global effects of the covariates are plotted. test.glob=FALSE and globcircle=FALSE might save a lot of time.

maxit

Maximal number of iterations to fit the cumulative logit model. See also vglm.control.

scale

If TRUE, the stars are scaled to equal maximal ray length.

nlines

If specified, nlines gives the number of lines in which the effect stars are plotted.

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.

dist.x

Optional factor to increase/decrease distances between the centers of the stars on the x-axis. 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 y-axis. 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 FALSE, all plotting is clipped to the plot region, if TRUE, all plotting is clipped to the figure region, and if NA, all plotting is clipped to the device region. See also par.

main

An overall title for the plot. See also plot.

col.fill

Color of background of the circle. See also col in par.

col.circle

Color of margin of the circle. See also col in par.

lwd.circle

Line width of the circle. See also lwd in par.

lty.circle

Line type of the circle. See also lty in par.

col.global

Color of margin of the global effects circle. See also col in par. Ignored, if globcircle = FALSE.

lwd.global

Line width of the global effects circle. See also lwd in par. Ignored, if globcircle = FALSE.

lty.global

Line type of the global effects circle. See also lty in par. Ignored, if globcircle = FALSE.

cex.labels

Size of labels for covariates placed above the corresponding star. See also cex in par.

cex.cat

Size of labels for categories placed around the corresponding star. See also cex in par.

xlim

Optional specification of the x coordinates ranges. See also xlim in plot.window

ylim

Optional specification of the y coordinates ranges. See also ylim in plot.window

Details

The underlying models are fitted with the function vglm from the package VGAM. The family argument for vglm is cumulative(parallel=FALSE).

The stars show the exponentials of the estimated coefficients. In cumulative logit models the exponential coefficients can be interpreted as odds. More precisely, the exponential e^{\gamma_{rj}}, r=1,\ldots,k-1 represents the multiplicative effect of the covariate j on the cumulative odds \frac{P(Y\leq r|x)}{P(Y>r|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 p-values beneath the covariate labels, which are given out 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 form of the circles can be modified by col.circle, lwd.circle and lty.circle.

By setting globcircle=TRUE, an addictional circle can be drawn. The radii now correspond to a model, where the respective covariate is not included category-specific but globally. Therefore, the distance between this circle and the star as a whole corresponds to the p-value p-global that is given if test.glob=TRUE.

Please note:

Regular fitting of cumulative logit models may fail because of the restrictions in the parameter space that have to be considered. If partial=TRUE, (sub)models with only one category-specific covariate, so-called partial proportional odds models, are fitted. Then at least estimates for every coefficient should be available. If partial=TRUE, the resulting effects of these (sub)models are plotted. It should be noted that in this case no coherent model is visualized. Also the p-values refer to the various submodels. For partial=TRUE, the p-values p-rel and p-global refer to tests of the corresponding partial proportial odds models against the proportional odds model.

It is strongly recommended to standardize metric covariates, display of effect stars can benefit greatly as in general differences between the coefficients are increased.

Value

P-values are only available if the corresponding option is set TRUE.

odds

Odds or exponential coefficients of the cumulative logit model

coefficients

Coefficients of the cumulative logit model

se

Standard errors of the coefficients

p_rel

P-values of Likelihood-Ratio-Tests for the relevance of the explanatory covariates

p_global

P-values of Likelihood-Ratio-Tests wether the covariates need to be included category-specific

xlim

xlim values that were automatically produced. May be helpfull if you want to specify your own xlim

ylim

ylim values that were automatically produced. May be helpfull if you want to specify your own ylim

Author(s)

Gunther Schauberger
[e-mail]
https://www.sg.tum.de/epidemiologie/team/schauberger/

References

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

Gerhard Tutz (2012): Regression for Categorical Data, Cambridge University Press

See Also

star.sequential, star.nominal

Examples

## Not run: 
data(insolvency)

star.cumulative(Insolvency ~ Sector + Employees, insolvency, select = 2:4)

## End(Not run)