Help for package EffectStars2

Type:

Package

Title:

Effect Stars

Version:

0.1-3

Date:

2019-10-22

Author:

Gunther Schauberger

Maintainer:

Gunther Schauberger <gunther.schauberger@tum.de>

Description:

Provides functions for the method of effect stars as proposed by Tutz and Schauberger (2013) <doi:10.1080/10618600.2012.701379>. Effect stars can be used to visualize estimates of parameters corresponding to different groups, for example in multinomial logit models. Beside the main function 'effectstars' there exist methods for special objects, for example for 'vglm' objects from the 'VGAM' package.

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Imports:

VGAM, miscTools

Suggests:

DIFlasso, DIFboost, VGAMdata

RoxygenNote:

6.1.1

NeedsCompilation:

Packaged:

2019-10-22 09:03:05 UTC; ge29weh

Repository:

CRAN

Date/Publication:

2019-10-22 09:40:02 UTC

Plot EffectStars

Description

The package provides functions for the method of effect stars as proposed by Tutz and Schauberger (2013). Beside the main function effectstars there exist methods for special objects, for example for vglm-objects.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Tutz, G. and Schauberger, G. (2013): Visualization of Categorical Response Models - from Data Glyphs to Parameter Glyphs, Journal of Computational and Graphical Statistics, 22(1), 156–177

Plot effect stars for DIFboost objects.

Description

Plots effect stars for DIFboost-objects. The parameter estimates for DIF-items are plotted, grouped by items.

For more details on plotting effect stars see effectstars.

Usage

## S3 method for class 'DIFboost'
effectstars(x, only.DIFitems = TRUE, ...)

Arguments

x

A DIFboost-object.

only.DIFitems

If TRUE, only the estimates unequal to zero (estimates from the DIF-items) are visualized with EffectStars.

...

further arguments for generic function effectstars.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Schauberger, G. and Tutz, G. (2016): Detection of Differential Item Functioning in Rasch Models by Boosting Techniques, British Journal of Mathematical and Statistical Psychology, 69(1), 80 - 103

Tutz, G. and Schauberger, G. (2013): 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

Examples

## Not run: 
### example for DIFboost

library(DIFboost)
data(simul.data)

Y <- simul.data[,1:10]
X <- simul.data[,11:13]

m1 <- DIFboost(Y = Y, X = X) 

effectstars(m1)


## End(Not run)

Plot effect stars for DIFlasso objects.

Description

Plots effect stars for DIFlasso-objects. The parameter estimates for DIF-items are plotted, grouped by items.

For more details on plotting effect stars see effectstars.

Usage

## S3 method for class 'DIFlasso'
effectstars(x, only.DIFitems = TRUE, ...)

Arguments

x

A DIFlasso-object.

only.DIFitems

If TRUE, only the estimates unequal to zero (estimates from the DIF-items) are visualized with EffectStars.

...

further arguments for generic function effectstars.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Tutz, G. and Schauberger, G. (2015): A Penalty Approach to Differential Item Functioning in Rasch Models, , Psychometrika, 80(1), 21 – 43

Tutz, G. and Schauberger, G. (2013): 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

Examples

## Not run: 
### example for DIFlasso

library(DIFlasso)
data(simul.data)

Y <- simul.data[,1:10]
X <- simul.data[,11:13]

m1 <- DIFlasso(Y = Y, X = X, trace = TRUE) 

effectstars(m1)


## End(Not run)

Plot effect stars.

Description

Plots effect stars for grouped coefficients. Effect stars are applicable if the parameters of a model are grouped in some sense. For example, the parameters of a multinomial logit models are grouped by the covariates, i.e. per covariate there is one estimate per response category. But also in many other models, the parameters can have a fixed grouping structure. All estimates have to be positive, typically the exponentials of the estimates are plotted. Every effect star comes with a circle of radius 1. This circle represents the case of no effect, i.e. exp(0)=1.

Usage

