2 How to Use this Book

2.1 Setup

2.1.1 Install booktem

# install.packages("devtools")
devtools::install_github("debruine/booktem")

2.1.2 Quarto Options

The file _quarto.yml contains various options that you can set to change the format and look of your book.

2.1.2.1 Project Options

The project key defines the inputs and outputs for the book (quarto reference).

project key

project:
  type: book
  output-dir: docs
  resources: resources

The output-dir key defines the directory where the rendered web files will be saved. This is set to docs in order to be compatible with GitHub Pages, but you can change this if you are working with a different repository that expects the web files to be in a different directory.

The resources key specifies a directory that is copied verbatim to the output directory. This is where you should put, for example, data files that you want to make accessible online (sometimes they don’t automatically copy over when linked).

2.1.2.2 Book Options

The book key defines options that affect the look and function of the book (quarto reference).

book key

book:
  title: Book
  subtitle: ~
  author: ~
  doi: ~
  license: CC-BY 4.0
  description: ~
  cover-image: images/logos/logo.png
  image: images/logos/logo.png
  favicon: images/logos/logo.png
  cookie-consent: false
  google-analytics: ~
  page-navigation: true
  search: true
  # comments:
  #   hypothesis:
  #     theme: clean
  #     openSidebar: false
  downloads: ~
  sharing: ~
  sidebar:
    title: ~
    logo: ~
    search: true
    contents: ~
    style: floating
    background: ~
    foreground: ~
    border: true
    alignment: left
    collapse-level: 3
    pinned: true
    header: ""
    footer: ""
  margin-header: ~
  page-footer:
    left: ~
    right: ~
  chapters:
  - index.qmd
  - instructions.qmd
  appendices:
  - references.qmd

2.1.2.3 html Options

The format key defines options for specific formats, such as html or pdf. We’ll only be using html here (quarto reference).

format:html key

format:
  html:
    theme:
      light:
      - flatly
      - include/light.scss
      dark:
      - darkly
      - include/dark.scss
    css:
    - https://use.fontawesome.com/releases/v5.13.0/css/all.css
    - include/booktem.css
    - include/glossary.css
    - include/style.css
    df-print: kable
    code-link: true
    code-fold: false
    code-line-numbers: true
    code-overflow: wrap
    code-copy: hover
    highlight-style: a11y
    mainfont: ~
    monofont: ~
    include-after-body: [include/script.js]

2.1.3 Crossrefs

Section links must start with sec- and look like this: Section 2.1.5.

## Section Title {#sec-section-title}

Internal links look like this: @sec-section-title

Figure links must start with fig- and look like this: Figure 2.1.

Figure 2.1: A histogram of a Poisson distribution with lambda = 3

Table links must start with tbl- and look like this: Table 2.1.

Table 2.1: The authors of this book
first_name	last_name
Lisa	DeBruine
Daniël	Lakens

See the quarto documentation for more information.

2.1.4 References

Zotero export - keep updated

2.1.5 Snippets

Snippets in RStudio provide shortcuts to syntax. For example, in an RMarkdown document, type “r” and shift-tab to expand a code chunk.

You can add your own snippets. Under the Tools menu, choose Edit Code Snippets... and paste the following text into the end of the appropriate sections.

2.1.5.1 Markdown

snippet gls
    r glossary("${1:term}")
    
snippet gls2
    r glossary("${1:term}", "${2:display}")
    
snippet h1
    # ${1:title} {#sec-${2:ref}}
    
snippet h2
    ## ${1:title} {#sec-${2:ref}}
    
snippet h3
    ### ${1:title} {#sec-${2:ref}}
    
snippet h4
    #### ${1:title} {#sec-${2:ref}}
    
snippet h5
    ##### ${1:title} {#sec-${2:ref}}

2.1.6 Customize

2.2 Layout

2.2.1 Conventions

This book will use the following conventions:

Code: list(number = 1, letter = "A")
File paths: data/sales.csv
Menu/interface options: Tools > Global Options… > Pane Layout
R Packages: tidyverse
Glossary items: alphaThe threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.
Citations: Wickham et al. (2022)
Internal links: Section 2.2.1
External links: Mastering Shiny
Mac-specific: Cmd-Shift-F10
Windows-specific: Ctl-Shift-F10

A list of mac and windows keyboard shortcuts.

