Help for package crosstable

Title:

Crosstables for Descriptive Analyses

Version:

0.8.1

Description:

Create descriptive tables for continuous and categorical variables. Apply summary statistics and counting function, with or without a grouping variable, and create beautiful reports using 'rmarkdown' or 'officer'. You can also compute effect sizes and statistical tests if needed.

License:

GPL-3

URL:

https://danchaltiel.github.io/crosstable/, https://github.com/DanChaltiel/crosstable/

BugReports:

https://github.com/DanChaltiel/crosstable/issues/

Depends:

R (≥ 3.1.0)

Imports:

checkmate (≥ 1.9.0), cli (≥ 3.0.0), dplyr (≥ 1.1.0), flextable (≥ 0.5.1), forcats (≥ 1.0.0), glue (≥ 1.3.0), lifecycle (≥ 0.2.0), methods, officer (≥ 0.4.0), purrr (≥ 0.2.3), rlang (≥ 1.0.0), stats, stringr (≥ 1.4.0), tibble (≥ 1.1), tidyr (≥ 1.0.0), utils,

Suggests:

callr, covr, crayon, xml2, digest, gt, expss, ggplot2, gmodels, Hmisc, hms, jsonlite, knitr, lubridate, openxlsx, rmarkdown, sloop, stringi, survival, systemfonts, tidyselect, testthat (≥ 3.0.0), withr, waldo

VignetteBuilder:

knitr

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

Config/testthat/edition:

Config/testthat/parallel:

true

Config/testthat/start-first:

by_factor , effects, officer

NeedsCompilation:

Packaged:

2024-11-01 10:05:01 UTC; Dan

Author:

Dan Chaltiel

[aut, cre], David Hajage [ccp]

Maintainer:

Dan Chaltiel <dan.chaltiel@gmail.com>

Repository:

CRAN

Date/Publication:

2024-11-01 10:30:03 UTC

crosstable: Crosstables for Descriptive Analyses

Description

Details

The crosstablepackage is centered on the crosstable()' function. See vignettes for more information.

Author(s)

Maintainer: Dan Chaltiel dan.chaltiel@gmail.com (ORCID)

Other contributors:

David Hajage [conceptor]

Return the number of non NA observations

Description

Return the number of non NA observations

Usage

N(x)

Arguments

x

a vector

Value

integer, number of non NA observations

Author(s)

David Hajage

Batch set variable labels

Description

This function is a copycat of from expss package v0.10.7 (slightly modified) to avoid having to depend on expss. See expss::apply_labels() for more documentation. Note that this version is not compatible with data.table.

Usage

apply_labels(data, ..., warn_missing = FALSE)

Arguments

data

data.frame/list

...

named arguments

warn_missing

if TRUE, throw a warning if some names are missing

Value

An object of the same type as data, with labels

Author(s)

Dan Chaltiel

Examples

iris %>%
  apply_labels(Sepal.Length="Length of Sepal",
               Sepal.Width="Width of Sepal") %>%
  crosstable()

Turns a `crosstable` object into a formatted `flextable`

Description

Turns a crosstable object into a formatted flextable

Usage

## S3 method for class 'crosstable'
as_flextable(
  x,
  keep_id = FALSE,
  by_header = NULL,
  autofit = TRUE,
  compact = FALSE,
  show_test_name = TRUE,
  fontsizes = list(body = 11, subheaders = 11, header = 11),
  padding_v = NULL,
  remove_header_keys = TRUE,
  header_show_n = FALSE,
  header_show_n_pattern = "{.col} (N={.n})",
  generic_labels = list(id = ".id", variable = "variable", value = "value", total =
    "Total", label = "label", test = "test", effect = "effect"),
  ...
)

as_flextable(x, ...)

Arguments

x

the result of crosstable().

keep_id

whether to keep the .id column.

by_header

a string to override the header if x has only one by stratum.

autofit

whether to automatically adjust the table. Can also be a function.

compact

whether to compact the table. If TRUE, see ct_compact.crosstable() to see how to use keep_id.

show_test_name

in the test column, show the test name.

fontsizes

font sizes as a list of keys. Default to list(body=11, subheaders=11, header=11). If set through arguments instead of options, all 3 names should be specified.

padding_v

vertical padding (body).

remove_header_keys

if TRUE and x has several by strata, header will only display values.

header_show_n

numeric vector telling on which depth the group size should be indicated in the header. You can control the pattern using option crosstable_options. See crosstable_options() for details about it. See example for use case.

header_show_n_pattern

glue pattern used when header_show_n==TRUE. .col is the name of the column and .n the size of the group. Default to {.col} (N={.n}); you can also use {.col_key} and {.col_val} when by has multiple stratum. To control the "Total" column, enter this as a list with names "cell" and "total".

generic_labels

names of the crosstable default columns. Useful for translation for instance.

...

unused.

Value

a flextable.

Methods (by class)

as_flextable(crosstable): Turns a crosstable object into a formatted flextable.

Author(s)

Dan Chaltiel

Examples