## Default S3 method:
effectstars(x, names = NULL, subs = NULL,
  labels = NULL, control = star.ctrl(), cols = NULL, fixed = FALSE,
  scale = 1, ...)

Arguments

x

A matrix containing all coefficients to plot, one column per group/covariate, one row per category. If the arguments names and labels are not specified, the colnames and rownames of x are used.

names

A vector containing all group/covariate names, will be used as titles of single effect stars. If NULL, colnames of x is used.

subs

A vector containing all subtitles, one per group/covariate.

labels

A vector or a matrix containing labels of the categories. If labels is a matrix, it needs to have the same dimensions as x. Otherwise, labels is a vector with length equal to the number of categories, i.e. number rows of x. If NULL, rownames of x is used.

control

Control argument (to set graphical parameters) for method effectstars, see star.ctrl.

cols

Number of columns for arranging effect stars

fixed

If TRUE, all circles have the same radius. If FALSE, every star is scaled so that the length of the longest ray is equal for all stars.

scale

Global factor to increase (scale>1) or decrease (scale<1) the size of the stars.

...

possible further arguments

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Tutz, G. and Schauberger, G. (2013): 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

Examples

## Not run: 
#####################
### Simple example for basic effectstars function
p <- 4; k <- 5
coefs <- matrix(exp(rnorm(p*k,sd=0.5)),ncol=k)
rownames(coefs) <- paste("Variable",1:p)
colnames(coefs) <- paste("Cat",1:k)
effectstars(coefs)

#####################
### Example for effect stars for a multivariate logit model
data(xs.nz, package = "VGAMdata")
xs.nz$age <- scale(xs.nz$age)
library(VGAM)

cats_dogs <- vglm(cbind(cat, dog) ~ age +  sex + marital, 
                  data = xs.nz, family = binom2.or(zero = NULL))

summary(cats_dogs)

## quick and dirty
effectstars(exp(coef(cats_dogs, matrix = TRUE)))


## make it pretty
# create the effects matrix you want to plot, name rows and columns
effects <- exp(coef(cats_dogs, matrix = TRUE))
colnames(effects) <- c("cat", "dog", "OR")
rownames(effects) <- c("Intercept", "Age", "Gender", rep("Marital", 3))

# create subtitles containing category labels of predictors
subs <- c(rep("",2), "(male)", "(married)", "(separated/divorced)", "(widowed)")

# create labels containing the response categories and all p-values
p_values <- formatC(summary(cats_dogs)@coef3[,4], format="f", digits=3)
labels <- matrix(paste0(rep(c("cat", "dog", "OR"), nrow(effects)), "\n(", p_values, ")"),
byrow = TRUE, ncol = 3)

# plot effectstars
effectstars(effects, labels = labels, subs = subs)


#####################
## Example for method effectstars.vglm for a multinomial logit model calculated in VGAM
data(election) 
library(VGAM)
m_elect <- vglm(Partychoice ~ Gender + West + Age + Union + Highschool + Unemployment
+ Pol.Interest + Democracy + Religion, family = multinomial(), data = election)
effectstars(m_elect)

## End(Not run)

Plot effect stars for vglm objects.

Description

Plots effect stars for vglm-objects. In particular, the method works for multinomial logit models created by family multinomial and for models with ordinal response like sratio, cratio, cumulative or acat.

For more details on plotting effect stars see effectstars.

Usage

## S3 method for class 'vglm'
effectstars(x, p.values = FALSE, symmetric = TRUE,
  plot.parallel = FALSE, ...)

Arguments

x

A vglm-object.

p.values

Should the p-values of the single coefficients be included in the labels? Default is FALSE.

symmetric

Should the parameters be transformed to parameters with symmetric (sum-to-zero) side constraints instead of using reference levels. Default is TRUE for multinomial-models. If the multinomial-model contains object-specific covariates (xij argument from vglm.control) symmetric side constraints are not possible. In ordinal response models, no side constraints are needed and the option is obsolete.

