ez (version 3.0-1)

ezPlot: Function to plot data from a factorial experiment

Description

This function provides easy visualization of any given user-requested effect from factorial experiments, including purely within-Ss designs (a.k.a. "repeated measures"), purely between-Ss designs, and mixed within-and-between-Ss designs. By default, Fisher's Least Significant Difference is computed to provide error bars that facilitate visual post-hoc multiple comparisons (see Warning section below).

Usage

ezPlot(
    data
    , dv
    , wid
    , within = NULL
    , between = NULL
    , between_full = NULL
    , x
    , do_lines = TRUE
    , do_bars = TRUE
    , bar_width = NULL
    , bar_size = NULL
    , split = NULL
    , row = NULL
    , col = NULL
    , to_numeric = NULL
    , x_lab = NULL
    , y_lab = NULL
    , split_lab = NULL
    , levels = NULL
    , diff = NULL
    , reverse_diff = FALSE
	, type = 2
    , dv_levs = NULL
    , dv_labs = NULL
    , row_y_free = FALSE
)

Arguments

data

Data frame containing the data to be analyzed. OR, if multiple values are specified in dv, a list with as many element as values specified in dv, each element specifying a data frame for each dv in sequence.

dv

.() object specifying the column in data that contains the dependent variable. Values in this column should be of the numeric class. Multiple values will yield a plot with dv mapped to row.

wid

.() object specifying the column in data that contains the variable specifying the case/Ss identifier. Values in this column will be converted to factor class if necessary.

within

Optional .() object specifying the column(s) in data that contains predictor variables that are manipulated within-Ss. Values in this column will be converted to factor class if necessary.

between

Optional .() object specifying the column(s) in data that contains predictor variables that are manipulated between-Ss. Values in this column will be converted to factor class if necessary.

between_full

Same as between, but must specify the full set of between-Ss variables if between specifies only a subset of the design.

x

.() object specifying the variable to plot on the x-axis.

do_lines

Logical. If TRUE, lines will be plotted connecting groups of points.

do_bars

Logical. If TRUE, error bars will be plotted.

bar_width

Optional numeric value specifying custom widths for the error bar hat.

bar_size

Optional numeric value or vector specifying custom size of the error bars.

split

Optional .() object specifying a variable by which to split the data into different shapes/colors (and line types, if do_lines==TRUE).

row

Optional .() object specifying a variable by which to split the data into rows.

col

Optional .() object specifying a variable by which to split the data into columns.

to_numeric

Optional .() object specifying any variables that need to be converted to the numeric class before plotting.

x_lab

Optional character string specifying the x-axis label.

y_lab

Optional character string specifying the y-axis label.

split_lab

Optional character string specifying the key label.

levels

Optional named list where each item name matches a factored column in data that needs either reordering of levels, renaming of levels, or both. Each item should be a list containing named elements new_order or new_names

diff

Optional .() object specifying a 2-level within-Ss varbiable to collapse to a difference score.

reverse_diff

Logical. If TRUE, triggers reversal of the difference collapse requested by diff.

type

Numeric value (either 1, 2 or 3) specifying the Sums of Squares "type" to employ when data are unbalanced (eg. when group sizes differ). See ezANOVA for details.

dv_levs

Optional character vector specifying the factor ordering of multiple values specified in dv.

dv_labs

Optional character vector specifying new factor labels for each of the multiple values specified in dv.

row_y_free

Logical. If TRUE, then rows will permit different y-axis scales.

Value

• A printable/modifiable ggplot2 object.

Warning

The default error bars are Fisher's Least Significant Difference for the plotted effect, facilitating visual post-hoc multiple comparisons. Note however that in the context of mixed within-and-between-Ss designs, these bars can only be used for within-Ss comparisons.

Details

While within and between are both optional, at least one column of data must be provided to either within or between. Any numeric or character variables in data that are specified as either wid, within or between will be converted to a factor with a warning. Fisher's Least Significant Difference is computed as sqrt(2)*qt(.975,DFd)*sqrt(MSd/N), where N is taken as the mean N per group in cases of unbalanced designs.

