pillar (version 1.0.1)

colonnade: Format multiple vectors in a tabular display

Description

The vectors are formatted to fit horizontally into a user-supplied number of characters per row.

The squeeze() function is called by format() and print() and usually doesn't need to be called manually. It returns an object suitable for printing and formatting at a fixed width with additional information about omitted columns.

Usage

colonnade(x, has_row_id = TRUE, width = NULL, ...)

squeeze(x, width = NULL, ...)

Arguments

x

A list of vectors to format

has_row_id

Include a column indicating row IDs? Pass "*" to mark the row ID column with a star.

width

Default width of the entire output, optional

...

Ignored

Details

In a first pass, for each pillar it is decided in which tier it is shown, if at all, and how much horizontal space it may use (either its minimum or its maximum width). More than one tier may be created if width > getOption("width"), in this case each tier is at most getOption("width") characters wide. Remaining space is then distributed proportionally to pillars that do not use their desired width.

For fitting pillars in one or more tiers, it is first attempted to fit all of them in the first tier. If this succeeds (or if no more tiers are available), this fit is accepted. Otherwise, an attempt is made to fit all remaining pillars in the remaining tiers (with a recursive call). If there still are pillars that don't fit, the minimum-width fit is accepted.

In case all remaining pillars fit all remaining tiers, a heuristic selects the optimal number of pillars in the first tier. The tier is grown starting with all pillars that are fitting with their desired width (at least one pillar will be used), and attempts are made to fit the remaining pillars in the remaining tiers (with a recursive call for each attempt). The first successful fit (or otherwise the initial minimum-width fit) is accepted.

For computing the pillar widths in a single tier, two cases are distinguished:

  1. When taking the minimum width for each pillar (plus one inter-pillar space), at least one pillar does not fit. In this case, the minimum width is assigned to all pillars that do fit, the non-fitting pillars are stripped.

  2. All pillars fit with their minimum width. In this case, starting at the leftmost pillar, the maximum width is allocated to the pillars until all available space is used.

The remaining space is distributed from left to right. Each column gains space proportional to the fraction of missing and remaining space, rounded down. Any space remaining after rounding is distributed from left to right, one space per column.

Examples

Run this code
# NOT RUN {
colonnade(list(a = 1:3, b = letters[1:3]))

long_string <- list(paste(letters, collapse = " "))
colonnade(long_string, width = 20)
colonnade(long_string, has_row_id = FALSE, width = 20)

# The width can also be overridden when calling format() or print():
print(colonnade(long_string), width = 20)

# If width is larger than getOption("width"), multiple tiers are created:
colonnade(rep(long_string, 4), width = Inf)
squeeze(colonnade(long_string), width = 20)
# }

Run the code above in your browser using DataCamp Workspace