crosstable_options(crosstable_fontsize_header=14,
                   crosstable_fontsize_subheaders=10,
                   crosstable_fontsize_body=8)
crosstable(iris) %>% as_flextable()
crosstable(mtcars2, -model, by=c(am, vs)) %>% as_flextable(header_show_n=1)
crosstable(mtcars2, cols=c(mpg, cyl), by=am, effect=TRUE) %>%
   as_flextable(keep_id=TRUE, autofit=FALSE)
crosstable(mtcars2, cols=c(mpg, cyl), by=am, effect=TRUE, total=TRUE) %>%
   as_flextable(compact=TRUE, header_show_n=TRUE,
                header_show_n_pattern=list(cell="{.col} (N={.n})", total="Total\n(N={.n})"))

#Renaming (because why not?)
crosstable(mtcars2, am, by=vs, total="both", test=TRUE, effect=TRUE) %>%
   dplyr::rename(ID=.id, math=variable, Tot=Total, lab=label, pval=test, fx=effect) %>%
   as_flextable(by_header = "Engine shape",
                generic_labels=list(id = "ID", variable = "math", total="Tot",
                                    label = "lab", test = "pval", effect="fx"))

Converts a `crosstable` object into a formatted `gt` table.

Description

Converts a crosstable object into a formatted gt table.

Method to convert an object to a gt table

Default method to convert an object to a gt table

Usage

## S3 method for class 'crosstable'
as_gt(
  x,
  show_test_name = TRUE,
  by_header = NULL,
  keep_id = FALSE,
  generic_labels = list(id = ".id", variable = "variable", value = "value", total =
    "Total", label = "label", test = "test", effect = "effect"),
  ...
)

as_gt(x, ...)

## Default S3 method:
as_gt(x, ...)

Arguments

x

object to be converted

show_test_name

in the test column, show the test name

by_header

a string to override the by header

keep_id

whether to keep the .id column

generic_labels

names of the crosstable default columns

...

arguments for custom methods

Value

a formatted gt table

Methods (by class)

as_gt(crosstable): For crosstables
as_gt(default): default function

Author(s)

Dan Chaltiel

Examples

xx = mtcars2 %>% dplyr::select(2:10)
crosstable(xx) %>% as_gt
crosstable(xx, by=am) %>% as_gt
crosstable(xx, by=cyl, test=TRUE, total=TRUE) %>%
   as_gt(keep_id=TRUE, show_test_name=FALSE, by_header="Cylinders")

Converts a `crosstable` object into a formatted, savable `openxlsx` workbook.

Description

Converts a crosstable object into a formatted, savable openxlsx workbook.

Usage

as_workbook(
  x,
  show_test_name = TRUE,
  by_header = NULL,
  keep_id = FALSE,
  generic_labels = list(id = ".id", variable = "variable", value = "value", total =
    "Total", label = "label", test = "test", effect = "effect"),
  ...
)

Arguments

x

the result of crosstable() or a list of crosstables

show_test_name

in the test column, show the test name

by_header

a string to override the by header

keep_id

whether to keep the .id column

generic_labels

names of the crosstable default columns

...

unused

Value

an openxlsx workbook containing the crosstable(s)

Author(s)

Dan Chaltiel

Examples

library(openxlsx)
target = tempfile(fileext=".xlsx")

x=crosstable(mtcars2, c(mpg, vs, gear), total=TRUE, test=TRUE)
as_workbook(x, keep_id=TRUE) %>%
    saveWorkbook(file=target)
if(interactive()) browseURL(target)

target = tempfile(fileext=".xlsx")
x2=list(iris=crosstable(iris2), crosstable(mtcars2))
as_workbook(x2, keep_id=TRUE) %>%
    saveWorkbook(file=target)
if(interactive()) browseURL(target)

Add a crosstable to an `officer` document

Description

body_add_crosstable() adds such a flextable an officer document.

Usage

body_add_crosstable(
  doc,
  x,
  body_fontsize = NULL,
  header_fontsize = ceiling(body_fontsize * 1.2),
  padding_v = NULL,
  allow_break = TRUE,
  max_cols = 25,
  ...
)

Arguments

doc

a rdocx object, created by officer::read_docx()

x

a crosstable object

body_fontsize

fontsize of the body

header_fontsize

fontsize of the header. Defaults to 1.2*body_fontsize.

padding_v

vertical padding of all table rows

allow_break

allow crosstable rows to break across pages

max_cols

max number of columns for x

...

further arguments passed to as_flextable.crosstable()

Value

The docx object doc

Author(s)

Dan Chaltiel

Examples

#Officer
library(officer)
mytable = crosstable(mtcars2)
doc = read_docx() %>%
    body_add_crosstable(mytable) %>%
    body_add_break %>%
    body_add_crosstable(mytable, compact=TRUE)

dfile = tempfile(fileext=".docx")
print(doc, target = dfile)
if(interactive()) browseURL(dfile)

Adds a standard footnote explaining the abbreviations used in a crosstable

Description

Use it below body_add_crosstable(). Footnote: Med: median, IQR: interquartile range, Std: standard deviation. Percentages are expressed in column.

