lessR (version 3.7.6)

PieChart: Pie Chart

Description

Abbreviation: pc

Plots a pie chart of a categorical variable (x). The default chart is a doughnut or ring version of a pie chart, that is, a hole in the middle of the pie. Either directly enter the corresponding numerical value (y) or have the numerical variable be the tabulated counts for the frequency of occurrence for each value of the categorical variable. Also displays the frequency table for the variable with the corresponding chi-square inferential analysis. Real numbers can also be entered directly.

Usage

PieChart(x, y=NULL, data=mydata, rows=NULL,
         radius=1, hole=0.65, hole.fill=getOption("panel.fill"),
         fill=NULL, 
         color="lightgray",
         trans=getOption("trans.bar.fill"),
         density=NULL, angle=45,
         lty="solid", lwd=1, edges=200,
         clockwise=FALSE, init.angle=ifelse (clockwise, 90, 0), 
         values=getOption("values"),
         values.color=getOption("values.color"), 
	       values.cex=getOption("values.cex"),
         values.digits=getOption("values.digits"),
         values.pos=getOption("values.pos"),
         main=NULL, main.cex=1.2, labels.cex=0.9, cex,
         add=NULL, x1=NULL, y1=NULL, x2=NULL, y2=NULL,
         eval.df=NULL, quiet=getOption("quiet"),
         width=6.5, height=6, pdf.file=NULL,
         …)
pc(…)

Arguments

x

For each level of this categorical variable, x, display the frequencies as slices of a pie.

y

Numeric variable that sets the area of each slice of the pie. If not specified, then its value is the frequency of each category of x, automatically tabulated.

data

Optional data frame that contains the variable(s) of interest, default is mydata.

rows

A logical expression that specifies a subset of rows of the data frame to analyze.

radius

The pie is drawn in a box with sides that range from -1 to 1, so the maximum value of the radius without truncating the pie is 1.

hole

The proportion of the radius that defines the inner hole for what is called a doughnut or hole plot. To show the full pie, set to FALSE or the value of 0.

hole.fill

Fill color of the hole, which by default is the same color as panel.fill as set by the color theme or individually with the style function.

fill

Specified color of each slice. Default is the discrete scale with, with fixed chroma (50) and luminance (75) for unbiased comparison across colors, for all color themes except "gray" and "white", with default gray scale. Can explicitly choose "grays" or "colors" , or pre-specified R color schemes "rainbow", "terrain", and "heat". Can also provide pre-defined color ranges "blues", "reds" and "greens", as well as custom colors, such as generated by getColors.

color

Border color of sides and the pie, can be a vector to customize the color for each slice. Default is bar.color from the lessR style function.

trans

Transparency factor of the area of each slice. Default is trans.bar.fill from the lessR style function.

density

Density of shading lines, in lines per inch. Default value is NULL, that is, no shading lines.

angle

Angle of shading lines in degrees.

lty

Type of line that borders each slice, such as "solid", the default. Can be a vector. Acceptable values are "blank", "solid", "dashed", "dotted", "dotdash", and "longdash".

lwd

Width of line that borders each slice.

edges

Approximation of a circle with a polygon drawn with the number of specified edges.

clockwise

Default value of FALSE specifies to draw the slices counter-clockwise, otherwise clockwise.

init.angle

Starting angle (in degrees) for the slices. For counter-clockwise the default value is 0 (3 o'clock), otherwise 90 (12 o'clock).

values

If not the default value of "off", adds the numerical results to the plot according to "%", "prop" or "input", that is, percentages, proportions, or the value from which the slices are plotted, such as tabulated counts if y is not specified, or the value of y if the plotted values are provided. If any other values parameter is specified, default is set to "%".

values.color

Color of the plotted text. Could be a vector to specify a unique color for each value. If fewer colors are specified than the number of categories, the colors are recycled.

values.cex

Character expansion factor, the size, of the plotted text, for which the default value is 0.95.

values.digits

Number of decimal digits for which to display the values. Default is 0, round to the nearest integer, for "%" and 2 for "prop".

values.pos

Position of the plotted text. Default is inside the pie, or, if "label", as part of the label for each value outside of the pie.

main

Title of graph. Set the color with main.color with the style function.

main.cex

Character expansion factor of title relative to 1.

labels.cex

Character expansion factor of labels relative to 1.

cex

General character expansion factor for default values of main.cex, labels.cex, and values.cex. Useful for adjustment of text for larger or smaller images.

add

