dynamictable: Dynamic Table

In maptracker/dynamictable: Create Simple HTML Pages from Tabular R Data Structures

Description

Light-weight, non-paginated HTML table with basic sorting, filtering and automated markup functionality

Usage

dynamictable(data, cols = NA, options = list(), params = list(),
  file = NA, header = "", title = NA, footer = "", sortby = "",
  show.rownames = TRUE, facet.title = TRUE, show.attr = TRUE,
  auto.url = TRUE, auto.title = TRUE, auto.factor = TRUE,
  min.level = NA, factor.colors = "hash", style = character(),
  favicon = NA,
  numeric.style = "text-align: right; font-family: monospace;",
  display.url = TRUE)

Arguments

data	The only required argument, an R object to be displayed, typically a data.frame, matrix or array. Vectors will be shown as a table with a single column.
cols	The columns to display. If NA (Default) then all columns in data will be shown (with some exceptions - see auto.url and auto.title). Alternatively a character vector of column names can be provided, to show only a subset of columns, or to change their order.
options	List of configuration options, keyed by the column names of x, sub-keyed by parameter name. See Options below for more details
params	A fallback to options, useful for providing default values. It is keyed first by parameter name, then column. If a parameter is defined in both options and params, the options value will be used
file	File path for output. If not provided, a temporary path will be used
header	HTML to display at top of document. If it begins with '<' it will be presumed to contain HTML markup and will be used as-is, otherwise it will be escaped
title	Text to define the HTML <title> block (displayed on the browser's window frame). If NA will default to header
footer	Text to add at the end of the document, after the table. Like header, will be escaped unless the first character is '<'
sortby	Column for initial sort of displayed data
show.rownames	When TRUE (default) the first column will be rownames, if set
facet.title	If TRUE (default) then any column titles set with the 'coltitle' option will also be shown as descriptive text above the faceting buttons.
show.attr	When TRUE (default) then some object attributes will be shown at the end of the table. Attributes will be listed only if the value is atomic, and if the key is not 'reserved' (names, dims, etc)
auto.url	If TRUE (default), will look for data/URL column pairs, such that a column 'foo URL' (or 'foo link') will be hidden and instead used as a hyperlink for column 'foo', provided that 'foo' exists
auto.title	Like auto.url, but if TRUE (default) will supress display of 'foo title' and use it for mouse-over title text on column 'foo' instead. Also matches 'foo description'
auto.factor	If TRUE (default), then any is.factor() columns will have faceting widgets set for them. These are buttons for each factor level that toggle row visibility on and off
min.level	Default NA, a minimum factor level count. Can be set here for all factors, or applied to individual columns, see the 'factor' section for more information.
factor.colors	Default 'hash', controls auto-generated colors assigned to factor levels. The value can also be set for each column, see the 'factor' section for more information.
style	Character vector of CSS styles to add to document
favicon	If NA (default) a default favicon will be assigned to the document. If NULL, no favicon will be set. Otherwise should be an appropriate URL or an HTML data block.
numeric.style	Default 'text-align: right; font-family: monospace;'. CSS styling of table columns is awkward, it is easiest to have this as an explicit parameter with explicit CSS code, rather than trying to set a particular class.
display.url	If TRUE (default), browseURL() will be called to display the newly-created output

Details

dynamictable was built with the following design goals:

• Ease of use - A table can be built by passing a single object, with reasonable defaults already set

• Configurable - Default settings can be changed with nested list options

• Single output file - The generated file is entirely self-contained

• Lightweight HTML - Most dynamic operations are CSS-driven, with a minimum amount of simple JavaScript

• Compact HTML - The resultant table is designed to pack a high amount of information into a given space

• No pagination - While this will be seen as a limitation by some users, it is an explicit design choice

• Basic functionality - Sortable columns, per-column filters (factor faceting, numeric and text filters), collapsable text, automatic and custom gradient generation, hyperlinks, mouse-over text

Value

The file path of the generated HTML document

Column Names

Column names have loose matching - an attempt will first be made with an exact, case-sensitive search; If that fails a case-insensitive attempt will be made.

In addition, the special token '*' will match ALL columns

Finally, if row names have been added, that column can be configured with the 'dtRowNames' column name.

Options

The options parameter should be a list, with column names corresponding to the column names of data. You need only include those columns you wish to configure. Each column should itself be a list of specific parameters to set. Most of those parameters will have simple values, but a few can optionally be provided as lists themselves, so for example:

dynamictable(mtcars, options=list(cyl=list(factor=TRUE), hp=list(gradient=list( colors=c("yellow","purple")))))

The call is requesting that "cyl" be treated as a factor, an option that could be configured with a sub-list, but passing TRUE will cause default values to be applied. The use of a sub-list to define the 'gradient' option for column "hp" allows finer-grained configuration.

Recognized Options

• "name" - Provide an alternative column name

• "url" - The name of another column that should serve as a source of URLs for this one.

  • Alternatively, the value can be a sprintf format string, which will be recognized by the presence of "%s", which will accept the cell content as a value

• "title" - The name of another column that should serve as a source of titles (text that appears on mouse hover over the CELL) for this one.

• "coltitle" - Text that will appear when holding the mouse over the column HEADER

• "hide" - If true, then the column will not be shown

• "byFactor" - Normally factor columns have styling applied to themselves. The byFactor option allows a column to be styled by the levels from another column

• "class" - Allows custom classing of cells.

  • If a column name is provided, then the values of that column will be used as class names. The high-level function parameter "style" should include relevant CSS definitions for this to have a visible effect. Class names will be transformed to meet W3C specifications. This will strip out 'illegal' characters, and will prefix 'DT-' to any values that do not start with '-?[_a-zA-Z]'. So a column with a value of '4.3@C' will have a class of 'DT-4.3C'

  • If an R function is provided, that function will be applied to each cell content and the returned value used as a class name

  • Otherwise, if a static value is provided, that value will be applied to all cells in the column.

• "truncate" - An integer value constraining column width. A cell will show at most this number of characters. If the value is exceeded, a clickable ellipses will be shown for the missing text; Clicking on the ellipses will toggle visibility. This option is ignored for numeric columns.

• "spacemap" - A list of characters that should be shown as spaces. Useful for long identifiers that use underscores preventing text wrapping (eg MSigDB).

• "sprintf" - If non-null will be used as a sprintf string to format values in the cells. Original values will still be used for sorting. Can be used on any column, but user is responsible for using relevant formatting tokens.

• "signif" - If an integer between 1-22, will restrict the column to that number of significant digits. Original values will still be used for sorting. Does not affect non-numeric columns, and will be ignored if sprintf is set.

• "fold" - If non-null will merely affix the × character entity (a slightly fancier "x") to the end of the column. Will not alter underlying values

• "percent" - If non-null will merely affix a "%" character to the end of the column. Will not alter underlying values

• "gradient" - Indicates that column cells should have a background color applied according to their value. The values will be broken into bins and assigned a CSS class for each bin.

  • "min" - Defines the smallest bin value. Defaults to min()

  • "max" - Defines the largest bin value. Defaults to max()

  • "bins" - Specifies the number of bins to use

  • "step" - If "bins" was not specified, then step can specify the bin size. If neither are specified, then 15 bins will be used.

  • "binVals" - An explicit list of bin values, will override "min", "max", "bins" and "step". Useful for hand-specifying non-linear (eg logarithmic/exponential) gradient values.

  • "colors" - The colors to use for generating the gradient, default are c("#5555ff", "white", "red"). These will be passed to colorRampPalette()

  • "lowstyle" - a CSS style (not class name) to be used for values that fall below the minimum bin. If not provided, then the lowest color gradient will be used.

  • "highstyle" - as above, but for values that exceed the maximum.

• "factor" - When non-null, will treat the column as a factor even if not formally in R. If the value is not a list, default factor options will be used. If a list, the following keys are recognized as configuration options:

  • "name" - defines the text that will be shown above the facetting buttons. If not defined, the "name" as defined for the column will be used

  • "active" - a character vector listing levels that should be pre-selected when the page first loads If not set then all levels will be off, which is equivalent to all levels being on.

  • "min.level" - An optional minimum level count. Levels with representation below this level will be grouped together in an "<Other>" category. This is useful for handling columns that are mostly controlled vocabullary, but include a few "noisy" levels, eg "Yes (except when it is raining)"

  • "textFilter" - if TRUE, will include a free-text filter box in addition to facetting buttons.

  • "color" - A flag to control how factor levels are colored

    • NULL - will default to the high-level option factor.colors, which is default "hash"

    • NA - no coloring at all

    • "rainbow", "heat.colors", "terrain.colors", "topo.colors", "cm.colors" - default R palette functions

    • "hash" - will use the internal colorizeString() function to generate an RGB color from a hashed string of each factor level (name). This color is "portable" across different data sets, in that the same factor level (name) will always generate the same color. Nuances of hash coloring can be controlled by the "min", "max", "r", "g" and "b" factor sub-options

      • "min" - Sets the minimum intentisty value for hash colors (default 128 in colorizeString)

      • "max" - Sets the maximum intensity for hash colors (default 240) in colorizeString

      • "r" - Sets a fixed intensity for the hashed red channel

      • "g" - Sets a fixed intensity for the hashed green channel

      • "b" - Sets a fixed intensity for the hashed blue channel

Author(s)

Charles A Tilford, [e-mail]

See Also

Library "DT", which implements jQuery DataTables. These are paginated and are likley more appropriate for visualizing larger (10,000+ rows) tables: <URL: http://rstudio.github.io/DT>

Examples

## Quick table generation

dynamictable(mtcars)

## Using the "*" wildcard to apply a setting (here a gradient) to all columns

dynamictable(state.x77, options = list("*"=list(gradient=TRUE)))

## A highly customized view of mtcars to illustrate most options:

demo("hyperCustomizedTable", package="dynamictable", ask=FALSE)

## Stress-test with 1000 rows. The performance is not stellar - tens
## of thoushands of rows are passable in Chrome, but awkward in Firefox.
## For larger datasets a paginated browser (eg DT) is likely more
## appropriate

demo("largeDataSets", package="dynamictable", ask=FALSE)

## Some simple factorized data sets:

dynamictable(texteditorplatforms)
dynamictable(typesystemcomparison)

## Factor-rich table, with min.level set to consolidate uncommon levels:

dynamictable(vampiretraits, min.level=2)

maptracker/dynamictable documentation built on May 21, 2019, 11:27 a.m.