# Pie Chart 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. ```r 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 ``` ## References Gerbing, D. W. (2020). R Visualizations: Derive Meaning from Data, Chapter 3, NY: CRC Press. ## Author(s) David W. Gerbing (Portland State University; gerbing@pdx.edu ) ## See Also `pie`, `chisq.test`. ## Examples ```r # 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) ```

PieChart function