data.table Printing Options

print.data.table extends the functionalities of print.data.frame.

Key enhancements include automatic output compression of many observations and concise column-wise class summary.

format_col and format_list_item generics provide flexibility for end-users to define custom printing methods for generic classes.

Note also the option datatable.prettyprint.char; character columns entries exceeding this limit will be truncated, with ... indicating the truncation. Note that the truncation is done with strtrim; be cognizant of potential limitations when dealing with non-printable characters like newlines or tabs.

Usage

# S3 method for class 'data.table'
print(x,
    topn=getOption("datatable.print.topn"),             # default: 5
    nrows=getOption("datatable.print.nrows"),           # default: 100
    class=getOption("datatable.print.class"),           # default: TRUE
    row.names=getOption("datatable.print.rownames"),    # default: TRUE
    col.names=getOption("datatable.print.colnames"),    # default: "auto"
    print.keys=getOption("datatable.print.keys"),       # default: TRUE
    trunc.cols=getOption("datatable.print.trunc.cols"), # default: FALSE
    show.indices=getOption("datatable.show.indices"),   # default: FALSE
    quote=FALSE,
    na.print=NULL,
    timezone=FALSE, ...)

  format_col(x, ...)
  # Default S3 method
format_col(x, ...)
  # S3 method for class 'POSIXct'
format_col(x, ..., timezone=FALSE)
  # S3 method for class 'expression'
format_col(x, ...)

  format_list_item(x, ...)
  # Default S3 method
format_list_item(x, ...)

Arguments