See Also

ANT, ANT2, ezANOVA, ezBoot, ezBootPlot, ezCor, ezDesign, ezMixed, link{ezMixedRel}, ezPerm, ezPlot, ezPrecis, ezPredict, ezResample, ezStats, progress_time, progress_timeCI

Examples

#Read in the ANT data (see ?ANT).
data(ANT)
head(ANT)
ezPrecis(ANT)


#Run an ANOVA on the mean correct RT data.
mean_rt_anova = ezANOVA(
    data = ANT[ANT$error==0,]
    , dv = .(rt)
    , wid = .(subnum)
    , within = .(cue,flank)
    , between = .(group)
)

#Show the ANOVA & assumption tests.
print(mean_rt_anova)


#Plot the main effect of group.
group_plot = ezPlot(
    data = ANT[ANT$error==0,]
    , dv = .(rt)
    , wid = .(subnum)
    , between = .(group)
    , x = .(group)
    , do_lines = FALSE
    , x_lab = 'Group'
    , y_lab = 'RT (ms)'
)

#Show the plot.
print(group_plot)


#Re-plot the main effect of group, using the levels
##argument to re-arrange/rename levels of group
group_plot = ezPlot(
    data = ANT[ANT$error==0,]
    , dv = .(rt)
    , wid = .(subnum)
    , between = .(group)
    , x = .(group)
    , do_lines = FALSE
    , x_lab = 'Group'
    , y_lab = 'RT (ms)'
    , levels = list(
        group = list(
            new_order = c('Treatment','Control')
            , new_names = c('Treatment
Group','Control
Group')
        )
    )
)

#Show the plot.
print(group_plot)


#Plot the cue*flank interaction.
cue_by_flank_plot = ezPlot(
    data = ANT[ANT$error==0,]
    , dv = .(rt)
    , wid = .(subnum)
    , within = .(cue,flank)
    , x = .(flank)
    , split = .(cue)
    , x_lab = 'Flanker'
    , y_lab = 'RT (ms)'
    , split_lab = 'Cue'
)

#Show the plot.
print(cue_by_flank_plot)


#Plot the cue*flank interaction by collapsing the cue effect to 
##the difference between None & Double
cue_by_flank_plot2 = ezPlot(
    data = ANT[ ANT$error==0 & (ANT$cue %in% c('None','Double')) ,]
    , dv = .(rt)
    , wid = .(subnum)
    , within = .(flank)
    , diff = .(cue)
    , reverse_diff = TRUE
    , x = .(flank)
    , x_lab = 'Flanker'
    , y_lab = 'RT Effect (None - Double, ms)'
)

#Show the plot.
print(cue_by_flank_plot2)



#Plot the group*cue*flank interaction.
group_by_cue_by_flank_plot = ezPlot(
    data = ANT[ANT$error==0,]
    , dv = .(rt)
    , wid = .(subnum)
    , within = .(cue,flank)
    , between = .(group)
    , x = .(flank)
    , split = .(cue)
    , col = .(group)
    , x_lab = 'Flanker'
    , y_lab = 'RT (ms)'
    , split_lab = 'Cue'
)

#Show the plot.
print(group_by_cue_by_flank_plot)


#Plot the group*cue*flank interaction in both error rate and mean RT.
group_by_cue_by_flank_plot_both = ezPlot(
    data = list(
        ANT
        , ANT[ANT$error==0,]
    )
    , dv = .(error,rt)
    , wid = .(subnum)
    , within = .(cue,flank)
    , between = .(group)
    , x = .(flank)
    , split = .(cue)
    , col = .(group)
    , x_lab = 'Flanker'
    , split_lab = 'Cue'
    , dv_labs = c('ER (%)', 'RT (ms)')
    , row_y_free = TRUE
)

#Show the plot.
print(group_by_cue_by_flank_plot_both)