Density Curves from Data plus Histogram

Description

Abbreviation: dn

Plots a normal density curve and/or a general density curve superimposed over a histogram, all estimated from the data. Also reports the Shapiro-Wilk normality test and summary statistics.

If the provided object to analyze is a set of multiple variables, including an entire data frame, then each non-numeric variable in the data frame is analyzed and the results written to a pdf file in the current working directory. The name of each output pdf file that contains a bar chart and its path are specified in the output.

When output is assigned into an object, such as d in d <- dn(Y), the pieces of output can be accessed for later analysis. A primary such analysis is knitr for dynamic report generation from an R markdown document in which R output is embedded in documents, facilitated by the Rmd option. See value below.

Usage

Density(x, data=mydata, n.cat=getOption("n.cat"), 

       bw="nrd0", type=c("both", "general", "normal"),
       bin.start=NULL, bin.width=NULL,

       Rmd=NULL, digits.d=NULL,

       color.fill=getOption("color.fill.pt"),
       color.bg=getOption("color.bg"),
       color.grid=getOption("color.grid"),
       color.box=getOption("color.box"),

       color.nrm="black", color.gen="black",
       color.fill.nrm=NULL, color.fill.gen=NULL,

       cex.axis=0.75, color.axis="gray30",

       rotate.values=0, offset=0.5,

       x.pt=NULL, xlab=NULL, main=NULL, sub=NULL, y.axis=FALSE, 
       x.min=NULL, x.max=NULL, band=FALSE, 

       quiet=getOption("quiet"),
       pdf.file=NULL, pdf.width=5, pdf.height=5,
       fun.call=NULL, ...)

dn(...)

Arguments

Details

OVERVIEW
Results are based on the standard dnorm function and density R functions for estimating densities from data, as well as the hist function for calculating a histogram. Colors are provided by default and can also be specified.

The default histogram can be modified with the bin.start and bin.width options. Use the Histogram function in this package for more control over the parameters of the histogram.

The limits for the axes are automatically calculated so as to provide sufficient space for the density curves and histogram, and should generally not require user intervention. Also, the curves are centered over the plot window so that the resulting density curves are symmetric even if the underlying histogram is not. The estimated normal curve is based on the corresponding sample mean and standard deviation.

If x.pt is specified, then type is set to general and y.axis set to TRUE.

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.

COLOR THEME
Individual colors in the plot can be manipulated with options such as color.bars for the color of the histogram bars. A color theme for all the colors can be chosen for a specific plot with the colors option with the lessR function theme. The default color theme is blue, but a gray scale is available with "gray", and other themes are available as explained in theme, such as "red" and "green". Use the option ghost=TRUE for a black background, no grid lines and partial transparency of plotted colors.

VARIABLE LABELS
If variable labels exist, then the corresponding variable label is by default listed as the label for the horizontal axis and on the text output. For more information, see Read.

PDF OUTPUT
Because of the customized graphic windowing system that maintains a unique graphic window for the Help function, 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 pdf.width and pdf.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 (or list of variable names). This referenced variable must exist in either the referenced data frame, such as the default mydata, or in the user's workspace, more formally called the global environment. That is, expressions cannot be directly evaluated. For example:

> Density(rnorm(50)) # does NOT work

Instead, do the following:

    > Y <- rnorm(50)   # create vector Y in user workspace
    > Density(Y)     # directly reference Y

Value

The output can optionally be saved into an R object, otherwise it simply appears in the console. Redesigned in lessR version 3.3 to provide two different types of components: the pieces of readable output, and a variety of statistics. The readable output are character strings such as tables amenable for reading. The statistics are numerical values amenable for further analysis. The motivation of these types of output is to facilitate R markdown documents, as the name of each piece, preceded by the name of the saved object and a $, can be inserted into the R~Markdown document (see examples).

READABLE OUTPUT
codeout_title: Title of output
codeout_stats: Statistics
codeout_file: Name and location of optional R markdown file

STATISTICS
codebw: Bandwidth parameter
coden: Number of data values analyzed
coden.miss: Number of missing data values
codeW: W statistic for Shapiro-Wilk normality test
codepvalue: p-value for W statistic

Although not typically needed, if the output is assigned to an object named, for example, h, then the contents of the object can be viewed directly with the unclass function, here as unclass(h).

Author(s)

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

See Also

dnorm, density, hist, plot, rgb, shapiro.test.

Examples

# create data frame, mydata, to mimic reading data with Read function
# mydata contains both numeric and non-numeric data
mydata <- data.frame(rnorm(50), rnorm(50), rnorm(50), rep(c("A","B"),25))
names(mydata) <- c("X","Y","Z","C")

# normal curve and general density curves superimposed over histogram
# all defaults
Density(Y)

# short name
dn(Y)

# save the density plot to a pdf file
Density(Y, pdf.file="MyDensityPlot.pdf")

# suppress the histogram, leaving only the density curves
# specify x-axis label per the xlab option for the plot function
Density(Y, color.fill="transparent", xlab="My Var")

# specify (non-transparent) colors for the curves,
# to make transparent, need alpha option for the rgb function
Density(Y, color.nrm="darkgreen", color.gen="plum")

# display only the general estimated density
#  so do not display the estimated normal curve
# specify the bandwidth for the general density curve,
#  use the standard bw option for the density function
Density(Y, type="general", bw=.6)

# display only the general estimated density and a corresponding
#  interval of unit width around x.pt
Density(Y, type="general", x.pt=2)

# generate R markdown file to be "knit" such as in RStudio
dn(Y, Rmd="myout")

# variable of interest is in a data frame which is not the default mydata
# access the breaks variable in the R provided warpbreaks data set
# although data not attached, access the variable directly by its name
Density(breaks, data=warpbreaks)

# densities for all numeric variables in a data frame
Density()

# densities for all specified numeric variables in a list of variables
# e.g., use the combine or c function to specify a list of variables
Density(c(X,Y))

Results