projectable/README.Rmd at master · socialresearchcentre/projectable · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

```

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![R-CMD-check](https://github.com/socialresearchcentre/projectable/workflows/R-CMD-check/badge.svg)](https://github.com/socialresearchcentre/projectable/actions)
<!-- badges: end -->

# projectable <a href='https://github.com/socialresearchcentre/projectable'><img src='man/figures/projectable_hex.png' align="right" height="120" /></a>

Producing output tables is an exceedingly manual activity, particularly when
tabling complex statistics with associated metadata. When preparing large
numbers of tables for presentation or publication, providing different views of
the same result set can require large amounts of re-processing and fiddly manual
combination and reshaping of outputs.

Inspired by the `gt` R package (https://gt.rstudio.com/), `projectable` is
designed to easily support flexible specification and table manipulation. The
`projectable` approach treats a table as a collection of calculations with
accompanying metadata rather than simple values. It aims to support easily
moving from specification to data production to presentation of results by
treating an output table as a “projection” of complex results.

## Installation

You can install the unreleased version of projectable from
[GitHub](https://github.com/) with:

``` r
devtools::install_github("socialresearchcentre/projectable")
```

## Usage

The `projectable` package implements a set of interlocking functions which are
designed to ingest a simple dataframe, perform calculations upon it to
generate a metadata-rich table like object, and reshape that object back into
a 'flat' dataframe to be formatted using `gt` or `flextable`.


```{r my_tbl, include = TRUE, message = FALSE, warning = FALSE}
library(projectable)
library(dplyr)
library(gt)
library(flextable)

my_tbl <- mtcars %>%
  # Create metadata-rich summary table according to a column and row specification
  prj_tbl_rows(
    Cylinders = cyl,
    Transmission = list(Automatic = am %in% 0, Manual = am %in% 1),
  ) %>%
  prj_tbl_cols(
    `V-Shaped` = col_freq(n = vs %in% 1, N = vs %in% 0:1),
    `Not V-shaped` = col_freq(n = vs %in% 0, N = vs %in% 0:1)
  ) %>%
  prj_tbl_summarise() %>%
  # Tag columns to display
  prj_shadow(everything(), .shadow = c(Frequency = "{signif(p, 2)} ({n})", Sample = "{N}"))


my_gt <- my_tbl %>%
  # Pass through to `gt` for formatting
  prj_gt() %>%
  gt::tab_header(title = "Engine Shape vs Other Vehicle Characteristics") %>%
  gt::tab_stubhead(label = "Vehicle Characteristics") %>%
  gt::tab_options(
    heading.background.color = "#080808",
    row_group.background.color = "#f0f0f0"
  )
```

```{r out.width = "75%", echo = FALSE, fig.align = "center"}
if (pkgdown::in_pkgdown()) {
  # For website
  my_tbl
} else {
  # For GitHub
  knitr::include_graphics("man/figures/README-my_gt.png")
}
```

```{r}
my_flex <- my_tbl %>%
  # Pass through to `flextable` for formatting
  prj_flex() %>%
  flextable::theme_tron_legacy() %>%
  flextable::add_header_lines("Engine Shape vs Other Vehicle Characteristics")
```
```{r out.width = "75%", echo = FALSE, fig.align = "center"}
knitr::include_graphics("man/figures/README-my_flex.png")
```