x: A data.table.
topn: The number of rows to be printed from the beginning and end of tables with more than nrows rows.
nrows: The number of rows which will be printed before truncation is enforced.
class: If TRUE, the resulting output will include above each column its storage class (or a self-evident abbreviation thereof). When combined with col.names="auto" and tables >20 rows, classes will also appear at the bottom.
row.names: If TRUE, row indices will be printed alongside x.
col.names: One of three flavours for controlling the display of column names in output. "auto" includes column names above the data, as well as below the table if nrow(x) > 20 (when class=TRUE, column classes will also appear at the bottom). "top" excludes this lower register when applicable, and "none" suppresses column names altogether (as well as column classes if class = TRUE.
print.keys: If TRUE, any key and/or index currently assigned to x will be printed prior to the preview of the data.
trunc.cols: If TRUE, only the columns that can be printed in the console without wrapping the columns to new lines will be printed (similar to tibbles).
show.indices: If TRUE, indices will be printed as columns alongside x.
quote: If TRUE, all output will appear in quotes, as in print.default.
timezone: If TRUE, time columns of class POSIXct or POSIXlt will be printed with their timezones (if attribute is available).
na.print: The string to be printed in place of NA values, as in print.default.
...: Other arguments ultimately passed to format.

Value

print.data.table returns x invisibly.

format_col returns a length(x)-size character vector.

format_list_item returns a length-1 character scalar.

Details

By default, with an eye to the typically large number of observations in a data.table, only the beginning and end of the object are displayed (specifically, head(x, topn) and tail(x, topn) are displayed unless nrow(x) < nrows, in which case all rows will print).

format_col is applied at a column level; for example, format_col.POSIXct is used to tag the time zones of POSIXct columns. format_list_item is applied to the elements (rows) of list columns; see Examples. The default format_col method uses getS3method to test if a format method exists for the column, and if so uses it. Otherwise, the default format_list_item method uses the S3 format method (if one exists) for each item of a list column.

Examples

  #output compression
  DT <- data.table(a = 1:1000)
  print(DT, nrows = 100, topn = 4)
#>           a
#>       <int>
#>    1:     1
#>    2:     2
#>    3:     3
#>    4:     4
#>   ---      
#>  997:   997
#>  998:   998
#>  999:   999
#> 1000:  1000

  #`quote` can be used to identify whitespace
  DT <- data.table(blanks = c(" 12", " 34"),
                   noblanks = c("12", "34"))
  print(DT, quote = TRUE)
#>    "blanks" "noblanks"
#>    "<char>"   "<char>"
#> 1:    " 12"       "12"
#> 2:    " 34"       "34"

  #`class` provides handy column type summaries at a glance
  DT <- data.table(a = vector("integer", 3),
                   b = vector("complex", 3),
                   c = as.IDate(paste0("2016-02-0", 1:3)))
  print(DT, class = TRUE)
#>        a      b          c
#>    <int> <cplx>     <IDat>
#> 1:     0   0+0i 2016-02-01
#> 2:     0   0+0i 2016-02-02
#> 3:     0   0+0i 2016-02-03

  #`row.names` can be eliminated to save space
  DT <- data.table(a = 1:3)
  print(DT, row.names = FALSE)
#>      a
#>  <int>
#>      1
#>      2
#>      3

  #`print.keys` can alert which columns are currently keys
  DT <- data.table(a=1:3, b=4:6, c=7:9, key=c("b", "a"))
  setindexv(DT, c("a", "b"))
  setindexv(DT, "a")
  print(DT, print.keys=TRUE)
#> Key: <b, a>
#> Indices: <a__b>, <a>
#>        a     b     c
#>    <int> <int> <int>
#> 1:     1     4     7
#> 2:     2     5     8
#> 3:     3     6     9

  # `trunc.cols` will make it so only columns that fit in console will be printed
  #    with a message that states the variables not shown
  old_width = options("width" = 40)
  DT <- data.table(thing_11 = vector("integer", 3),
                   thing_21 = vector("complex", 3),
                   thing_31 = as.IDate(paste0("2016-02-0", 1:3)),
                   thing_41 = "aasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf",
                   thing_51 = vector("integer", 3),
                   thing_61 = vector("complex", 3))
  print(DT, trunc.cols=TRUE)
#>    thing_11 thing_21   thing_31
#>       <int>   <cplx>     <IDat>
#> 1:        0     0+0i 2016-02-01
#> 2:        0     0+0i 2016-02-02
#> 3:        0     0+0i 2016-02-03
#> 3 variables not shown: [thing_41 <char>, thing_51 <int>, thing_61 <cplx>]
  options(old_width)

  # `char.trunc` will truncate the strings,
  # if their lengths exceed the given limit: `datatable.prettyprint.char`
  # For example:

  old = options(datatable.prettyprint.char=5L)
  DT = data.table(x=1:2, y=c("abcdefghij", "klmnopqrstuv"))
  DT
#>        x        y
#>    <int>   <char>
#> 1:     1 abcde...
#> 2:     2 klmno...
  options(old)

  # Formatting customization
  format_col.complex = function(x, ...) sprintf('(%.1f, %.1fi)', Re(x), Im(x))
  x = data.table(z = c(1 + 3i, 2 - 1i, pi + 2.718i))
  print(x)
#>                  z
#>             <cplx>
#> 1: 1.000000+3.000i
#> 2: 2.000000-1.000i
#> 3: 3.141593+2.718i

  old = options(datatable.show.indices=TRUE)
  NN = 200
  set.seed(2024)
  DT = data.table(
    grp1 = sample(100, NN, TRUE),
    grp2 = sample(90, NN, TRUE),
    grp3 = sample(80, NN, TRUE)
  )
  setkey(DT, grp1, grp2)
  setindex(DT, grp1, grp3)
  print(DT)
#> Key: <grp1, grp2>
#> Index: <grp1__grp3>
#>       grp1  grp2  grp3 index:grp1__grp3
#>      <int> <int> <int>            <int>
#>   1:     1     9    11                2
#>   2:     1    10     5                1
#>   3:     1    60    47                3
#>   4:     2    44     6                4
#>   5:     2    80    36                5
#>  ---                                   
#> 196:    97    59    65              196
#> 197:    98    32    59              198
#> 198:    98    52    36              197
#> 199:    99     2    19              199
#> 200:    99    72    80              200
  options(old)

  iris = as.data.table(iris)
  iris_agg = iris[ , .(reg = list(lm(Sepal.Length ~ Petal.Length))), by = Species]
  format_list_item.lm = function(x, ...) sprintf('<lm:%s>', format(x$call$formula))
  print(iris_agg)
#>       Species      reg
#>        <fctr>   <list>
#> 1:     setosa <lm[12]>
#> 2: versicolor <lm[12]>
#> 3:  virginica <lm[12]>

Usage

Arguments

Value

Details

See also

Examples