Draw one or more objects, text or a geometric figures, on the plot. Possible values are any text to be written, the first argument, which is "text", or, to indicate a figure, "rect" (rectangle), "line", "arrow", "v.line" (vertical line), and "h.line" (horizontal line). The value "means" is short-hand for vertical and horizontal lines at the respective means. Does not apply to Trellis graphics. Customize with parameters such as fill and color from the style function.

x1

First x coordinate to be considered for each object. All coordinates vary from -1 to 1.

y1

First y coordinate to be considered for each object.

x2

Second x coordinate to be considered for each object. Only used for "rect", "line" and arrow.

y2

Second y coordinate to be considered for each object. Only used for "rect", "line" and arrow.

eval.df

Determines if to check for existing data frame and specified variables. By default is TRUE unless the shiny package is loaded then set to FALSE so that Shiny will run. Needs to be set to FALSE if using the pipe %\>% notation.

quiet

If set to TRUE, no text output. Can change system default with style function.

width

Width of the plot window in inches, defaults to 4.5.

height

Height of the plot window in inches, defaults to 4.5.

pdf.file

Name of the pdf file to if graphics to be redirected to a pdf file.

...

Other parameter values for graphics as defined processed by pie and par for general graphics, which includes radius of the pie, and color.main for the title of the graph.

Details

OVERVIEW Plot a pie chart with default colors, presumably with a relatively small number of values for each variable. By default, colors are selected for the slices, background and grid lines, all of which can be customized. The basic computations of the chart are provided with the standard R functions pie and chisq.test and the lessR function chisq.test. A minor modification of the original pie code provides for the hole in the middle of the pie, the default doughnut or ring chart.

DATA The data may either be a vector from the global environment, the user's workspace, as illustrated in the examples below, or one or more variable's in a data frame, or a complete data frame. The default input data frame is mydata. Can specify the source data frame name with the data option. If multiple variables are specified, only the numerical variables in the list of variables are analyzed. The variables in the data frame are referenced directly by their names, that is, no need to invoke the standard R mechanisms of the mydata$name notation, the with function or the attach function. If the name of the vector in the global environment and of a variable in the input data frame are the same, the vector is analyzed.

The rows parameter subsets rows (cases) of the input data frame according to a logical expression. Use the standard R operators for logical statements as described in Logic such as & for and, | for or and ! for not, and use the standard R relational operators as described in Comparison such as == for logical equality != for not equals, and > for greater than. See the Examples.

COLORS Set the default color of the bars by the current color theme according to bar.fill.discrete argument of the function style, which includes the default color theme "colors" that defines a qualitative HCL color scale, or set the bar color with the fill parameter. These parameters reference a specified vector of color specifications, such as generated by the lessR getColors function.

Set fill to a single color or a color palette, of which there are many possibilities. Define a qualitative color palette with "colors" that provides HCL colors of the same chroma (saturation) and luminance (brightness). Also available are the pre-specified R color palettes "rainbow", "terrain", and "heat". Pre-defined sequential and divergent color ranges are available as implicit calls to getColors. The full list of pre-defined color ranges (defined in 30 degree increments around the HCL color wheel): "reds", "rusts", "yellows", "olives", "greens", "emeralds", "turquoises", "aquas", "blues", "purples","violets", "magentas", and "grays".

Defines a sequential color scale with single value of fill for a pre-defined palette such as "blues". Or, manually specify colors. For example, for a two-level by variable, could set fill to c("coral3","seagreen3"), where the specified colors are not pre-defined color ranges.

For the pre-defined color scales can obtain more control over the obtained color palettes with an explicit call to getColors for the argument to fill. Here the value of chroma (c) and luminance (l) can be explicitly manipulated in conjunction with the specification of a pre-defined color range. Or, create a custom color range for any value of hue (h). See getColors for more information.

To change the background color, set the "panel.fill" argument of the style function. The hole of the pie defaults to that color, which, of course, can also be specified to a different color.

ANNOTATIONS Use the add and related parameters to annotate the plot with text and/or geometric figures. Each object is placed according from one to four corresponding coordinates, the required coordinates to plot that object, as shown in the following table. The values of the coordinates vary from -1 to 1.

Value	Object	Required Coordinates
-----------	-------------------	----------------
text	text	x1, x2
"rect"	rectangle	x1, y1, x2, y2
"line"	line segment	x1, y1, x2, y2
"arrow"	arrow	x1, y1, x2, y2
-----------	-------------------	----------------