plot.parallel

Should parallel parameters (equal over all response categories) be represented by effect stars. Default is FALSE.

...

further arguments for generic function effectstars.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Examples

## Not run: 
############################################
### Examples for multinomial logit model
############################################

### German election data
data(election) 
library(VGAM)
m_elect <- vglm(Partychoice ~ Gender + West + Age + Union + Highschool + Unemployment
+ Pol.Interest + Democracy + Religion, family = multinomial(), data = election)

effectstars(m_elect)

# include p.values
effectstars(m_elect, p.values = TRUE)

### German election data with category-specific covariates

data(election)
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

m.all <- vglm(Partychoice ~ Social + Immigration + Nuclear + Left_Right + Age + 
                Religion + Democracy + Pol.Interest + Unemployment + Highschool + Union + West + 
                Gender, data = election, 
                family = multinomial(parallel = TRUE~-1 + Social + Immigration + 
                Nuclear + Left_Right, refLevel = 1),
              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),
              form2 = ~Social + Immigration + Nuclear + Left_Right + Age + 
                Religion + Democracy + Pol.Interest + Unemployment + Highschool + Union + West + 
                Gender + Social_SPD + Social_FDP + Social_Greens + Social_Left +
                Immigration_SPD + Immigration_FDP + Immigration_Greens + Immigration_Left +
                Nuclear_SPD + Nuclear_FDP + Nuclear_Greens + Nuclear_Left +
                Left_Right_SPD + Left_Right_FDP + Left_Right_Greens + Left_Right_Left
)

effectstars(m.all, symmetric = FALSE, p.values = TRUE)
summary(m.all)


### Chilean plebiscite data
data(plebiscite)
m_chile <- vglm(Vote ~ ., family = multinomial(), data = plebiscite)
effectstars(m_chile)

# choose fixed circle sizes and use reference category instead of symmetric side constraints
effectstars(m_chile, symmetric = FALSE, fixed = TRUE)

############################################
### Examples for ordinal data
############################################

### Munich insolvency data
data(insolvency)
insolvency$Age <- scale(insolvency$Age)

my_formula <- Insolvency ~ Age + Gender

m_acat <- vglm(my_formula, data = insolvency,family = acat())
m_cratio <- vglm(my_formula, data = insolvency,family = cratio())
m_sratio <- vglm(my_formula, data = insolvency,family = sratio())
m_cumulative <- vglm(my_formula, data = insolvency,family = cumulative())

summary(m_acat)
effectstars(m_acat, p.values = TRUE)

summary(m_cratio)
effectstars(m_cratio, p.values = TRUE)

summary(m_sratio)
effectstars(m_sratio, p.values = TRUE)

summary(m_cumulative)
effectstars(m_cumulative, p.values = TRUE)

## End(Not run)

Election Data

Description

The data set contains data from the German Longitudinal Election Study. The response categories refer to the five dominant parties in Germany. The explanatory variables refer to the declarations of single voters.

Format

A data frame with 816 observations on the following 30 variables.

