Absolutize a Filepath

Description

Absolutizes a filepath. Somewhat the opposite of relativizePath.

Usage

absolutizePath(x, dir = getwd(), winslash = "/", ...)

Arguments

Details

x and dir are first normalized, then x is expressed relative to dir. If x and dir are on different drives (i.e. C:/ D:/) x is returned as an absolute path.

Coerce to Kable

Description

Coerces to kable output class. Generic, with method as_kable.tablet.

Usage

as_kable(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
as_kable(tablet(tablette(groupwise(x))))

Coerce Tablet to Kable

Description

Renders a tablet. Calls kbl and implements special features like grouped columns.

Usage

## S3 method for class 'tablet'
as_kable(
  x,
  ...,
  booktabs = TRUE,
  escape = FALSE,
  escape_latex = tablet::escape_latex,
  escape_html = function(x, ...) x,
  variable = " ",
  col.names = NA,
  linebreak = TRUE,
  align = "c",
  double_escape = FALSE,
  linebreaker = "\n",
  pack_rows = list(escape = escape),
  secondary = FALSE
)

Arguments

Details

See also tablet.data.frame. Column _tablet_name must inherit 'character' and by default (in a latex render context) its values will eventually be processed by escape_latex. Thus, if _tablet_name is of class 'latex' it will be handled by method escape_latex.latex (which tries not to re-escape metacharacters).

Value

like kbl

Examples

library(boot)
library(dplyr)
library(magrittr)
library(haven)
library(yamlet)
library(spork)
melanoma %>%
  select(-time, -year) %>%
  mutate(sex = factor(sex), ulcer = factor(ulcer)) %>%
  group_by(status) %>%
  tablet %>%
  as_kable

x <- system.file(package = 'tablet', 'shiny-examples/mesa/data/adsl.sas7bdat')
x %<>% read_sas %>% data.frame
decorations(x) 

# calculate BMI by assuming all males are 1.75 m, all females 1.63 cm
x %<>% mutate(height = ifelse(sex == 'F', 1.63, 1.75))
x %<>% mutate(bmi = signif(digits = 3, weight / (height^2)))
x %<>% filter(saffl == 'Y')
x %<>% select(trt01a, age, sex, weight, bmi)
x %<>% redecorate('
trt01a: [ Treatment, [ Placebo, TRT 10 mg, TRT 20 mg ]]
age:    [ Age, year ]
sex:    [ Sex, [ Female: F, Male: M ]]
weight: [ Body Weight, kg ]
bmi:    [ Index_body mass, kg/m^2 ]
')
x %<>% resolve
x %<>% group_by(trt01a)

x %>% tablet %>% as_kable

# supply default and unit-conditional latex titles
x %<>% modify(title = concatenate(as_latex(as_spork(c(.data$label)))))
x %<>% modify(
age, weight, bmi,
  title = concatenate(
    sep = '',  # default ok in pdf
    as_latex(
      as_spork(
        c(.data$label, ' (', .data$units, ')')
      )
    )
  )
)
x %>% tablet %>% as_kable

Coerce to tablet

Description

Coerces to tablet. Generic, with method as_tablet.data.frame.

Usage

as_tablet(x, ...)

Arguments

Value

tablet

See Also

Other tablet: as_tablet.data.frame(), header_rows(), header_rows.tablet(), tablet.tablette(), tablette.tablet()

Coerce data.frame to tablet

Description

Coerces data.frame to tablet. Checks format and assigns the class. See tablet.data.frame.

Usage

## S3 method for class 'data.frame'
as_tablet(x, ...)

Arguments

Value

tablet

See Also

Other tablet: as_tablet(), header_rows(), header_rows.tablet(), tablet.tablette(), tablette.tablet()

Coerce to Xtable

Description

Coerces to xtable output class. Generic, with method as_xtable.tablet.

Usage

as_xtable(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
as_xtable(tablet(tablette(groupwise(x))))

Coerce Tablet to Xtable

Description

Renders a tablet as xtable. Calls xtable and implements default aesthetics.

Usage

## S3 method for class 'tablet'
as_xtable(
  x,
  caption = NULL,
  label = NULL,
  align = NULL,
  digits = NULL,
  display = NULL,
  auto = FALSE,
  variable = " ",
  format_name = function(x, ...) paste0("\\!\\!\\textbf{", x, "}"),
  format_stat = function(x, ...) x,
  format_value = function(x, ...) x,
  ...
)

Arguments

Value

like xtableList

Examples

library(boot)
library(dplyr)
library(magrittr)
library(xtable)
melanoma %>%
  select(-time, -year) %>%
  mutate(sex = factor(sex), ulcer = factor(ulcer)) %>%
  group_by(status) %>%
  tablet %>%
  as_xtable

Identify Categories

Description

Identifies categories. Generic, with method categoricals.data.frame.

Usage

categoricals(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
categoricals(x)

Identify Categoricals for Data Frame

Description

Identifies categorical columns: literally, factors. Stacks factor levels and supplies value = 1.

Usage

## S3 method for class 'data.frame'
categoricals(x, ..., na.rm_fac = FALSE, exclude_fac = NULL, all_levels = FALSE)

Arguments

Value

same class as x

Examples

example(classifiers)
categoricals(x)
levels(categoricals(x)$`_tablet_level`)

Identify Classifiers

Description

Identifies classifiers. Generic, with method classifiers.data.frame.

Usage

classifiers(x, ...)

Arguments

Value

see methods

Examples

library(dplyr)
x <- data.frame(grp = 1:2, a = factor(1:2), b = 1:2, c = factor(1:2, levels = 2:1))
x <- group_by(x, grp)
classifiers(x)

Identify Classifiers for Data Frame

Description

Identifies classifiers: literally, groups. Supplies tablet_n and tablet_N: groupwise and ungrouped counts.

Usage

## S3 method for class 'data.frame'
classifiers(x, ...)

Arguments

Value

data.frame, grouped if x was (see group_by)

Aggregate Values

Description

Aggregated values. Generic, with method devalued.observations.

Usage

devalued(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
devalued(observations(x))

Aggregate Values for Observations Aggregates values for observations. Accepts a list of formulas with result name on left and aggregating expression on the right. Behavior is undefined if any expression does not aggregate! (I.e., length != 1). Expressions are evaluated in an environment where values are available as 'x', grouped count is available as 'n' and ungouped count is available as 'N'.

Description

Aggregate Values for Observations Aggregates values for observations. Accepts a list of formulas with result name on left and aggregating expression on the right. Behavior is undefined if any expression does not aggregate! (I.e., length != 1). Expressions are evaluated in an environment where values are available as 'x', grouped count is available as 'n' and ungouped count is available as 'N'.

Usage

## S3 method for class 'observations'
devalued(
  x,
  ...,
  fun = list(sum ~ sum(x, na.rm = TRUE), pct ~ signif(digits = 3, sum/n * 100), ave ~
    signif(digits = 3, mean(x, na.rm = TRUE)), std ~ signif(digits = 3, sd(x, na.rm =
    TRUE)), med ~ signif(digits = 3, median(x, na.rm = TRUE)), min ~ signif(digits = 3,
    min(x, na.rm = TRUE)), max ~ signif(digits = 3, max(x, na.rm = TRUE))),
  silent = TRUE
)

Arguments

Value

class 'devalued', presumably one record per group:

Escape Special Characters for Latex

Description

Escapes special characters in Latex context. Generic, with method escape_latex.default.

Usage

escape_latex(x, ...)

Arguments

Value

see methods

See Also

Other escape: escape_latex.default(), escape_latex.latex()

Examples

example(escape_latex.default)

Escape Special Characters for Latex by Default

Description

Escapes text characters that have special meaning in latex. Adapted with gratitude from KableExtra internals. I.e. inactivates material that otherwise looks like latex.

Usage

## Default S3 method:
escape_latex(x, secondary = TRUE, ...)

Arguments

Details

This function is used in as_kable.tablet in preparation for a call to kbl. At kableExtra 1.3.4, sim_double_escape() only doubles primary (leading) backslashes; the secondary argument by default pre-doubles later backslashes to prevent certain display errors. Behavior may change if kableExtra changes.

Value

latex

See Also

Other escape: escape_latex(), escape_latex.latex()

Examples

escape_latex('([#$%&_{}])')

Escape Latex for Class 'latex'

Description

Returns argument typically unmodified. Prevents accidental double-escaping of the same text.

Usage

## S3 method for class 'latex'
escape_latex(x, secondary = TRUE, primary = FALSE, ...)

Arguments

Details

This function is used in as_kable.tablet in preparation for a call to kbl. At kableExtra 1.3.4, sim_double_escape() only doubles primary (leading) backslashes; the secondary argument by default pre-doubles later backslashes to prevent certain display errors. Behavior may change if kableExtra changes.

Value

latex

See Also

Other escape: escape_latex(), escape_latex.default()

Examples

identical(
escape_latex('([#$%&_{}])'),
escape_latex(escape_latex('([#$%&_{}])'))
)

Calculate With Groups

Description

Calculates with groups. Generic, with method groupfull.data.frame. It is meaningless to use this toolchain function on classes 'observations', 'devalued', or 'widgets'.

Usage

groupfull(x, ...)

Arguments

Value

see methods

Calculate Widgets With Groups

Description

Calculates widgets with groups. Executes: data.frame -> observations -> devalued -> widgets.

Usage

## S3 method for class 'data.frame'
groupfull(x, ...)

Arguments

Value

class 'groupfull', with output like widgets.devalued

Calculate Without Groups

Description

Calculates without groups. Generic, with method groupless.data.frame. It is meaningless to use this toolchain function on classes 'observations', 'devalued', or 'widgets'.

Usage

groupless(x, ...)

Arguments

Value

see methods

Calculate Widgets Without Groups

Description

Calculates widgets without groups. Removes grouping variables and groups, then executes: data.frame -> observations -> devalued -> widgets.

Usage

## S3 method for class 'data.frame'
groupless(x, ...)

Arguments

Value

class 'groupless', with output like widgets.devalued

Calculate With and Without Groups

Description

Calculates with and without groups. Generic, with method groupwise.data.frame. It is meaningless to use this toolchain function on classes 'observations', 'devalued', 'widgets', 'groupless', or 'groupfull'.

Usage

groupwise(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
groupwise(x)

Calculate Widgets With and Without Groups

Description

Calculates widgets with and without groups. Supplies 'groupfull' and 'groupless' (prefixed) columns instead of 'widgets'.

Usage

## S3 method for class 'data.frame'
groupwise(
  x,
  fun = list(sum ~ sum(x, na.rm = TRUE), pct ~ signif(digits = 3, sum/n * 100), ave ~
    signif(digits = 3, mean(x, na.rm = TRUE)), std ~ signif(digits = 3, sd(x, na.rm =
    TRUE)), med ~ signif(digits = 3, median(x, na.rm = TRUE)), min ~ signif(digits = 3,
    min(x, na.rm = TRUE)), max ~ signif(digits = 3, max(x, na.rm = TRUE))),
  fac = list(` ` ~ sum + " (" + pct + "%" + ")"),
  num = list(`Mean (SD)` ~ ave + " (" + std + ")", `Median (range)` ~ med + " (" + min +
    ", " + max + ")"),
  ...
)

Arguments

Value

class 'groupwise', arranged by groups:

Identify Header Rows

Description

Identifies header rows. Generic, with method header_rows.tablet.

Usage

header_rows(x, ...)

Arguments

See Also

Other tablet: as_tablet(), as_tablet.data.frame(), header_rows.tablet(), tablet.tablette(), tablette.tablet()

Identify Header Rows for tablet

Description

Identifies header rows for tablet.

Usage

## S3 method for class 'tablet'
header_rows(x, ...)

Arguments

Value

integer: indices for those rows representing headers

See Also

Other tablet: as_tablet(), as_tablet.data.frame(), header_rows(), tablet.tablette(), tablette.tablet()

Create Header List.

Description

Creates header list. Generic, with method headerlist.tablette.

Usage

headerlist(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
headerlist(tablette(groupwise(x)))

Create Header List for Tablet

Description

Creates header list for tablet.

Usage

## S3 method for class 'tablette'
headerlist(x, ...)

Arguments

Value

list of named integer where each element describes an additional header row with names as indicated, repeated integer times

Create Index

Description

Creates index. Generic, with method index.tablette.

Usage

index(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
index(tablette(groupwise(x)))

Create Index for Tablet

Description

Creates index for tablet.

Usage

## S3 method for class 'tablette'
index(x, ...)

Arguments

Value

named integer giving row groupings with names as indicated, repeated integer times

Drag-and-drop Descriptive Statistics

Description

Generate a table of descriptive statistics by selecting columns from a file. Currently supported formats include *.xpt, *.sas7bdat, and *.csv. Launch the application using mesa() and use the interface to select a data file, such as 'mtcars.xpt' under 'examples/') (or select configuration file 'mtcars.conf' under 'examples/'). Then classify the columns of interest to generate the corresponding displays.

Usage

mesa(launch.browser = TRUE, display.mode = "normal", ...)

Arguments

Details

Currently,

* xpt files are read using the defaults for read.xport,

* sas7bdat files are read using the defaults for read_sas, and

* csv files are read using the defaults for as.csv.

If a file in the same directory has a corresponding base name but a .yaml extension, it is treated as metadata and an attempt is made to apply it to the internal version of the data. This file will not be over-written, but it WILL be constructed if missing. You can hand-edit it to supply metadata. See ?yamlet for format; see the Variables tab for an easy interface.

This is a metadata-driven application. Columns in the data that are *not* in the metadata will be ignored, and columns in the metadata that are *not* in the data will be constructed (maybe *all* of them).

The mtcars datasets in the 'examples' volume is from datasets.

Value

used for side effects: launches shiny application shinyWidgets',

Identify Numerics

Description

Identifies numerics. Generic, with method numerics.data.frame.

Usage

numerics(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
numerics(x)

Identify Numerics for Data Frame

Description

Identifies numeric columns. Stacks values and supplies factor level 'numeric'.

Usage

## S3 method for class 'data.frame'
numerics(x, ..., na.rm_num = FALSE, all_levels = FALSE)

Arguments

Value

same class as x

Identify Observations

Description

Identifies observations. Generic, with method observations.data.frame.

Usage

observations(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
observations(x)

Identify Observations for Data Frame

Description

Identifies observations. Stacks values by level, supplying defaults as necessary.

Usage

## S3 method for class 'data.frame'
observations(x, ..., exclude_name = NULL)

Arguments

Value

class 'observations' arranged by groups (presented first):

Recap Something

Description

Recaps something. Generic, with method recap.knitr_kable.

Usage

recap(x, ...)

Arguments

See Also

Other recap: recap.knitr_kable()

Recap knitr_kable.

Description

Recaps knitr_kable. Specifically, it replaces the first non-tabled caption with multicolumn text. The intent is to prevent repeat bookmarks when generating pdf.

Usage

## S3 method for class 'knitr_kable'
recap(x, cols = NULL, pos = "c", ...)

Arguments

See Also

Other recap: recap()

Relativize a Filepath

Description

Relativizes a filepath. Somewhat the opposite of normalizePath.

Usage

relativizePath(x, dir = getwd(), sep = "/", ...)

Arguments

Details

x and dir are first normalized, then x is expressed relative to dir. If x and dir are on different drives (i.e. C:/ D:/) x is returned as an absolute path.

Splice Some Things Together

Description

Spices some things together. Generic, with tablet-oriented method splice.data.frame.

Usage

splice(x, ...)

Arguments

Value

see methods

Examples

example(splice.data.frame)

Splice A Data Frame

Description

Splices a data.frame. If the data.frame has groups, tablet() is called for each group in succession, only the last of which requests 'all'. The results are column-bound, and duplicate columns are removed.

Usage

## S3 method for class 'data.frame'
splice(x, all = "All", ...)

Arguments

Value

tablet

Examples

library(boot)
library(dplyr)
library(magrittr)
melanoma %>%
  select(-time, -year) %>%
  mutate(sex = factor(sex), ulcer = factor(ulcer)) %>%
  mutate(status2 = ifelse(status == 2, 2, 4)) %>%
  group_by(status, status2) %>%
  splice

Generate a Tablet

Description

Generates a tablet. Generic. See tablet.data.frame and as_kable.tablet.

Usage

tablet(x, ...)

Arguments

Value

see methods

Examples

example(tablet.data.frame)

Generate a Tablet for Data Frame

Description

Generates a 'tablet': a summary table of formatted statistics for factors (is.factor()) and numerics (is.numeric()) in x, with and without grouping variables (if present, see group_by). Column names represent finest level of grouping, distinguished by attribute 'nest' (the values of higher other groups, if any) along with the 'all' column for ungrouped statistics. Column attribute 'n' indicates relevant corresponding observation count. Input should not have column names beginning with '_tablet'.

Usage

## S3 method for class 'data.frame'
tablet(
 x,
 ...,
 na.rm = FALSE,
 all = 'All',
 fun = list(
  sum ~ sum(x,  na.rm = TRUE),
  pct ~ signif(digits = 3,     sum / n * 100        ),
  ave ~ signif(digits = 3,    mean(x,  na.rm = TRUE)),
  std ~ signif(digits = 3,      sd(x,  na.rm = TRUE)),
  med ~ signif(digits = 3,  median(x,  na.rm = TRUE)),
  min ~ signif(digits = 3,     min(x,  na.rm = TRUE)),
  max ~ signif(digits = 3,     max(x,  na.rm = TRUE))
 ),
 fac = list(
  ` ` ~ sum + ' (' + pct + '%' + ')'
 ),
 num = list(
  `Mean (SD)` ~ ave + ' (' + std + ')',
  `Median (range)` ~ med + ' (' + min + ', ' + max + ')'
  ),
 lab = list(
  lab ~ name + '\n(N = ' + n + ')'
 ),
 na.rm_fac = na.rm,
 na.rm_num = na.rm,
 exclude_fac = NULL,
 exclude_name = NULL,
 all_levels = FALSE
)

Arguments

Details

Arguments 'fun', 'fac', 'num', and 'lab' are lists of two-sided formulas that are evaluated in an environment where '+' expresses concatenation (for character elements). The values of LHS should be unique across all four lists. 'fun' is a list of aggregate statistics that have access to N (number of original records), n (number of group members), and x (the numeric observations, or 1 for each factor value). Aggregate statistics generated by 'fun' are available for use in 'fac' and 'num' which create visualizations thereof ('widgets'). Column-specific attributes are available to elements of 'lab', including the special attribute name (the current column name). For 'lab' only, if the RHS succeeds, it becomes the label attribute of the corresponding output column. 'lab' is used here principally to support annotation of *output* columns; if *input* columns have attributes 'label' or 'title' (highest priority) those will have been already substituted for default column names at the appropriate positions in the output.

Missingness of observations (and to a lesser extent, levels of grouping variables) merits special consideration. Be aware that na.rm_fac and na.rm_num take their defaults from na.rm. Furthermore, na.rm_fac may interact with exclude_fac, which is passed to factor as exclude. The goal is to support all possible ways of expressing or ignoring missingness. That said, if aggregate functions are removing NA, the values of arguments beginning with 'na.rm' or 'exclude' may not matter.

Column 1 of output is character. Its values are typically the names of the original columns that were factor or numeric but not in groups(x). If any of these had a label attribute or (priority) a title attribute with class 'latex', then column 1 is assigned the class 'latex' as well. It makes sense therefore to be consistent across input columns regarding the presence or not of a 'latex' label or title. By default, as_kable.tablet dispatches class-specific methods for escape_latex.

Similarly, row 1 of output is typically character. As of version 0.6.6, if any of the grouping variables inherits 'latex', then the return value of tablet.data.frame() has an attribute 'name_class' with value 'latex'.

Value

'tablet' A tablet is a special case of data.frame with grouped rows and columns.

See Also

as_kable.tablet

Examples

library(boot)
library(dplyr)
library(magrittr)
melanoma %>%
  select(-time, -year) %>%
  mutate(sex = factor(sex), ulcer = factor(ulcer)) %>%
  group_by(status) %>%
  tablet

Convert to tablette from tablet.

Description

Converts to 'tablette' from 'tablet'. I.e., makes compact data.frame that emulates the layout expected by as_kable. Preserves attributes 'n', 'label', 'codelist', and 'latex' class if present.

Usage

## S3 method for class 'tablette'
tablet(x, ...)

Arguments

Value

tablette : a data.frame with columns for each combination of groups, and:

See Also

Other tablet: as_tablet(), as_tablet.data.frame(), header_rows(), header_rows.tablet(), tablette.tablet()

Examples

library(boot)
library(dplyr)
library(magrittr)
library(yamlet)
rm(melanoma)
melanoma %<>% select(-time, -year) 
melanoma %<>% decorate('
time:      [ Survival Time Since Operation, day               ]
status:    [ End of Study Patient Status,
           [ Alive: 2, Melanoma Death: 1, Unrelated Death: 3 ]]
sex:       [ Sex, [ Male: 1, Female: 0                       ]]
age:       [ Age at Time of Operation, year                   ]
thickness: [ Tumor Thickness, mm                              ]
ulcer:     [ Ulceration, [ Absent: 0, Present: 1             ]]
')
melanoma %<>% resolve
melanoma %<>% group_by(status, ulcer) 
melanoma %<>% tablet 
melanoma %>% header_rows
melanoma %>% as_kable
melanoma %>% tablette
melanoma %>% tablette %>% tablet
identical(melanoma, tablet(tablette(melanoma)))
  

Convert to tablette

Description

Converts to 'tablette'. Generic, with method tablette.tablet.

Usage

tablette(x, ...)

Arguments

See Also

Other tablette: tablette.tablet()

Generate a Group-wise Tablette

Description

Generates a group-wise tablette. Calculates statistics for all factors and numerics, with and without grouping variables. Column names represent finest level of grouping, distinguished by attribute 'nest' (the values of higher groups). Column names include 'all' column for same statistics without groups. Result columns have corresponding attribute 'n'. 'lab' supplies a label attribute for each column where the RHS succeeds: by default appending 'n' to result column names.

Usage

## S3 method for class 'groupwise'
tablette(x, ..., all = "All", lab = list(lab ~ name + "\n(N = " + n + ")"))

Arguments

Value

'tablette', with columns for each combination of groups, and:

Convert to tablette from tablet

Description

Converts to tablette from tablet. Intends to be the inverse of tablet.tablette.

Usage

## S3 method for class 'tablet'
tablette(x, ...)

Arguments

Value

tablet data.frame

See Also

Other tablette: tablette()

Other tablet: as_tablet(), as_tablet.data.frame(), header_rows(), header_rows.tablet(), tablet.tablette()

Examples

example(tablet.tablette)

Calculate Widgets

Description

Calculates widgets. Generic, with method widgets.devalued.

Usage

widgets(x, ...)

Arguments

Value

see methods

Examples

example(classifiers)
widgets(devalued(observations(x)))

Calculate Widgets for Devalued

Description

Calculates widgets for class 'devalued'. In this context, a widget is a text fragment that formats one or more aggregate statistics, all of which must have been present as LHS of some element of 'fun' in the call to devalued(). Furthermore, LHS must be unique across 'fac' and 'num' for expected behavior.

Usage

## S3 method for class 'devalued'
widgets(
  x,
  fac = list(` ` ~ sum + " (" + pct + "%" + ")"),
  num = list(`Mean (SD)` ~ ave + " (" + std + ")", `Median (range)` ~ med + " (" + min +
    ", " + max + ")"),
  ...
)

Arguments

Details

In the context of this call, "+" is redefined to allow concatenation of text. Evaluation proceeds left to right as usual.

Value

class 'widgets', arranged by groups: