-
Notifications
You must be signed in to change notification settings - Fork 6
/
report.qmd
315 lines (225 loc) · 12.7 KB
/
report.qmd
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
---
title: How to create an article for Real World Data Science
description: |
A template to help contributors style their articles and make use of different Quarto features.
categories:
- Resources
- for
- Contributors
author: Author1, Author2
date: last-modified
date-format: long
toc: true
format:
html:
theme: [lux, rwds.scss]
css: rwds.css
toc: true
grid:
sidebar-width: 0px
body-width: 1000px
margin-width: 250px
code-annotations: below
mermaid:
theme: neutral
bibliography: references.bib
csl: chicago.csl
execute:
eval: false
echo: true
messages: false
error: false
warning: false
nocite: '@*'
page-layout: article
title-block-banner: true
# citation: true
---
This is a template for writing Real World Data Science (RWDS) articles in [`Quarto`](https://quarto.org). Please insert graphs and tables as static objects, i.e. `.png` files or markdown tables, rather than generating them by code, as it otherwise takes too long to render the full RWDS website.
One idea for a workflow could be to write your analysis and text directly in the `report.qmd` file, execute your code cells in your local terminal, save figures into the images folder, and import them as files in the `report.qmd`.
<!-- TODO: What about creating the files once and freezing them? Is there a more elegant way? -->
For the content of your writing, make sure to check out the resources on [RWDS---Call for Contributions](https://realworlddatascience.net/contributor-docs/call-for-contributions.html).
## A main section about writing text
Notice how the headings and their hierarchy also show up in the table of contents on the right-hand side.
When writing, use **bold**, *italics*, and ~~strikethrough~~ text for emphasis, but use sparingly.
<!-- You can also write comments for yourself, which won't show up in the rendered documents. However, be aware that these comments will be displayed in the online source code in the RWDS repository, so don't share any secrets here! -->
In this subsection, we will show how to create lists and blockquotes:
1. First item
2. Second item
- Item A
- Item B
- Subitem B1
> You can make profound statements in a blockquote.
You can add a footnote to your writing.^[In case you want to give an extra reference or link to a source.]
By adding your references as BibTeX to the `references.bib` file in this repository, you not only maintain your references in the right citation style, but you can also cite directly, as recommended by @example-bibtexkey, or indirectly [see @example-bibtexkey].
By writing `---` you can add a horizontal line separator.
---
If your article includes tips on special keyboard shortcuts, you can typeset them like this: *To print, press* {{< kbd Shift-Ctrl-P >}}. *To open an existing new project, press* {{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}.
You can write equations in-line like this $y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \epsilon \text{, }$ or in a separate block like this:
$$
y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \epsilon \text{. }
$$ {#eq-first}
@eq-first is an example of a reference to an equation.
::: {.callout-note appearance="simple"}
For more information on **cross-references**, see the [Quarto documentation](https://quarto.org/docs/authoring/cross-references.html#equations).
:::
### Sub-section: Creating tables
Adding a table in markdown is easy, but can result in some formatting work. Consider using a tool like [tablesgenerator](https://www.tablesgenerator.com/markdown_tables), or the [Visual Editor if you are using R Studio](https://quarto.org/docs/visual-editor/).
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| A | B | C |
| D | E | F |
: Example table with a caption. {#tbl-example}
You can also reference great tables such as @tbl-example.
If needed, you can also add sub-tables:
::: {#tbl-panel layout-ncol=2}
| Col1 | Col2 | Col3 |
|------|------|------|
| A | B | C |
| E | F | G |
| A | G | G |
: First Table. {#tbl-first}
| Col1 | Col2 | Col3 |
|------|------|------|
| A | B | C |
| E | F | G |
| A | G | G |
: Second Table. {#tbl-second}
Main Caption.
:::
See @tbl-panel for details, especially @tbl-second.
::: {.callout-note appearance="simple"}
For more information on **tables**, see the [Quarto documentation](https://quarto.org/docs/authoring/tables.html#grid-tables).
:::
## Another main section: Writing code
Authoring technical articles may also include code chunks. You can add code chunks in `R` like this:
``` {r}
set_signif_par()
plot(1:4, 1:4, col=1:4, pch=19, cex=3, xlab="", ylab="",
main = "My Significance Plot",
sub = "Source: data source")
abline(h=1:4, v=1:4, col = "lightgrey")
```
We can write not only about `R`, but also about `Python`:
``` {python}
import pandas as pd
print("Hello this is Python code")
```
or `Julia` (and many other languages):^[To render documents with embedded `Julia` code, follow the [installation instructions](https://quarto.org/docs/computations/julia.html#installation) on the Quarto website.]
``` {{julia}}
using Plots
plot(sin,
x->sin(2x),
0,
2π,
leg=false,
fill=(0,:lavender))
```
If you want to show how to write a specific code chunk in `Quarto`, you can use the `echo: fenced` option to show the code in the output.
```{r}
#| echo: fenced
# This is a fenced code block with some R code
x <- 1:10
y <- x^2
plot(x, y)
```
If you want to reference specific lines of code, set `code-line-numbers: true`. Even better, take a look at how to do [interactive code annotations](https://quarto.org/docs/authoring/code-annotation.html#annotation-syntax), as these are also supported on Real World Data Science. You can see an example here (try clicking on the numbers for the highlighting):
```{r}
#| code-line-numbers: true
library(tidyverse)
library(palmerpenguins)
penguins |> # <1>
mutate( # <2>
bill_ratio = bill_depth_mm / bill_length_mm, # <2>
bill_area = bill_depth_mm * bill_length_mm # <2>
) # <2>
```
1. Take `penguins`, and then,
2. add new columns for the bill ratio and bill area.
## Figures and their layout
You can also add images:
and resize them:
{width=10%}
and reposition them:
{width=10% fig-align="center"}
You can make use of Quarto's options to arrange multiple images in a grid, and link to both URLs and local files. Also, you can add captions to images that contain links. Local images should be stored in the folder `images` and in `.png` format.
You can also cross-reference figures, such as @fig-layout, or subfigures like @fig-repo.
::: {#fig-layout layout="[1,1,1]"}
](https://images.unsplash.com/photo-1526628953301-3e589a6a8b74?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=2006&q=80){#fig-data}
](https://images.unsplash.com/photo-1538688273852-e29027c0c176?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=2070&q=80){#fig-laptop}
](images/repo_cover.png){#fig-repo}
Caption for the full figure.
:::
Sometimes, you might want to add an image, graph, equation, table, or simple text in the margin of the page, to further substantiate a claim that you make. Here we put the RWDS logo in the margin.
::: {.column-margin}
:::
::: {.callout-note appearance="simple"}
For more information on figures, see the [Quarto documentation](https://quarto.org/docs/authoring/figures.html).
:::
## Creating diagrams
Rather than creating diagrams in Canva, Figma, or PowerPoint and pasting them into your article as an image, consider using [Mermaid](https://mermaid-js.github.io/mermaid/#/). Note how the chunk options for Mermaid start with `%%|` and that you need to set the option `eval: true` and `echo: false` to only generate your graph and not the code that created it. @fig-mermaid is an example of a reference to a diagram.
```{mermaid}
%%| eval: true
%%| echo: false
%%| fig-align: center
%%| fig-cap: "This is a caption for the diagram."
%%| label: fig-mermaid
flowchart LR
A[Hard edge] --> B(Round edge)
B --> C{Decision}
C --> D[Result one]
C --> E[Result two]
```
::: {.callout-note appearance="simple"}
For more information on diagrams, see the [Quarto documentation](https://quarto.org/docs/authoring/diagrams.html).
:::
## Interactive elements
### Shiny
We welcome the inclusion of interactive elements such as Shiny apps in RWDS articles. So far, the easiest way to implement these apps is to host them on your own and embed them in this article as an HTML iframe object.
One example workflow could be:
1. Create a Shiny app and host it on your server, e.g. on [shinyapps.io](https://www.shinyapps.io/) (free option).
2. You can then embed the app in your article as an [HTML iframe](https://support.posit.co/hc/en-us/articles/217592607-Can-I-embed-iframe-Shiny-apps-in-other-websites-from-RStudio-Connect-).
The iframe could look like this (replace `www.your_shiny_dashboard` with the URL of your app):
```{html}
<iframe src="www.your_shiny_dashboard" style="border: none; width: 100%; height: 500px" frameborder="0"></iframe>
```
Paste this code directly into your `.qmd` file to implement the HTML iframe.
You can find an example in the RWDS article, [Using 'basket complementarity' to make product recommendations](https://realworlddatascience.net/ideas/datasciencebites/posts/2023/03/02/basket-complementarity.html).
### webR
The webR Quarto extension, from [James Balamuta](https://thecoatlessprofessor.com/about/), is very exciting. As Balamuta describes, webR is "designed to empower you to run R code directly in your web browser using familiar reporting tools, all without the need for an external R server."
Visit the [quarto-webr website](https://quarto-webr.thecoatlessprofessor.com/) for details on how to make full use of this capability. And check out [a simple working example](https://realworlddatascience.net/viewpoints/editors-blog/posts/2023/09/19/positconf-blog.html#dynamic-interactions-empowering-educators-and-researchers-with-interactive-quarto-documents-using-webr) on RWDS.
## Some icing on the cake
You can add a warning to your writing like this:
::: {.callout-warning appearance="simple"}
This is a warning!
:::
If your remark is too benign for a warning, but still valuable information for the reader, consider a note:
::: {.callout-note appearance="simple"}
Want to hear more from the RSS Data Science and AI Section? Sign up for its newsletter at [rssdsaisection.substack.com](https://rssdsaisection.substack.com/).
:::
To add more media to your article, consider embedding a video:
{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}
<!-- TODO: This leads to weird formatting of the rest of the article. Also: How does this work when hosted? -->
<!-- https://quarto.org/docs/interactive/shiny/ -->
::: {.article-btn}
[Back to section homepage](url)
:::
::: {.further-info}
::: grid
::: {.g-col-12 .g-col-md-12}
About the author
: Author 1 is... and Author 2 is...
:::
::: {.g-col-12 .g-col-md-6}
Copyright and licence
: © 2023 Author 1 and Author 2
<a href="http://creativecommons.org/licenses/by/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;"> <img style="height:22px!important;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1"></a> This article is licensed under a Creative Commons Attribution 4.0 (CC BY 4.0) <a href="http://creativecommons.org/licenses/by/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;"> International licence</a>. Thumbnail photo credit and licence goes here.
:::
::: {.g-col-12 .g-col-md-6}
How to cite
: 1, Author, and Author 2. 2023. "How to create an article for Real World Data Science." Real World Data Science, Month Day, Year. [URL](url)
:::
:::
:::