-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.rmd
154 lines (115 loc) · 5.77 KB
/
README.rmd
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: "listdown"
output:
md_document:
variant: markdown_github
---
<!-- 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%"
)
```
# listdown
<!-- badges: start -->
[](https://cran.r-project.org/package=listdown)
[](https://github.com/kaneplusplus/listdown/actions)
[](https://codecov.io/gh/kaneplusplus/listdown?branch=master)
<!-- badges: end -->
## Overview
The {listdown} package provides functions to programmatically create R Markdown files from
named lists. It is intended for data analysis pipelines where the presentation of the results
is separated from their creation. For this use case, a data processing (or analysis) is performed
and the results are provided in a single named list, organized hierarchically. With the list and a {listdown} object a workflowr, pdf, word, or html page. List element names denote sections, subsections,
subsubsection, etc. and the list elements contain the data structure to be presented including
graphs and tables. The goal of the package is not to provide a finished, readable document. It is to provide a document with all tables and visualization that will appear (_computational_ components). This serves as a starting point from which a user can organize outputs, describe a study, discuss results, and provide conclusions (_narrative_ components).
{listdown} provides a reproducible means for producing a document with specified computational components. It is most compatible with data analysis pipelines where the data format is fixed but the analyses are either being updated, which may affect narrative components including the result discussion and conclusion, or where the experiment is different, which affects all narrative components If the narrative components are not changing with the data being pushed through your analysis pipeline, then you may be better off writing the R Markdown code manually.
## Installation
You can install the released version of listdown from [CRAN](https://CRAN.R-project.org) with:
``` r
install.packages("listdown")
```
The development version of {listdown} can be installed from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("kaneplusplus/listdown")
```
## Example
As a toy example, suppose we would like to create an html document plotting Anscombe's quartet with
each plot having it's own section. To construct the document, we will need to two objects. The first
is a presentation list, whose names indicate section (or subsection) titles and whose elements are
the objects to present. The second is a `listdown` object, which describes how the object should
be rendered in the document.
```{r eval = FALSE}
library(listdown)
library(ggplot2)
data(anscombe)
# Create the ggplot objects to display.
pres_list <- list(
Linear = ggplot(anscombe, aes(x = x1, y = y1)) + geom_point() + theme_bw(),
`Non Linear` = ggplot(anscombe, aes(x = x2, y = y2)) + geom_point() + theme_bw(),
`Outlier Vertical`= ggplot(anscombe, aes(x = x3, y = y3)) + geom_point() + theme_bw(),
`Outlier Horizontal` = ggplot(anscombe, aes(x = x4, y = y4)) + geom_point() + theme_bw())
# Save the pres_list object so that it can be used in the R Markdown document.
saveRDS(pres_list, "pres-list.rds")
# Create a listdown object.
ld <- listdown(load_cc_expr = readRDS("pres-list.rds"), # The expression to load pres_list.
package = "ggplot2") # The packages needed to render plots.
# Output an html document to a string.
doc <- c(
as.character(
ld_rmarkdown_header("Anscombe's Quartet",
author = "Francis Anscombe",
date = "1973")),
ld_make_chunks(ld))
cat(paste(doc, collapse = "\n"))
```
```{r eval = TRUE, echo = FALSE}
library(listdown)
library(ggplot2)
data(anscombe)
# Create the ggplot objects to display.
pres_list <- list(
Linear = ggplot(anscombe, aes(x = x1, y = y1)) + geom_point() + theme_bw(),
`Non Linear` = ggplot(anscombe, aes(x = x2, y = y2)) + geom_point() + theme_bw(),
`Outlier Vertical`= ggplot(anscombe, aes(x = x3, y = y3)) + geom_point() + theme_bw(),
`Outlier Horizontal` = ggplot(anscombe, aes(x = x4, y = y4)) + geom_point() + theme_bw())
# Save the pres_list object so that it can be used in the R Markdown document.
saveRDS(pres_list, "pres-list.rds")
# Create a listdown object.
ld <- listdown(load_cc_expr = readRDS("pres-list.rds"), # The expression to load pres_list.
package = "ggplot2") # The packges needed to render plots.
# Output an html document to a string.
doc <- c(
as.character(
ld_rmarkdown_header("Anscombe's Quartet",
author = "Francis Anscombe",
date = "1973")),
ld_make_chunks(ld))
cat(paste(doc, collapse = "\n"))
```
The document can then be written to a file, rendered, and viewed with the following code.
```{r message = FALSE, eval = FALSE}
library(rmarkdown)
writeLines(doc, file("anscombe.Rmd"))
render("anscombe.Rmd")
browseURL("anscombe.html")
```
```{r cleanup, echo = FALSE, warning = FALSE, error = FALSE}
unlink("pres-list.rds")
```
<!--
## Example
This is a basic example which shows you how to solve a common problem:
```{r example}
library(listdown)
## basic example code
```
-->
## Code of Conduct
Please note that the {listdown} project is released with a
[Contributor Code of Conduct](CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.