Create an interactive histogram

Source: R/l_hist.R

l_hist is a generic function for creating interactive histogram displays that can be linked with loon's other displays.

l_hist(x, ...)

# S3 method for default
l_hist(
  x,
  yshows = c("frequency", "density"),
  by = NULL,
  on,
  layout = c("grid", "wrap", "separate"),
  connectedScales = c("cross", "row", "column", "both", "x", "y", "none"),
  origin = NULL,
  binwidth = NULL,
  showStackedColors = TRUE,
  showBinHandle = FALSE,
  color = l_getOption("color"),
  active = TRUE,
  selected = FALSE,
  xlabel = NULL,
  showLabels = TRUE,
  showScales = FALSE,
  showGuides = TRUE,
  parent = NULL,
  ...
)

# S3 method for factor
l_hist(
  x,
  showFactors = length(unique(x)) < 25L,
  factorLabelAngle,
  factorLabelSize = 12,
  factorLabelColor = l_getOption("foreground"),
  factorLabelY = 0,
  ...
)

# S3 method for character
l_hist(
  x,
  showFactors = length(unique(x)) < 25L,
  factorLabelAngle,
  factorLabelSize = 12,
  factorLabelColor = l_getOption("foreground"),
  factorLabelY = 0,
  ...
)

# S3 method for data.frame
l_hist(x, ...)

# S3 method for matrix
l_hist(x, ...)

# S3 method for list
l_hist(x, ...)

# S3 method for table
l_hist(x, ...)

# S3 method for array
l_hist(x, ...)

Arguments

x

vector with numerical data to perform the binning on x,
...

named arguments to modify the histogram plot states or layouts, see details.
yshows

one of "frequency" (default) or "density"
by

loon plot can be separated by some variables into multiple panels. This argument can take a formula, n dimensional state names (see l_nDimStateNames) an n-dimensional vector and data.frame or a list of same lengths n as input.
on

if the x or by is a formula, an optional data frame containing the variables in the x or by. If the variables are not found in data, they are taken from environment, typically the environment from which the function is called.
layout

layout facets as 'grid', 'wrap' or 'separate'
connectedScales

Determines how the scales of the facets are to be connected depending on which layout is used. For each value of layout, the scales are connected as follows:

  • layout = "wrap": Across all facets, when connectedScales is

    • "x", then only the "x" scales are connected

    • "y", then only the "y" scales are connected

    • "both", both "x" and "y" scales are connected

    • "none", neither "x" nor "y" scales are connected. For any other value, only the "y" scale is connected.

  • layout = "grid": Across all facets, when connectedScales is

    • "cross", then only the scales in the same row and the same column are connected

    • "row", then both "x" and "y" scales of facets in the same row are connected

    • "column", then both "x" and "y" scales of facets in the same column are connected

    • "x", then all of the "x" scales are connected (regardless of column)

    • "y", then all of the "y" scales are connected (regardless of row)

    • "both", both "x" and "y" scales are connected in all facets

    • "none", neither "x" nor "y" scales are connected in any facets.
origin

numeric scalar to define the binning origin
binwidth

a numeric scalar to specify the binwidth If NULL binwidth is set using David Scott's rule when x is numeric (namely 3.49 * sd(x)/(n ^(1/3)) if sd(x) > 0 and 1 if sd(x) == 0) and using the minumum numerical difference between factor levels when x is a factor or a character vector (coerced to factor).
showStackedColors

if TRUE (default) then bars will be coloured according to colours of the points; if FALSE, then the bars will be a uniform colour except for highlighted points.
showBinHandle

If TRUE, then an interactive "bin handle" appears on the plot whose movement resets the origin and the binwidth. Default is FALSE
color

colour fills of bins; colours are repeated until matching the number x. Default is found using l_getOption("color").
active

a logical determining whether points appear or not (default is TRUE for all points). If a logical vector is given of length equal to the number of points, then it identifies which points appear (TRUE) and which do not (FALSE).
selected

a logical determining whether points appear selected at first (default is FALSE for all points). If a logical vector is given of length equal to the number of points, then it identifies which points are (TRUE) and which are not (FALSE).
xlabel

label to be used on the horizontal axis. If NULL, an attempt at a meaningful label inferred from x will be made.
showLabels

logical to determine whether axes label (and title) should be presented.
showScales

logical to determine whether numerical scales should be presented on both axes.
showGuides

logical to determine whether to present background guidelines to help determine locations.
parent

a valid Tk parent widget path. When the parent widget is specified (i.e. not NULL) then the plot widget needs to be placed using some geometry manager like tkpack or tkplace in order to be displayed. See the examples below.
showFactors

whether to show the factor labels (unique strings in x) as a layer on the plot. If FALSE, the factor labels are hidden and can be turned on from the "layers" tab on the inspector.
factorLabelAngle

is the angle of rotation (in degrees) for the factor labels. If not specified, an angle of 0 is chosen if there are fewer than 10 labels; labels are rotated 90 degrees if there are 10 or more. This can also be a numeric vector of length equal to the number of factor labels.
factorLabelSize

is the font size for the factor labels (default 12).
factorLabelColor

is the colour to be used for the factor labels. (default is l_getOption("foreground")). Can also be a vector equal to that of the number of factor labels.
factorLabelY

either a single number, or a numeric vector of length equal to the number of factor labels, determining the y coordinate(s) for the factor labels.

Value

if the argument by is not set, a loon widget will be returned; else an l_facet object (a list) will be returned and each element is a loon widget displaying a subset of interest.

Details

For more information run: l_help("learn_R_display_hist")

  • Note that when changing the yshows state from 'frequency' to 'density' you might have to use l_scaleto_world to show the complete histogram in the plotting region.

  • Some arguments to modify layouts can be passed through, e.g. "separate", "byrow", etc. Check l_facet to see how these arguments work.

See also

Turn interactive loon plot static loonGrob, grid.loon, plot.loon.

Other loon interactive states: l_info_states(), l_plot(), l_serialaxes(), l_state_names(), names.loon()

Examples

if(interactive()){

h <- l_hist(iris$Sepal.Length)

names(h)
h["xlabel"] <- "Sepal length"
h["showOutlines"] <- FALSE

h["yshows"]
h["yshows"] <- "density"
l_scaleto_plot(h)

h["showStackedColors"] <- TRUE
h['color'] <- iris$Species
h["showStackedColors"] <- FALSE
h["showOutlines"] <- TRUE
h["showGuides"] <- FALSE

# link another plot with the previous plot
h['linkingGroup'] <- "iris_data"
h2 <- with(iris, l_hist(Petal.Width,
                        linkingGroup="iris_data",
                        showStackedColors = TRUE))


# Get an R (grid) graphics plot of the current loon plot
plot(h)
# or with more control about grid parameters
grid.loon(h)
# or to save the grid data structure (grob) for later use
hg <- loonGrob(h)

}