2.2.2 Figures

It is best practice to set a custom ggplot theme, then each subsequent plot will use that theme. You can put this code in R/my_setup.R after loading ggplot2.

Start with a built-in theme and then add any tweaks with the theme() function.

library(ggplot2)

my_theme <- theme_minimal(base_size = 16) + 
            theme(panel.background = element_rect(fill = "red", 
                                                  color = "black", 
                                                  size = 5),
                  panel.grid = element_blank())
theme_set(my_theme)

ggplot(midwest, aes(popdensity, percollege)) +
  geom_point(alpha = 0.5) +
  labs(x = "Population Density", y = "Percent College Educated")

Figure 2.2: Demographic information of midwest counties from 2000 US census

2.2.3 Tables

Shorter tables and PDFs print using kableExtra and longer tables in HTML format use DT for interactive paged tables.

head(beaver1)

Table 2.2: Shorter table
day	time	temp
346	840	36.33
346	850	36.34
346	900	36.35
346	910	36.42
346	920	36.55
346	930	36.69

#DT::datatable(beaver1)

?(caption)

2.2.4 Callout boxes

See the quarto reference for more options.]{.aside}

Note

.callout-note: Informational asides.

Click to expand

colapse = “true”: Expanded!

Tip

.callout-tip: Tips

Warning

.callout-warning: Notes to warn you about something.

Caution

.callout-caution: Notes about things that could cause serious errors.

Important

.callout-important: Notes about things that are important.

2.2.5 Code and Output

# code chunks
paste("Code", "Output", 1, sep = " ")

[1] "Code Output 1"

Filename or header

# code chunks with filename
a <- 1

```{r, fig.width = 2, fig.height = 2}

# code chunks with visible headers
hist(rnorm(100000))

```

## Markdown Example

* Inline code: `r nrow(iris)`
* *Italics*
* **Bold**
* [Linked text](https://psyteachr.github.io)

2.2.6 Fonts

2.3 Extras

2.3.1 Glossary

Books are set up with lightweight glossary functions from the glossary package.

# code in R/my_setup.R to initialise the glossary on each page
library(glossary)
glossary_path("include/glossary.yml")
glossary_popup("click") # "click", "hover" or "none"

Edit the file glossary.yml with your glossary terms like this:

alpha: |
  The threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.
p-value: |
  The probability of the observed data, or more extreme data, if the null hypothesis is true. The lower the p-value, the higher the test statistic, and less likely it is to observe the data if the null hypothesis is true.

Look up a term from the glossary file with glossary("alpha"): alphaThe threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.

Display a different value for the term with glossary("alpha", "$\\alpha$"): $\alpha$The threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.

Use an inline definition instead of the glossary file with glossary("beta", def = "The second letter of the Greek alphabet"): betaThe second letter of the Greek alphabet

Just show the definition with glossary("p-value", show = "def"): The probability of the observed data, or more extreme data, if the null hypothesis is true. The lower the p-value, the higher the test statistic, and less likely it is to observe the data if the null hypothesis is true.

Show the table of terms defined on this page with glossary_table():

term	definition
alpha	The threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.
beta	The second letter of the Greek alphabet
p-value	The probability of the observed data, or more extreme data, if the null hypothesis is true. The lower the p-value, the higher the test statistic, and less likely it is to observe the data if the null hypothesis is true.

2.3.2 FontAwesome

The fontAwesome quarto extension allows you to use the free icons with syntax like:

{{< fa dragon >}}
{{< fa brands github size = 5x title="(github logo)" >}}

To install it, just run this code in the Terminal pane of RStudio (not the Console pane).

quarto install extension quarto-ext/fontawesome

2.1 Setup

2.1.1 Install booktem

2.1.2 Quarto Options

2.1.2.1 Project Options

2.1.2.2 Book Options

2.1.2.3 html Options

2.1.3 Crossrefs

2.1.4 References

2.1.5 Snippets

2.1.5.1 Markdown

2.1.6 Customize

2.1.6.1 Page Footer

2.2 Layout

2.2.1 Conventions

2.2.2 Figures

2.2.3 Tables

2.2.4 Callout boxes

2.2.5 Code and Output

2.2.6 Fonts

2.3 Extras

2.3.1 Glossary

2.3.2 FontAwesome