Age: Standardized age of the voter
AgeOrig: Unstandardized age of the voter
Partychoice: Party Choice with levels CDU, SPD, FDP, Greens and Left Party
Gender: Gender with levels female and male
West: Regional provenance (West-Germany or East-Germany) with levels east and west
Union: Member of a Union with levels no member and member
Highschool: Educational level with levels no highschool and highschool
Unemployment: Unemployment with levels not unemployed and unemployed
Pol.Interest: Political Interest with levels very interested and less interested
Democracy: Satisfaction with the functioning of democracy with levels satisfied and not satisfied
Religion: Religion with levels evangelical, catholic and other religion
Social_CDU: Difference in attitude towards the socioeconomic dimension of politics between respondent and CDU
Social_SPD: Difference in attitude towards the socioeconomic dimension of politics between respondent and SPD
Social_FDP: Difference in attitude towards the socioeconomic dimension of politics between respondent and FDP
Social_Greens: Difference in attitude towards the socioeconomic dimension of politics between respondent and the Greens
Social_Left: Difference in attitude towards the socioeconomic dimension of politics between respondent and the Left party
Immigration_CDU: Difference in attitude towards immigration of foreigners between respondent and CDU
Immigration_SPD: Difference in attitude towards immigration of foreigners between respondent and SPD
Immigration_FDP: Difference in attitude towards immigration of foreigners between respondent and FDP
Immigration_Greens: Difference in attitude towards immigration of foreigners between respondent and the Greens
Immigration_Left: Difference in attitude towards immigration of foreigners between respondent and the Left party
Nuclear_CDU: Difference in attitude towards nuclear energy between respondent and CDU
Nuclear_SPD: Difference in attitude towards nuclear energy between respondent and SPD
Nuclear_FDP: Difference in attitude towards nuclear energy between respondent and FDP
Nuclear_Greens: Difference in attitude towards nuclear energy between respondent and the Greens
Nuclear_Left: Difference in attitude towards nuclear energy between respondent and the Left party
Left_Right_CDU: Difference in attitude towards the positioning on a political left-right scale between respondent and CDU
Left_Right_SPD: Difference in attitude towards the positioning on a political left-right scale between respondent and SPD
Left_Right_FDP: Difference in attitude towards the positioning on a political left-right scale between respondent and FDP
Left_Right_Greens: Difference in attitude towards the positioning on a political left-right scale between respondent and the Greens
Left_Right_Left: Difference in attitude towards the positioning on a political left-right scale between respondent and the Left party

References

German Longitudinal Election Study (GLES)

Examples


data(election) 
library(VGAM)
m_elect <- vglm(Partychoice ~ Gender + West + Age + Union + Highschool + Unemployment
+ Pol.Interest + Democracy + Religion, family = multinomial(), data = election)

effectstars(m_elect)

Insolvency data

Description

The data set originates from the Munich founder study. The data were collected on business founders who registered their new companies at the local chambers of commerce in Munich and surrounding administrative districts. The focus was on survival of firms measured in 7 categories, the first six represent failure in intervals of six months, the last category represents survival time beyond 36 months.

Format

A data frame with 1224 observations on the following 16 variables.

Insolvency: Survival of firms in ordered categories with levels 1 < 2 < 3 < 4 < 5 < 6 < 7
Sector: Economic Sector with levels industry, commerce and service industry
Legal: Legal form with levels small trade, one man business, GmBH and GbR, KG, OHG
Location: Location with levels residential area and business area
New_Foundation: New Foundation or take-over with levels new foundation and take-over
Pecuniary_Reward: Pecuniary reward with levels main and additional
Seed_Capital: Seed capital with levels < 25000 and > 25000
Equity_Capital: Equity capital with levels no and yes
Debt_Capital: Debt capital with levels no and yes
Market: Market with levels local and national
Clientele: Clientele with levels wide spread and small
Degree: Educational level with levels no A-levels and A-Levels
Gender: Gender with levels female and male
Experience: Professional experience with levels < 10 years and > 10 years
Employees: Number of employees with levels 0 or 1 and > 2
Age: Age of the founder at formation of the company

Source

Muenchner Gruender Studie

References

Bruederl, J. and Preisendoerfer, P. and Ziegler, R. (1996): Der Erfolg neugegruendeter Betriebe: eine empirische Studie zu den Chancen und Risiken von Unternehmensgruendungen, Duncker & Humblot.

Examples


## Not run: 
data(insolvency)
insolvency$Age <- scale(insolvency$Age)

my_formula <- Insolvency ~ Age + Gender

m_acat <- vglm(my_formula, data = insolvency,family = acat())
m_cratio <- vglm(my_formula, data = insolvency,family = cratio())
m_sratio <- vglm(my_formula, data = insolvency,family = sratio())
m_cumulative <- vglm(my_formula, data = insolvency,family = cumulative())

