groupedTickLabels: Label Axes With Hierarchically Organized Groups
In mwrowe/microRutils: Mike Rowe's Miscellaneous R Utility Functions

Description Usage Arguments Details Value Author(s) See Also

groupedTickLabels() labels and divides groups along the x- or y-axis.

groupedTickLabels(
  groups,
  side,
  lwd = 1,
  col = "black",
  cex = 0.7,
  las = 0,
  at,
  gaps,
  plot.labels = TRUE,
  group.tix = TRUE,
  meta.label = TRUE
)

`groups`	A data.frame() of annotations that define groupings based on their values, orderd from most general to most specific. The ordering of the rows must correspond to the ordering of the items plotted along the axis which will be labeled.
`side`	Which axis to label– see `axis`.
`lwd`	Vector of line widths for grid lines dividing groups, with each element corresponding a column in groups. If NA or omitted, no line will be drawn for a given grouping.
`col`	Vector of colors for the lines between groupings.
`cex`	Numeric vector specifying sizing of labels for each annotation in groups. The last element will be reused for subsequent annotations. Labels will not be printed if cex is zero or NA for a given annotation.
`las`	A vector of integers in the range 0 to 2 indicating how the labels for each annotation in groups should be oriented. If fewer elements are supplied than annotations (ncol(groups)), the remaining labels will be placed perpendicular to the axis.
`at`	Numeric vector specifying centers along the axes, to be used when spacing not uniform or separated values other than one. By default, at will be set at 1:nrow(groups).
`gaps`	Numeric vector, specifying gap to leave, specified as margin lines, between successive group labels; default is rep(0.5,ncol(groups)). The last value specifies the gap between the axis line and the group closest to the axis (i.e., the last group).
`plot.labels`	Logical; if FALSE, do not add group labels to the plot, but return placement info and print suggested margin.
`group.tix`	Logical; if TRUE, draw lines connecting tick marks within each group, for each grouping variable.
`meta.label`	Logical; should variable labels be plotted at the left edge or top?

This function is useful when the data along one axis is ordered by hierarchically related groups. The most general groups are labeled farthest from the axis, and by default have larger labels and heavier lines between them than more specific subgroups.

The user must provide sufficient margin space along the axis for the labels via the par("mar") value for the side to be labelled. A suggested value may be generated by calling the function with plot.labels=FALSE.

Spacing required by the labels is determined primarily by the las and cex arguments, as well as gaps. In general, you may have to play with the arguments a bit to make the labels look readable.

Returns a list with elements named according to the columns of groups, with elements:

labels Character vector with labels for the unique groupings at this level of the hierarchy (column of groups).
N Numeric vector, same length as labels, with the number of items (rows of groups) within this group.
mids Numeric vector, same length as labels, with the midpoints of each group, used to center labels along the axis.
breaks Numeric vector, length(labels)+1, with midpoints between successive groups (including before first and after last).
outerLine, innerLine: numeric values specifying position of labels and grouping lines away from the axis
group Numeric vector, length equal to n.rows(groups), with the group number of each row of groups.
par Vector of graphics parameters applied to this level of the hierarchy, with names "line", "cex", "las", "adj", "padj".