R: Pie Chart

PieChart {lessR}

R Documentation

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=d, filter=NULL,

         radius=1, hole=0.65, hole_fill=getOption("panel_fill"),

         theme=getOption("theme"),
         fill=NULL, 
         color="lightgray",
         transparency=getOption("trans_bar_fill"),

         density=NULL, angle=45,
         lty="solid", lwd=1, edges=200,

         clockwise=FALSE, init_angle=ifelse (clockwise, 90, 0), 

         labels=getOption("labels"),
         labels_color=getOption("labels_color"),
         labels_size=getOption("labels_size"),
         labels_digits=getOption("labels_digits"),
         labels_position=getOption("labels_position"),

         main=NULL, main_cex=getOption("main_cex")*1.2,
         labels_cex=getOption("lab_cex"), cex,

         add=NULL, x1=NULL, y1=NULL, x2=NULL, y2=NULL,

         rows=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. Applied to reading the summary table of the already aggregated data as the data for the pie chart.
`data`	Optional data frame that contains the variable(s) of interest, default is `d`.
`filter`	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.

`theme`	Selected color theme, change with `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 `"hues"` , or pre-specified R color schemes `"rainbow"`, `"terrain"`, and `"heat"`. Or, set to the name of `y` to map the values of bar fill, specified as `(count)` if tabulated from the data. 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.
`transparency`	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).

`labels`	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 `labels` parameter is specified, default is set to `"%"`.
`labels_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.
`labels_size`	Character expansion factor, the size, of the plotted text, for which the default value is 0.95.
`labels_digits`	Number of decimal digits for which to display the values_ Default is 0, round to the nearest integer, for `"%"` and 2 for `"prop"`.
`labels_position`	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. No labels if set to 0.
`cex`	General character expansion factor for default values of main_cex, labels_cex, and values_size. 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`.

rows

Deprecated old parameter name that is now called filter.

`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 d. 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 d$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 "hues" 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", "browns", "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, d 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

Author(s)

David W. Gerbing (Portland State University; gerbing@pdx.edu)

References

Gerbing, D. W. (2020). R Visualizations: Derive Meaning from Data, Chapter 3, NY: CRC Press.

Examples

# get the data from a file included with lessR
d <- rd("Employee")

# --------------------------------------------------------
# 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("aliceblue", end_pal="steelblue", n=5)
PieChart(Dept, fill=mycolors)

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

# viridis color palette
PieChart(Dept, fill="viridis")

# display the percentage inside each slice of the pie
# provide a unique color for each displayed value
PieChart(Dept, labels="%",
         labels_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, labels="input", labels_size=0.75,
         labels_color=getOption("window_fill"))

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

# map counts of each level to the fill color of the corresponding slice
PieChart(JobSat, fill=(count))


# ------------------------------
# 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)
d <- data.frame(x,y)
names(d) <- 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)
d <- data.frame(x,y)
pc(Dept, Salary)
rm(Dept)
rm(Salary)

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

d <- rd("Employee")

# 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)

[Package lessR version 4.3.6 Index]