Coloured Formatting for Columns

Provides a 'pillar' generic designed for formatting columns of data using the full range of colours provided by modern terminals.


Travis-CI Build Status Coverage status CRAN status

pillar provides tools for styling columns of data, artfully using colour and unicode characters to guide the eye.

Installation

devtools::install_github("r-lib/pillar")

Usage

pillar is not designed for end-users but will eventually be incorporated in packages like tibble.

library(pillar)
 
x <- 123456789 * (10 ^ c(1, -3, -5, NA, -8, -10))
pillar(x)
#>           <dbl>
#> 1234567890     
#>     123457     
#>       1235     
#>         NA     
#>          1.23  
#>          0.0123

If you render this in a console that supports colour, you'll see something that looks like this:

Extending

The primary user of this package is tibble, which in the current development version already lets pillar do all the formatting work. Packages that implement a data type to be used in a tibble column can add color with only a few changes:

  1. Implement the pillar_shaft() method for your data type.
  2. Add pillar to Suggests and implement dynamic method registration
    • If you don't mind the dependency, you can also add it to Imports, and import the methods you override with a regular NAMESPACE import.

tidyverse/hms#43 shows the changes that were necessary to add colored output for the hms package:

  • pillar.R for the actual implementation (old name colformat.R)
  • DESCRIPTION for the dependency
  • zzz.R for the dynamic method registration

Some more detail is given below.

Implementing pillar_shaft.your_class_name()

This method accepts a vector of arbitrary length and is expected to return an S3 object with the following properties:

  • It has an attribute "width"
  • It can have an attribute "min_width", if missing, "width" is used
  • It must implement a method format(x, width, ...) that can be called with any value between min_width and width
    • This method must return an object that inherits from character and has attributes "align" (with supported values "left", "right", and "center") and "width"

The function new_pillar_shaft() returns such an object, and also correctly formats NA values. In many cases, the implementation of pillar_shaft.your_class_name() will format the data as a character vector (using color for emphasis) and simply call new_pillar_shaft(). See pillar_shaft.numeric() for a code that allows changing the display depending on the available width.

Useful helpers

  • style_neg() to format negative values
  • style_num() to format numbers
  • style_subtle() to de-emphasize

Dynamic method registration

If you avoid the strong dependency on pillar, you need a helper, register_s3_method(), which you can borrow e.g. from hms. In .onLoad(), call this helper as follows:

register_s3_method("pillar", "pillar_shaft", "your_class_name")

Replace "your_class_name" with the name of the S3 class of your data type.

Inspirations

  • TextPlots for use of Braille characters

  • spark for use of block characters.

The earliest use of unicode characters to generate sparklines appears to be from 2009.

Exercising these ideas to their fullest requires a font with good support for block drawing characters. PragamataPro is one such font.

News

pillar 1.1.0 (2018-01-14)

  • NA values are now shown in plain red, without changing the background color (#70).
  • New options to control the output, with defaults that match the current behavior unless stated otherwise:
    • pillar.sigfig to control the number of significant digits, for highlighting and truncation (#72),
    • pillar.subtle to specify if insignificant digits should be printed in gray (#72),
    • pillar.neg to specify if negative digits should be printed in red,
    • pillar.bold to specify if column headers should be printed in bold (default: FALSE, #76),
    • pillar.min_title_chars to specify the minimum number of characters to display for each column name (default: 15 characters, #75).
  • Shortened abbreviations for types: complex: cplx -> cpl, function: fun -> fn, factor: fctr -> fct (#71).
  • Date columns now show sub-seconds if the digits.secs option is set (#74).
  • Very wide tibbles now print faster (#85).

pillar 1.0.1 (2017-11-27)

  • Work around failing CRAN tests on Windows.

pillar 1.0.0 (2017-11-16)

Initial release.

User functions

pillar(x, title = NULL, width = NULL, ...)
colonnade(x, has_row_id = TRUE, width = NULL, ...)
squeeze(x, width = NULL, ...)

Functions for implementers of data types

new_pillar_shaft_simple(formatted, ..., width = NULL, align = "left", min_width = NULL, na_indent = 0L)
new_pillar_shaft(x, ..., width, min_width = width, subclass)
new_ornament(x, width = NULL, align = NULL)
get_extent(x)
get_max_extent(x)

Utilities

dim_desc(x)
style_na(x)
style_neg(x)
style_num(x, negative, significant = rep_along(x, TRUE))
style_subtle(x)

Testing helper

expect_known_display(object, file, ..., width = 80L, crayon = TRUE)

Own S3 methods

pillar_shaft(x, ...) # AsIs, Date, POSIXt, character, default, list, logical, numeric
type_sum(x) # AsIs, Date, POSIXct, data.frame, default, difftime, factor, ordered
is_vector_s3(x) # Date, POSIXct, data.frame, default, difftime, factor, ordered
obj_sum(x) # AsIs, POSIXlt, default, list
extra_cols(x, ...) # squeezed_colonnade

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("pillar")

1.3.0 by Kirill Müller, 6 days ago


https://github.com/r-lib/pillar


Report a bug at https://github.com/r-lib/pillar/issues


Browse source code at https://github.com/cran/pillar


Authors: Kirill Müller [aut, cre], Hadley Wickham [aut], RStudio [cph]


Documentation:   PDF Manual  


GPL-3 license


Imports cli, crayon, fansi, methods, rlang, utf8

Suggests knitr, lubridate, testthat, withr


Imported by bench, sjmisc, tibble, tsibble, unpivotr.

Suggested by blob, enc, errors, fs, hms, rlang, sf, units.


See at CRAN