Package 'EffectStars2'

Title: Effect Stars
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.
Authors: Gunther Schauberger
Maintainer: Gunther Schauberger <[email protected]>
License: GPL (>= 2)
Version: 0.1-3
Built: 2024-11-08 02:56:13 UTC
Source: https://github.com/cran/EffectStars2

Help Index


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
[email protected]

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

See Also

effectstars, star.ctrl, effectstars.vglm, effectstars.DIFlasso, effectstars.DIFboost


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
[email protected]

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

See Also

star.ctrl, effectstars.vglm, effectstars.DIFlasso, effectstars.DIFboost

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 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
[email protected]

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

See Also

star.ctrl, effectstars

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
[email protected]

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

See Also

star.ctrl, effectstars

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 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
[email protected]

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

See Also

effectstars effectstars.DIFlasso

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
[email protected]

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

See Also

effectstars

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)