Share via

rxHistogram: Histogram

  • Article

Description

Histogram plot for a variable in an .xdf file or data frame

Usage

  rxHistogram(formula, data, pweights = NULL, fweights = NULL, numBreaks = NULL,
              startVal = NULL, endVal = NULL, levelsToDrop = NULL,
              levelsToKeep = NULL, rowSelection = NULL, transforms = NULL,
              transformObjects = NULL, transformFunc = NULL, transformVars = NULL, 
              transformPackages = NULL, transformEnvir = NULL,
              blocksPerRead = rxGetOption("blocksPerRead"), 
              histType = "Counts", 
              title = NULL, subtitle = NULL, xTitle = NULL, yTitle = NULL,
              xNumTicks = NULL, yNumTicks = NULL, xAxisMinMax = NULL,
              yAxisMinMax = NULL, fillColor = "cyan", lineColor = "black",
              lineStyle = "solid", lineWidth = 1, plotAreaColor = "gray90",
              gridColor = "white", gridLineWidth = 1, gridLineStyle = "solid",
              maxNumPanels = 100, reportProgress = rxGetOption("reportProgress"),
              print = TRUE, ...)

Arguments

formula

formula describing the data to plot. It should take the form of ~x|g1 + g2 where g1 and g2 are optional conditioning factor variables and x is the name of a variable or an on-the-fly factorization F(x). Other expressions of x are not supported.

data

either an RxXdfData object, a character string specifying the .xdf file, or a data frame containing the variable to plot.

pweights

character string specifying the variable to use as probability weights for the observations.

fweights

character string specifying the variable to use as frequency weights for the observations.

numBreaks

number of breaks to use to cut numeric data, including the upper and lower bounds.

startVal

low value used for cutting numeric data.

endVal

high value used for cutting numeric data.

levelsToDrop

levels to exclude if the histogram variable is a factor.

levelsToKeep

levels to keep if the histogram variable is a factor.

rowSelection

name of a logical variable in the data set (in quotes) or a logical expression using variables in the data set to specify row selection. For example, rowSelection = "old" will use only observations in which the value of the variable old is TRUE. rowSelection = (age > 20) & (age < 65) & (log(income) > 10) will use only observations in which the value of the age variable is between 20 and 65 and the value of the log of the income variable is greater than 10. The row selection is performed after processing any data transformations (see the arguments transforms or transformFunc). As with all expressions, rowSelection can be defined outside of the function call using the expression function.

transforms

an expression of the form list(name = expression, ...) representing the first round of variable transformations. As with all expressions, transforms (or rowSelection) can be defined outside of the function call using the expression function.

transformObjects

a named list containing objects that can be referenced by transforms, transformsFunc, and rowSelection.

transformFunc

variable transformation function. See rxTransform for details.

transformVars

character vector of input data set variables needed for the transformation function. See rxTransform for details.

transformPackages

character vector defining additional R packages (outside of those specified in rxGetOption("transformPackages")) to be made available and preloaded for use in variable transformation functions, e.g., those explicitly defined in RevoScaleR functions via their transforms and transformFunc arguments or those defined implicitly via their formula or rowSelection arguments. The transformPackages argument may also be NULL, indicating that no packages outside rxGetOption("transformPackages") will be preloaded.

transformEnvir

user-defined environment to serve as a parent to all environments developed internally and used for variable data transformation. If transformEnvir = NULL, a new "hash" environment with parent baseenv() is used instead.

blocksPerRead

number of blocks to read for each chunk of data read from the data source.

histType

character string specifying "Counts" or "Percent".

title

main title for the plot. Alternatively main can be used.

subtitle

subtitle (at the bottom) for the plot. Alternatively sub can be used.

xTitle

title for the X axis. Alternatively xlab can be used.

yTitle

title for the Y axis. Alternatively ylab can be used.

xNumTicks

number of tick marks on X axis (ignored for factor variables).

yNumTicks

number of tick marks on Y axis.

xAxisMinMax

numeric vector of length 2 containing a minimum and maximum value for the X axis. Alternatively xlim can be used.

yAxisMinMax

numeric vector of length 2 containing a minimum and maximum value for the Y axis. Alternatively ylim can be used.

fillColor

fill color for histogram. Use colors to see color names.

lineColor

line color for border of histogram.

lineStyle

line style for border of histogram: "blank", "solid", "dashed", ``"dotted", "dotdash", "longdash", or "twodash".

lineWidth

line width for border of histogram. Alternatively lwd can be used.

plotAreaColor

background color for the plot area.

gridColor

color for grid lines.

gridLineWidth

line width for grid lines.

gridLineStyle

line style for grid lines.

maxNumPanels

integer specifying the maximum number of panels to plot. The number of panels is determined by the product of the number of levels of each conditioning variable. If the number of panels exceeds the maxNumPanels an error is given and the plot is not drawn. If maxNumPanels is NULL, it is ignored.

reportProgress

integer value with options:

  • 0: no progress is reported.
  • 1: the number of processed rows is printed and updated.
  • 2: rows processed and timings are reported.
  • 3: rows processed and all timings are reported.

print

logical. If TRUE, the plot is printed. If FALSE, and the lattice package is loaded, an lattice plot object is returned invisibly and can be printed later.

...

additional arguments to be passed directly to the underlying barchart or xyplot function.

Details

rxHistogram calls rxCube to perform computations and uses the lattice graphics package (barchart or xyplot) to create the plot. The rxHistogram function will attempt bin continuous data in reasonable intervals. For faster computation (using a bin for every integer value), use the F() function around the variable. Descriptive argument names are used to facilitate quick and easy plotting and self-documenting code for new R users.

Value

An object of class "trellis". It is automatically printed within the function.

Author(s)

Microsoft Corporation Microsoft Technical Support

See Also

rxLinePlot, rxCube, histogram.

Examples


 # Examples using airline data
 airlineData <- file.path(rxGetOption("sampleDataDir"), "AirlineDemoSmall.xdf")
 # Use the F() function to quickly compute bins for each integer level
 rxHistogram(~F(CRSDepTime), data = airlineData)
 # Specify the approximate number of breaks
 rxHistogram(~CRSDepTime, numBreaks=11, data = airlineData)

 # Examples using census data subsample
 censusWorkers <- file.path(rxGetOption("sampleDataDir"), "CensusWorkers")
 # Create panels for each of the 3 states
 rxHistogram(~ sex | state, data = censusWorkers)
 # Repeat, printing x axis labels at an angle, and all panels in a row
 rxHistogram(~ sex | state, scales = list(x = list(rot = 30)), 
     data = censusWorkers, layout = c(3,1))
 # Create panels for age for each sex for each state
 rxHistogram(~ age | sex + state, data = censusWorkers)
 # Specify how wage income should be broken into bins
 rxHistogram(~ incwage | state + sex, title="Wage Income Up To 100,000", 
   endVal = 100000, numBreaks=21, data = censusWorkers)

 # Show panels for each state on a separate page
 numCols <- 1
 numRows <- 2
 ## Not run:

par(ask=TRUE) # Set ask to pause between each plot
## End(Not run) 

 rxHistogram(~ age | sex + state, data = censusWorkers, layout=c(numCols, numRows)) 

 # Create a jpeg file for each page, named myplot001.jpeg, etc
 ## Not run:

jpeg(file="myplot
rxHistogram(~ age | sex + state, data = censusWorkers, 
  blocksPerRead=6, layout=c(numCols, numRows)) 
dev.off()
## End(Not run)