summary(m_acat)
effectstars(m_acat, p.values = TRUE)

summary(m_cratio)
effectstars(m_cratio, p.values = TRUE)

summary(m_sratio)
effectstars(m_sratio, p.values = TRUE)

summary(m_cumulative)
effectstars(m_cumulative, p.values = TRUE)

## End(Not run)

Chilean Plebiscite

Description

The data origin from a survey refering to the plebiscite in Chile 1988. The chilean people had to decide, wether Augusto Pinochet would remain president for another ten years (voting yes) or if there would be presidential elections in 1989 (voting no).

Format

A data frame with 2431 observations on the following 7 variables.

Gender: Gender with levels female and male
Education: Educational level with levels low and high
SantiagoCity: Respondent from Santiago City with levels no and yes
Income: (Standardized) Monthly Income in Pesos
Population: (Standardized) Population size of respondent's community
Age: (Standardized) Age in years
Vote: Response with levels Abstention, No, Undecided and Yes

Source

R package carData: Chile

References

Fox, J. (2008): Applied Regression Analysis and Generalized Linear Models, Second Edition.

Examples


## Not run: 
data(plebiscite)
m_chile <- vglm(Vote ~ ., family = multinomial(), data = plebiscite)

effectstars(m_chile)

## End(Not run)

Control function for effect stars.

Description

Control function to set graphical parameters for method effectstars.

Usage

star.ctrl(lwd.circle = 1, col.circle = "yellowgreen",
  lty.circle = "solid", col.fill = "yellowgreen", lwd.star = 1.5,
  cex.main = 1.5, cex.labels = 1, col.main = "black",
  col.labels = "black", col.star = "black", dist.labels = 1,
  font.labels = 1, radius = 1)

Arguments

lwd.circle

Line width of circle.

col.circle

Color of circle, possibly a vector with one value per covariate.

lty.circle

Line type of circle.

col.fill

Color to fill the circle, possibly a vector with one value per covariate.

lwd.star

Line width for effect star.

cex.main

Size of mains.

cex.labels

Size of labels.

col.main

Color of mains.

col.labels

Colors of labels. Can be a vector (one value/color per category) or a even matrix (one column per category, one row per star).

col.star

Color of effect star.

dist.labels

Tuning parameter for distance of labels from effect star. Default is 1, higher values increase the distance of the labels to effect stars. Can also be specified as a vector, containing one value per star.

font.labels

Font type of labels. Can be a vector (one value/color per category) or a even matrix (one column per category, one row per star).

radius

Radius for circle. Can also be specified as a vector, containing one value per star.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

https://www.sg.tum.de/epidemiologie/team/schauberger/

References

Examples

## Not run: 
data(election) 
library(VGAM)

m_elect <- vglm(Partychoice ~ Gender + West + Age + Union + Highschool + Unemployment
+ Pol.Interest + Democracy + Religion, family = multinomial(), data = election)

ctrl <- star.ctrl(col.labels = c("black","red2","yellow2","green2","darkred"), 
col.star = "darkgray", col.fill = "lightblue", col.circle = "darkgray", 
cex.labels = 1.1)

effectstars(m_elect, control = ctrl)

## End(Not run)

Plot EffectStars

Description

Author(s)

References

See Also

Plot effect stars for DIFboost objects.

Description

Usage

Arguments

Author(s)

References

See Also

Examples

Plot effect stars for DIFlasso objects.

Description

Usage

Arguments

Author(s)

References

See Also

Examples

Plot effect stars.

Description

Usage

Arguments

Author(s)

References

See Also

Examples

Plot effect stars for vglm objects.

Description

Usage

Arguments

Author(s)

References

See Also

Examples

Election Data

Description

Format

References

Examples

Insolvency data

Description

Format

Source

References

Examples

Chilean Plebiscite

Description

Format

Source

References

Examples

Control function for effect stars.

Description

Usage

Arguments

Author(s)

References

See Also

Examples