Usage

body_add_crosstable_footnote(doc)

Arguments

doc

a rdocx object

Value

The docx object doc

Author(s)

Dan Chaltiel

Alternative to `officer::body_add_gg()` which uses `ggplot` syntax

Description

Alternative to officer::body_add_gg() which uses ggplot syntax

Usage

body_add_gg2(
  doc,
  value,
  width = getOption("crosstable_gg_width", 6),
  height = getOption("crosstable_gg_height", 5),
  units = getOption("crosstable_units", "in"),
  style = getOption("crosstable_style_image", doc$default_styles$paragraph),
  res = 300,
  ...
)

Arguments

doc

an rdocx object

value

ggplot object

width, height

width and height. Can be abbreviated to w and h.

units

units for width and height

style

paragraph style

res

resolution of the png image in ppi (passed to the argument dpi of ggplot2::ggsave())

...

other arguments to be passed to ggplot2::ggsave()

Value

The docx object doc

Author(s)

Dan Chaltiel

Examples

library(officer)
library(ggplot2)
p = ggplot(data=iris, aes(Sepal.Length, Petal.Length)) + geom_point()
crosstable_options(
  units="cm",
  style_image="centered"
)
doc = read_docx() %>%
 body_add_normal("Text before") %>%
 body_add_gg2(p, w=14, h=10, scale=1.5) %>% #or units="cm" instead of using options
 body_add_normal("Text after")
write_and_open(doc)

Alternative to `officer::body_add_img()` which adds a `units` choice

Description

Alternative to officer::body_add_img() which adds a units choice

Usage

body_add_img2(
  doc,
  src,
  width,
  height,
  units = getOption("crosstable_units", "in"),
  style = getOption("crosstable_style_image", doc$default_styles$paragraph),
  ...
)

Arguments

doc

an rdocx object

src

image filename, the basename of the file must not contain any blank.

width, height

width and height. Can be abbreviated to w and h.

units

units for width and height

style

paragraph style

...

other arguments to be passed to officer::body_add_img()

Value

The docx object doc

Author(s)

Dan Chaltiel

Examples

img.file = file.path( R.home("doc"), "html", "logo.jpg" )
if(file.exists(img.file)){
    library(officer)
    options(crosstable_units="cm")
    doc = read_docx() %>%
        body_add_normal("This is the R logo.") %>%
        body_add_img2(img.file, h=7.6, w=10, style="centered") #or units="cm" without options
    #write_and_open(doc)
}

Add a legend to a table or a figure

Description

Add a legend to a table or a figure in an officer document. Legends can be referred to using the ⁠@ref⁠ syntax in body_add_normal() (see examples for some use cases). Table legends should be inserted before the table while figure legends should be inserted after the figure.

Usage

body_add_table_legend(
  doc,
  legend,
  ...,
  bookmark = NULL,
  legend_style = getOption("crosstable_style_legend", doc$default_styles$paragraph),
  style = deprecated(),
  legend_prefix = NULL,
  name_format = NULL,
  legend_name = "Table",
  seqfield = "SEQ Table \\* Arabic",
  par_before = FALSE,
  envir = parent.frame(),
  legacy = FALSE
)

body_add_figure_legend(
  doc,
  legend,
  ...,
  bookmark = NULL,
  legend_style = getOption("crosstable_style_legend", doc$default_styles$paragraph),
  style = deprecated(),
  legend_prefix = NULL,
  name_format = NULL,
  legend_name = "Figure",
  seqfield = "SEQ Figure \\* Arabic",
  par_after = FALSE,
  envir = parent.frame(),
  legacy = FALSE
)

Arguments

doc

a docx object

legend

the table legend. Supports glue syntax and markdown syntax (see Section below).

...

unused

bookmark

the id of the bookmark. This is the id that should then be called in body_add_normal() using the "\\@ref(id)" syntax. Forbidden characters will be removed.

legend_style

style of of the whole legend. May depend on the docx template. However, if name_format is provided with a specific font.size, this size will apply to the whole legend for consistency.

style

deprecated in favor of name_format.

legend_prefix

a prefix that comes before the legend, after the numbering

name_format

format of the legend's LHS (legend_name + numbering) using officer::fp_text_lite() or officer::fp_text(). Default to fp_text_lite(bold=TRUE) in addition to the format defined in legend_style. Note that the reference to the bookmark will have the same specific format in the text.

legend_name

name before the numbering. Default to either "Table" or "Figure".

seqfield

Keep default. Otherwise, you may figure it out doing this: in a docx file, insert a table legend, right click on the inserted number and select "Toggle Field Codes". This argument should be the value of the field, with extra escaping.

par_before, par_after

should an empty paragraph be inserted before/after the legend?

envir

Environment to evaluate each expression in glue().

legacy

use the old version of this function, if you cannot update {officer} to v0.4+

Value

The docx object doc

Warning

Be aware that you unfortunately cannot reference a bookmark more than once using this method. Writing:
body_add_normal("Table \\@ref(iris_col1) is about flowers. I really like Table \\@ref(iris_col1).")
will prevent the numbering from applying.