The value of add specifies the object. For a single object, enter a single value. Then specify the value of the needed corresponding coordinates, as specified in the above table. For multiple placements of that object, specify vectors of corresponding coordinates. To annotate multiple objects, specify multiple values for add as a vector. Then list the corresponding coordinates, for up to each of four coordinates, in the order of the objects listed in add. See the examples for illustrations.

Can also specify vectors of different properties, such as add.color. That is, different objects can be different colors, different transparency levels, etc.

STATISTICS In addition to the pie chart, descriptive and inferential statistics are presented. First, for integer variables such as counts, the frequency table with proportions is displayed. Second, the corresponding chi-square test is also displayed. For real valued variables read from a data frame, the summary statistics such as the mean are reported.

PDF OUTPUT Because lessR functions generate their own graphics calls, the standard graphic output functions such as pdf do not work with the lessR graphics functions. Instead, to obtain pdf output, use the pdf.file option, perhaps with the optional width and height options. These files are written to the default working directory, which can be explicitly specified with the R setwd function.

ONLY VARIABLES ARE REFERENCED The referenced variable in a lessR function can only be a variable name. This referenced variable must exist in either the referenced data frame, mydata by default, or in the user's workspace, more formally called the global environment. That is, expressions cannot be directly evaluated. For example:

> PieChart(rnorm(10)) # does NOT work

Instead, do the following:

    > Y <- rnorm(10)   # create vector Y in user workspace
    > PieChart(Y)     # directly reference Y

See Also

pie, chisq.test.

Examples

# NOT RUN {
# get the data from a file included with lessR
mydata <- rd("Employee", in.lessR=TRUE)

# --------------------------------------------------------
# pie (doughnut) chart from the data for a single variable
# --------------------------------------------------------

# basic pie chart, actually a doughnut or ring chart
# with default hcl colors (except for themes "gray" and "white")
PieChart(Dept)
# short name
#pc(Dept)

# standard pie chart with no hole
pc(Dept, hole=0)

# specify a unique slice color for each of the two slices
# turn off borders
PieChart(Gender, fill=c("pink","lightblue"), lty="blank")

# just males with a salary larger than 75000 USD
PieChart(Dept, rows=(Gender=="M" & Salary > 75000))

# use getColors function to create the pie slice colors
# here as a separate function call
# need to set the correct number of colors to span the full range
mycolors <- getColors(n=5, clr=getColors("aliceblue", end.clr="steelblue"))
PieChart(Dept, fill=mycolors)

# specify the colors from a predefined color palette
# see ?getColors
PieChart(Dept, fill="blues")

# display the percentage inside each slice of the pie
# provide a unique color for each displayed value
PieChart(Dept, values="%",
         values.color=c("yellow", "pink", "blue", "purple", "brown"))

# display the counts inside each slice of the pie
# reduce size of displayed counts to 0.75
PieChart(Dept, values="input", values.cex=0.75,
         values.color=getOption("window.fill"))

# add transparency and custom color for the displayed values
PieChart(Dept, trans=.6, values="%", values.color=rgb(.3,.3,.3))


# ------------------------------
# pie chart directly from counts
# ------------------------------

# from vector
# pie chart of one variable with three levels
# enter counts as a vector with the combine function, c
# must supply the level names and variable name
# use abbreviation pc for PieChart
City <- c(206, 94, 382)
names(City) <- c("LA","Chicago","NY")
pc(City, main="Employees in Each City")

# counts from data frame
x <- c("ACCT", "ADMN", "FINC", "MKTG", "SALE")
y <- c(5, 6, 4, 6, 15)
mydata <- data.frame(x,y)
names(mydata) <- c("Dept", "Count")
PieChart(Dept, Count)

# real numbers from data frame 
Dept <- c("ACCT", "ADMN", "FINC", "MKTG", "SALE")
Salary <- c(86208.42, 29808.29, 42305.52, 75855.81, 65175.51)
mydata <- data.frame(x,y)
pc(Dept, Salary)
rm(Dept)
rm(Salary)

# -----------
# annotations
# -----------

mydata <- rd("Employee", in.lessR=TRUE)

# Place a message in the center of the pie
# Use \n to indicate a new line
PieChart(Dept, add="Employees by\nDepartment", x1=0, y1=0)

# Use style to change some parameter values
style(add.trans=.8, add.fill="gold", add.color="gold4", add.lwd=0.5)
# Add a rectangle around the message centered at <0,0>
PieChart(Dept, add=c("rect", "Employees by\nDepartment"),
                     x1=c(-.4,0), y1=c(-.2, 0), x2=.4, y2=.2)

# }