What to do if there is still no numbering?

During the opening of the document, MS Word might ask you to "update the fields", to which you should answer "Yes".
If it is not asked or if you answer "No", the legends added with body_add_table_legend() or body_add_figure_legend() might have no actual numbers displayed.
In this case, you have to manually update the references in MS Word: select all (Ctrl+A), then update (F9), sometimes twice. More info on https://ardata-fr.github.io/officeverse/faq.html#update-fields.

Markdown support

In all crosstable helpers for officer, you can use the following Markdown syntax to format your text:

bold: "**text in bold**"
*italics: "*text in italics*"
subscript: "Text in ~subscript~"
superscript: "Text in ^superscript^"
newline: ⁠Before After⁠
color: "<color:red>red text</color>"
shade: "<shade:yellow>yellow text</shade>" (background color)
font family: "<ff:symbol>symbol</ff>" (

Note that the font name depends on your system language. For instant, in French, it would be Symbol with an uppercase first letter.

See the last example of body_add_normal() for a practical case.

Author(s)

Dan Chaltiel

Examples

library(officer)
library(ggplot2)
p = ggplot(iris, aes(x=Sepal.Length, y=Sepal.Width, color=Species)) + geom_point()
fp_italic = fp_text_lite(italic=TRUE, font.size=10)
x = read_docx() %>%
    body_add_normal("There is Table \\@ref(iris_col1) and Table \\@ref(iris_col2). ",
                    "The `iris` dataset is about flowers.") %>%
    body_add_normal() %>%
    body_add_table_legend("Iris dataset, column 1 (mean={round(mean(iris[[1]]), 2)})",
                           bookmark="iris_col1") %>%
    body_add_crosstable(crosstable(iris[1])) %>%
    body_add_normal() %>%
    body_add_table_legend("Iris dataset, column 2 (mean={round(mean(iris[[2]]), 2)})",
                          bookmark="iris_col2",
                          name_format=fp_italic, legend_style="Balloon Text") %>%
    body_add_crosstable(crosstable(iris[2])) %>%
    body_add_normal() %>%
    body_add_normal("There is also the figure \\@ref(iris_fig)") %>%
    body_add_gg(p) %>%
    body_add_figure_legend("Iris plot", bookmark="iris_fig")
write_and_open(x)
#If asked to update fields, press "Yes". Otherwise press Ctrl+A then F9 twice for the references
#to appear.

Add a list to an `officer` document

Description

Add a list to an officer document

Usage

body_add_list(doc, value, ordered = FALSE, style = NULL, ...)

body_add_list_item(doc, value, ordered = FALSE, style = NULL, ...)

Arguments

doc

a docx object

value

a character vector (body_add_list()) or scalar (body_add_list_item). See Section below for markdown support.

ordered

if TRUE, adds an ordered list, if FALSE (default), adds a bullet list

style

specify the style manually, overriding ordered. A better way is to set options crosstable_style_list_ordered and crosstable_style_list_unordered globally.

...

passed on to officer::body_add_par()

Details

Ordered lists and bullet lists are not supported by the default officer template (see https://github.com/davidgohel/officer/issues/262). You have to manually set custom styles matching those list in a custom Word template file. Then, you can use either the style argument or crosstable options. See examples for more details.

Value

The docx object doc

Markdown support

In all crosstable helpers for officer, you can use the following Markdown syntax to format your text:

bold: "**text in bold**"
*italics: "*text in italics*"
subscript: "Text in ~subscript~"
superscript: "Text in ^superscript^"
newline: ⁠Before After⁠
color: "<color:red>red text</color>"
shade: "<shade:yellow>yellow text</shade>" (background color)
font family: "<ff:symbol>symbol</ff>" (

Note that the font name depends on your system language. For instant, in French, it would be Symbol with an uppercase first letter.

See the last example of body_add_normal() for a practical case.

Author(s)

Dan Chaltiel

Examples

## Not run: 
#For this example to work, `my_template.docx` should include styles named
#`ordered_list` and `unordered_list`

library(officer)
library(crosstable)
options(crosstable_style_list_ordered="ordered_list")
options(crosstable_style_list_unordered="unordered_list")

read_docx("my_template.docx") %>%
 body_add_list(c("Numbered item 1", "Numbered item 2"), ordered = TRUE) %>%
 body_add_list_item("Numbered item 3", ordered = TRUE) %>%
 body_add_list(c("Bullet item 1", "Bullet item 2"), ordered = FALSE) %>%
 body_add_list_item("Bullet item 3", ordered = FALSE) %>%
 write_and_open()

## End(Not run)

Add a new paragraph with default style

Description

Add a new paragraph in an officer document with default style.
Variables can be inserted in the text as multiple strings (paste() style) or enclosed by braces (glue() style).
Basic markdown syntax is available: ⁠**bold**⁠, ⁠*italic*⁠, and ⁠_underlined_⁠.
References to any bookmark can be inserted using the syntax ⁠@ref(bookmark)⁠ and newlines can be inserted using the token ⁠ ⁠.

Usage

body_add_normal(
  doc,
  ...,
  .sep = "",
  style = NULL,
  squish = TRUE,
  font_size = NA,
  envir = parent.frame(),
  parse = c("ref", "format", "code")
)

Arguments

doc

the doc object (created with the read_docx function of officer package)

...

one or several character strings, pasted using .sep. As with glue::glue(), expressions enclosed by braces will be evaluated as R code. If more than one variable is passed, all should be of length 1.

.sep

Separator used to separate elements.

style

Style for normal text. Best set with crosstable_options().

squish

Whether to squish the result (remove trailing and repeated spaces). Default to TRUE. Allows to add multiline paragraph without breaking the string.

font_size

Font size.

envir

Environment to evaluate each expression in glue().

parse

which format to parse. Default to all formats (c("ref", "format", "code")).

Value

a new doc object

The docx object doc

Markdown support

In all crosstable helpers for officer, you can use the following Markdown syntax to format your text:

bold: "**text in bold**"
*italics: "*text in italics*"
subscript: "Text in ~subscript~"
superscript: "Text in ^superscript^"
newline: ⁠Before After⁠
color: "<color:red>red text</color>"
shade: "<shade:yellow>yellow text</shade>" (background color)
font family: "<ff:symbol>symbol</ff>" (

Note that the font name depends on your system language. For instant, in French, it would be Symbol with an uppercase first letter.

See the last example of body_add_normal() for a practical case.

Author(s)

Dan Chaltiel

Examples

library(officer)
library(crosstable)

info_rows = c("Also, table iris has {nrow(iris)} rows.",
              "And table mtcars has {nrow(mtcars)} rows.")
doc = read_docx()  %>%
    body_add_normal("Table iris has", ncol(iris), "columns.", .sep=" ") %>% #paste style
    body_add_normal("However, table mtcars has {ncol(mtcars)} columns") %>% #glue style
    body_add_normal(info_rows)                                          %>% #vector style
    body_add_normal("")
doc = doc %>%
    body_add_normal("You can write text in *italic1*, _underlined1_, **bold1**, and `code`,
                    and you can also add * **references** *, for instance a ref to Table
                    @ref(my_table). Multiple spaces are ignored (squished) so that you
                    can enter multiline text.") %>%
    body_add_normal() %>%
    body_add_normal("Here I should use `body_add_crosstable()` to add a table before the
                     legend.") %>%
    body_add_table_legend("My pretty table", bookmark="my_table")
write_and_open(doc)

#Markdown support
read_docx() %>%
  body_add_normal("This is **bold and *italic* (see Table @ref(my_bkm)). ** <br> This is
                   **bold `console \\*CODE\\*` and *bold _and_ italic* **") %>%
  body_add_normal("This is <color:red>red **bold** text</color>, this is ~subscript *italic*~,
                   and this is ^superscript with <shade:yellow>yellow</shade>^") %>%
  body_add_normal("This is <ff:Alibi>a fancy font</ff> and this `is code`!!") %>%
              #you might need to change "Alibi" to "alibi" here
  body_add_normal() %>%
  body_add_table_legend("Some table legend", bookmark="my_bkm") %>%
  write_and_open()

Add a list of tables

Description

Add a list of tables in an officer document. crosstables will be added using body_add_crosstable() and flextables will be added using flextable::body_add_flextable(). Plain dataframes will be converted to flextables.

Usage

body_add_table_list(
  doc,
  l,
  fun_before = "title2",
  fun_after = NULL,
  fun = fun_before,
  ...
)

body_add_flextable_list(...)

body_add_crosstable_list(...)

Arguments

doc

a rdocx object, created by officer::read_docx()

l

a named list of tables (of class crosstable, flextable, or data.frame).

fun_before

a function to be used before each table

fun_after

a function to be used after each table.

fun

Deprecated

...

arguments passed on to body_add_crosstable() or flextable::body_add_flextable()

Value

The docx object doc

`fun_before` and `fun_after`

These should be function of the form ⁠function(doc, .name)⁠ where .name is the name of the current table of the list. You can also pass "title2" to add the name as a title of level 2 between each table (works for levels 3 and 4 as well), "newline" to simply add a new line, or even NULL to not separate them (beware that the tables might merge then). fun_before is designed to add a title while fun_after is designed to add a table legend (cf. examples).

Examples

library(officer)
ctl = list(iris2=crosstable(iris2, 1),
           "Just a flextable"=flextable::flextable(mtcars2[1:5,1:5]),
           "Just a dataframe"=iris2[1:5,1:5])

fun1 = function(doc, .name){
    doc %>%
        body_add_title(" This is table '{.name}' as a flex/crosstable", level=2) %>%
        body_add_normal("Here is the table:")
}
fun2 = function(doc, .name){
  doc %>% body_add_table_legend("{.name}", bookmark=.name)
}
read_docx() %>%
  body_add_title("Separated by subtitle", 1) %>%
  body_add_table_list(ctl, fun_before="title2") %>%
  body_add_break() %>%
  body_add_title("Separated using a custom function", 1) %>%
  body_add_normal("You can therefore use bookmarks, for instance here are
                   tables \\@ref(iris2), \\@ref(just_a_flextable)
                   and \\@ref(just_a_dataframe).") %>%
  body_add_table_list(ctl, fun_before=fun1, fun_after=fun2, body_fontsize=8) %>%
  write_and_open()

Add a section with a table and its legend

Description

Add a section with a table and its legend

Usage

body_add_table_section(
  doc,
  x,
  legend,
  ...,
  bookmark = NULL,
  title = getOption("crosstable_section_title", TRUE),
  title_lvl = getOption("crosstable_section_title_level", 3),
  sentence = getOption("crosstable_section_sentence", FALSE)
)

Arguments

doc

a rdocx object

x

a table: crosstable, flextable, or plain old dataframe

legend

the legend to use

...

passed on to flextable::body_add_flextable() or body_add_crosstable()

bookmark

the bookmark to use. Defaults to the cleaned variable name of x

title

the title to add for the section. Can also be FALSE (no title) or TRUE (the title defaults to legend)

title_lvl

the title level if applicable

sentence

a sentence to add between the title (if applicable) and the table. If TRUE, defaults to "Information about {tolower(title)} is described in Table @ref({bookmark})".

Value

The docx object doc

Examples

library(officer)
read_docx() %>%
  body_add_title("Description", 1) %>%
  body_add_title("Population A", 2) %>%
  body_add_table_section(head(iris), "The iris dataset", sentence=TRUE) %>%
  body_add_table_section(crosstable(iris), "A crosstable of the iris dataset",
                         title=FALSE, sentence=TRUE, body_fontsize=8) %>%
  write_and_open()

Add a title to an `officer` document

Description

Add a title to an officer document

Usage

body_add_title(
  doc,
  value,
  level = 1,
  squish = TRUE,
  envir = parent.frame(),
  style = getOption("crosstable_style_heading", "heading")
)

Arguments

doc

the doc object (created with the read_docx function of officer package)

value

a character string. See Section below for markdown support.

level

the level of the title. See styles_info(doc) to know the possibilities.

squish

Whether to squish the result (remove trailing and repeated spaces). Default to TRUE.

envir

Environment to evaluate each expression in glue().

style

the name of the title style. See styles_info(doc) to know the possibilities.

Value

The docx object doc

Markdown support

In all crosstable helpers for officer, you can use the following Markdown syntax to format your text:

bold: "**text in bold**"
*italics: "*text in italics*"
subscript: "Text in ~subscript~"
superscript: "Text in ^superscript^"
newline: ⁠Before After⁠
color: "<color:red>red text</color>"
shade: "<shade:yellow>yellow text</shade>" (background color)
font family: "<ff:symbol>symbol</ff>" (

Note that the font name depends on your system language. For instant, in French, it would be Symbol with an uppercase first letter.

See the last example of body_add_normal() for a practical case.

Author(s)

Dan Chaltiel

Examples

library(officer)
library(crosstable)
library(dplyr)
doc = read_docx() %>%
   body_add_title("La table iris (nrow={nrow(iris)})", 1) %>%
   body_add_title("Description", 2) %>%
   body_add_normal("La table iris a ", ncol(iris), " colonnes.")
#write_and_open(doc)

Replace text on several bookmarks at once

Description

Replace text on several bookmarks at once

Usage

body_replace_text_at_bkms(doc, ..., envir = parent.frame())

Arguments

doc

a rdocx object

...

named

envir

Environment to evaluate each expression in glue().

Value

The docx object doc

Author(s)

Dan Chaltiel

Cleans names of a dataframe while retaining old names as labels

Description

Cleans names of a dataframe while retaining old names as labels

Usage

clean_names_with_labels(
  df,
  except = NULL,
  .fun = getOption("crosstable_clean_names_fun")
)

Arguments

df

a data.frame

except

<tidy-select> columns that should not be renamed.

.fun

the function used to clean the names. Default function is limited; if the cleaning is not good enough you could use janitor::make_clean_names()

Value

A dataframe with clean names and label attributes

Author(s)

Dan Chaltiel

Examples

#options(crosstable_clean_names_fun=janitor::make_clean_names)
x = data.frame("name with space"=1, TwoWords=1, "total $ (2009)"=1, àccénts=1,
               check.names=FALSE)
cleaned = clean_names_with_labels(x, except=TwoWords)
cleaned %>% names()
cleaned %>% get_label()

Confidence interval of a numeric vector

Description

Not an S3 method, which might have conflicted with stats::confint.

Usage

confint_numeric(object, level = 0.95, B = 0)

Arguments

object

a vector, numeric or equivalent (date, logical...)

level

the confidence level required

B

if >0, the number of bootstraps

Value

the vector [conf_inf, conf_sup]

Author(s)

Dan Chaltiel

Examples

confint_numeric(iris$Sepal.Length)
confint_numeric(mtcars2$hp_date)
confint_numeric(mtcars2$hp_date, level=0.99)

Summarize a numeric vector

Description

Summarize a numeric vector with min, max, mean, sd, median, IQR, n and missings.

Usage

cross_summary(x, dig = 1, ...)

Arguments

x

a numeric vector

dig

number of digits

...

params to pass on to format_fixed(): zero_digits and only_round

Value

a list of named functions

Author(s)

Dan Chaltiel, David Hajage

Examples

cross_summary(iris$Sepal.Length)
cross_summary(iris$Petal.Width, dig=3)
cross_summary(mtcars2$hp_date)
cross_summary(mtcars2$qsec_posix, date_format="%d/%m %H:%M")

Easily describe datasets

Description

Generate a descriptive table of all chosen columns, as contingency tables for categorical variables and as calculation summaries for numeric variables. If the by argument points to one or several categorical variables, crosstable will output a description of all columns for each level. Otherwise, if it points to a numeric variable, crosstable will calculate correlation coefficients with all other selected numeric columns. Finally, if it points to a Surv object, crosstable will describe the survival at different times.

Can be formatted as an HTML table using as_flextable().

Usage

crosstable(
  data,
  cols = everything(),
  ...,
  by = NULL,
  total = c("none", "row", "column", "both"),
  percent_pattern = "{n} ({p_row})",
  percent_digits = 2,
  num_digits = 1,
  showNA = c("ifany", "always", "no"),
  label = TRUE,
  funs = c(` ` = cross_summary),
  funs_arg = list(),
  cor_method = c("pearson", "kendall", "spearman"),
  drop_levels = FALSE,
  remove_zero_percent = NULL,
  unique_numeric = 3,
  date_format = NULL,
  times = NULL,
  followup = FALSE,
  test = FALSE,
  test_args = crosstable_test_args(),
  effect = FALSE,
  effect_args = crosstable_effect_args(),
  margin = deprecated(),
  .vars = deprecated()
)

Arguments

data

A data.frame

cols

<tidy-select> Columns to describe, default to everything(). See examples or vignette("crosstable-selection") for more details.

...

Unused. All parameters after this one must be named.

by

The variable to group on. Character or name.

total

one of ["none", "row", "column" or "both"] to indicate whether to add total rows and/or columns. Default to none.

percent_pattern

Pattern used to describe proportions in categorical data. Syntax uses a glue::glue() specification, see the section below for more details. Default to "{n} ({p_col})" if by is null and "{n} ({p_row})" if it is not.

percent_digits

Number of digits for percentages.

num_digits

Number of digits for numeric summaries.

showNA

Whether to show NA in categorical variables (one of c("ifany", "always", "no"), like in table()).

label

Whether to show labels. See import_labels() or set_label()for how to add labels to the dataset columns.

funs

Functions to apply to numeric variables. Default to cross_summary().

funs_arg

Additional parameters for funs, e.g. digits (the number of decimal places) for the default cross_summary(). Ultimately, these arguments are passed to format_fixed().

cor_method

One of c("pearson", "kendall", "spearman") to indicate which correlation coefficient is to be used.

drop_levels

Whether to drop unused levels of factor variables. Default to TRUE.

remove_zero_percent

Whether to remove proportions when n==0. Default to FALSE.

unique_numeric

The number of non-missing different levels a variable should have to be considered as numeric.

date_format

if x is a vector of Date or POSIXt, the format to apply (see strptime for formats)

times

When using formula with survival::Surv() objects, which times to summarize.

followup

When using formula with survival::Surv() objects, whether to display follow-up time.

test

Whether to perform tests.

test_args

See crosstable_test_args to override default testing behaviour.

effect

Whether to compute a effect measure.

effect_args

See crosstable_effect_args to override default behaviour.

margin

Deprecated in favor of percent_pattern. One of ["row", "column", "cell", "none", or "all"]. Default to row.

.vars

Deprecated in favor of cols.

Value

A data.frame/tibble of class crosstable

About `percent_pattern`

The percent_pattern argument is very powerful but can be difficult to understand at first :

It is usually a single string that uses the glue syntax, where variables are put in curly braces ({x}).
Counts are expressed as {n}, {n_row}, {n_col}, and {n_tot}, and proportions as {p_row}, {p_col}, and {p_cell}, depending on the margin on which they are calculated.
For each variable, a version including missing values in the total is proposed as {n_xxx_na} or {p_xxx_na}.
For each proportion, a confidence interval is also calculated using Wilson score and can be expressed as {p_xxx_inf} and {p_xxx_sup}. See examples for practical applications.
Alternatively, percent_pattern can be a list of characters with names body, total_row, total_col, and total_all to also control the pattern in other parts of the crosstable than the body.

Author(s)

Dan Chaltiel

Examples

#whole table
crosstable(iris)
crosstable(mtcars)
crosstable(mtcars2)

#tidyselection, custom functions
library(dplyr)
crosstable(mtcars2, c(ends_with("t"), starts_with("c")), by=vs,
           funs=c(mean, quantile), funs_arg=list(probs=c(.25,.75)))

#margin and totals, multiple by
crosstable(mtcars2, c(disp, cyl), by=c(am, vs),
           margin=c("row", "col"), total = "both")

#predicate selection, correlation, effect calculation
crosstable(mtcars2, where(is.numeric), by=hp, effect=TRUE)

#lambda selection & statistical tests
crosstable(mtcars2, ~is.numeric(.x) && mean(.x)>50, by=vs, test=TRUE)

#Dates
mtcars2$my_date = as.Date(mtcars2$hp , origin="2010-01-01") %>% set_label("Some nonsense date")
crosstable(mtcars2, my_date, by=vs, date_format="%d/%m/%Y")

#Survival data (using formula syntax)
library(survival)
crosstable(aml, Surv(time, status) ~ x, times=c(0,15,30,150), followup=TRUE)

#Patterns
crosstable(mtcars2, vs, by=am, percent_digits=0,
           percent_pattern="{n} ({p_col} / {p_row})")
crosstable(mtcars2, vs, by=am, percent_digits=0,
           percent_pattern="N={n} \np[95%CI] = {p_col} [{p_col_inf}; {p_col_sup}]")
str_high="n>5"; str_lo="n<=5"
crosstable(mtcars2, vs, by=am, percent_digits=0,
           percent_pattern="col={p_col}, row={p_row} ({ifelse(n<5, str_lo, str_high)})")

Default arguments for calculating and displaying effects in `crosstable()`

Description

This helper function provides default parameters for defining how the effect sizes should be computed. It belongs to the effect_args argument of the crosstable() function. See effect_summary, effect_tabular, and effect_survival for more insight.

Usage

crosstable_effect_args(
  effect_summarize = diff_mean_auto,
  effect_tabular = effect_odds_ratio,
  effect_survival = effect_survival_coxph,
  effect_display = display_effect,
  conf_level = 0.95,
  digits = 2
)

Arguments

effect_summarize

a function of three arguments (continuous variable, grouping variable and conf_level), used to compare continuous variable. Returns a list of five components: effect (the effect value(s)), ci (the matrix of confidence interval(s)), effect.name (the interpretation(s) of the effect value(s)), effect.type (the description of the measure used) and conf_level (the confidence interval level). Users can use diff_mean_auto(), diff_mean_student(), diff_mean_boot(), or diff_median(), or their custom own function.

effect_tabular

a function of three arguments (two categorical variables and conf_level) used to measure the associations between two factors. Returns a list of five components: effect (the effect value(s)), ci (the matrix of confidence interval(s)), effect.name (the interpretation(s) of the effect value(s)), effect.type (the description of the measure used) and conf_level (the confidence interval level).Users can use effect_odds_ratio(), effect_relative_risk(), or effect_risk_difference(), or their custom own function.

effect_survival

a function of two argument (a formula and conf_level), used to measure the association between a censored and a factor. Returns the same components as created by effect_summarize.Users can use effect_survival_coxph() or their custom own function.

effect_display

a function to format the effect. See display_effect().

conf_level

the desired confidence interval level

digits

the decimal places

Value

A list with effect parameters

Author(s)

Dan Chaltiel

Options for the package `crosstable`

Description

Use this function to manage your crosstable parameters globally while taking advantage of autocompletion. Use crosstable_peek_options() to see which option is currently set and crosstable_reset_options() to set all options back to default.

Usage

crosstable_options(
  ...,
  remove_zero_percent = FALSE,
  only_round = FALSE,
  verbosity_autotesting = "default",
  verbosity_duplicate_cols = "default",
  fishertest_B = 1e+05,
  total,
  percent_pattern,
  margin,
  percent_digits,
  num_digits,
  showNA,
  label,
  funs,
  funs_arg,
  cor_method,
  drop_levels,
  unique_numeric,
  date_format,
  times,
  followup,
  test_args,
  effect_args,
  wrap_id = 70,
  compact_padding = 25,
  header_show_n_pattern = "{.col} (N={.n})",
  keep_id,
  by_header,
  autofit,
  compact,
  remove_header_keys,
  show_test_name,
  padding_v,
  header_show_n,
  fontsize_body,
  fontsize_subheaders,
  fontsize_header,
  generic_labels,
  units = "in",
  peek_docx = TRUE,
  font_code = "Consolas",
  add_max_cols = 25,
  gg_width,
  gg_height,
  format_legend_name,
  table_legend_par_before,
  table_legend_prefix,
  figure_legend_par_after,
  figure_legend_prefix,
  normal_squish,
  normal_font_size,
  title_squish,
  allow_break,
  section_title,
  section_title_level,
  section_sentence,
  style_normal,
  style_image,
  style_legend,
  style_heading,
  style_list_ordered,
  style_list_unordered,
  scientific_log,
  clean_names_fun,
  verbosity_na_cols,
  format_epsilon,
  .local = FALSE,
  reset = deprecated()
)

Arguments

...

unused

remove_zero_percent

set to TRUE so that proportions are not displayed if n==0

only_round

default argument for format_fixed()

verbosity_autotesting

one of default, quiet, or verbose

verbosity_duplicate_cols

one of default, quiet, or verbose.

fishertest_B

number of simulations to perform when fisher.test() is failing (FEXACT error 7).

total