Level Up 01: Reporting with Papaja

# Level Up 01: Reporting with Papaja

---

# SeminRs

- Informal, optional weekly sessions to help build a 'portfolio of skills'

- 1-2 hours of instruction, demos, walk throughs & activities to try out

### *Essentials*

- Focused on the fundRmental skills to help you get started with learning R  
- Covering: basic wrangling & visualising data, '.bold.pink[pretty]' R Markdown, inline code, debugging...

### *Level Up*

- Focused on more advanced programming skills & applying these skills to new .bold.orange[fun] topics  
- Covering: Papaja, advanced wrangling & manipulation of data, '.bold.italic.pink[even prettier]' R Markdown, spotifyR...

<br>

*Session topics are not fixed - use the Padlet linked on Canvas for suggestions!*

---
class: inverse

# Suggested Workflow

- Create an R project file for all seminR sessions

- Within this directory, create an r_docs & data folder

- Save all Rmds and datasets to these folders respectively

<br>

File > New Project... New Directory > New Project > *Give your project a name & location*

<br>

- Make a cheat sheet of useful functions and .orange[#] comment their meaning and usage as you go through seminRs, practicals, tutorials etc.

---

# Session Objectives

### Reporting with Papaja

- Intro into Papaja for reporting

- Guided Papaja install

- Useful Papaja functions & tools

- Referencing with Papaja, citr, & BibTeX

- Tips & Tricks

---

class: inverse
 
# Papaja: .orange[P]reparing .orange[APA] .orange[J]ournal .orange[A]rticles

.pull-left[
- R package created by Frederik Aust & Marius Barth for producing APA style papers/reports

- R Markdown template

- Renders to pdf or Word doc

- Combine your analyses & write-up in a nicely formatted APA-style document

- Under active development

]

]
---

- Replication crisis

- Good for reproducibility & open science

- Anyone with the data & scripts can reproduce your results

- Saves time on formatting in line with APA guidelines

- Automatic reporting & updating of results

- Contains useful functions & tools for formatting tables, statistical test results  & references

---

# Guided Install

R (2.11.1 or later) and RStudio (1.1.453 or later), to check run `sessionInfo()` & go to `Help > About RStudio` 
  
.bold[Installing TinyTeX]

- Needed for rendering Word & pdf docs

```r
if(!"tinytex" %in% rownames(installed.packages())) install.packages("tinytex")

tinytex::install_tinytex()
```

```r
if(!"devtools" %in% rownames(installed.packages())) install.packages("devtools")

devtools::install_github("crsh/papaja")
```

---

# Usage

*File > New File > R Markdown... >  From Template > APA article*

<br>

Very similar to standard R Markdown files

3 main components:

1. YAML for document meta data
1. Markdown for your main write-up
1. Code chunks for R code
]

]

---

# YAML Options

First part contains meta data needed for journal submissions

- Can delete out any irrelevant options (i.e., author role, address, affiliation etc. for assignments)

- Edit info as you would in a normal Rmd

The second part of the YAML contains additional options, 3 of which you'll most likely want to change:

]

]

---

# Useful Functions & Tools

This:

]

Renders as:

]

This code:

```r
out <- apa_print(
  t.test(yield ~ N, data = npk)
)
```

& This inline code:

]

Produces this output:

Renders as:

]

.orange[apa_table()] to report the statistical tests in an APA style table (apa_table() extends knitr::kable())

Example code:

```r
# for ready made tables

table %>% 
  dplyr::select(Effect, Estimate, ci, StdEst, p) %>% 
  apa_table(., caption = "Model parameters for predictors of the intercept of maths attainment (at age 11).",  
          col.names = c("Predictor", "$b$", "95\\% CI", "$\\beta$", "$p$"),
          escape = FALSE,
          digits = 3,
          note = "$\\beta$ is the standardized parameter estimate."
          )
```

]

Example output:

]]

.orange[apa_table()] to report the statistical tests in an APA style table (apa_table extends knitr::kable())

Example code:

```r
# for raw results from tests

apa_lm <- apa_print(lm_out) # creates table element you can subset using $

apa_table(
  apa_lm$table, 
  caption = "A full regression table."
  )
```

]

Example output:

]

This:

```r
plot <- ggplot2::ggplot(peng_data, aes(species, flipper_length_mm))
plot +
  stat_summary(fun = "mean", geom = "point", size = 4, position = position_dodge(width = 0.3)) +  
  labs(x = "Species", y = "Flipper Length (mm)") +
  coord_cartesian(ylim = c(0, 250)) +
scale_y_continuous(breaks = seq(0, 250, 50)) +
* theme_apa()
```

]

Becomes:

]

.orange[cite_r] is a function in papaja for citing R packages, the code needed to generate them is provided in the template under the data analysis section, all you need to do is load your packages & they'll be added to the r-references.bib file automatically & included in the reference list

]

]]]]]]
---

# Bibliographies & .bib files

BibTeX files (.bib) are a text based file format for bibliography items (i.e., articles, books, URLs)

You can create them by creating a plain text file and saving it with a .bib file extension

]

Give the name of your .bib file in the YAML & add your references as you go

The Google Scholar Button for chrome is an easy way to get BibTeX references, but double check these are correct & complete

---

# How to cite

- Using the names of references in your .bib file that you've specified in the YAML:

bibliography: ["your_bib_file.bib", "r-references.bib"]

- Cite following these examples<sup>*</sup>:

]

.footnote[[*] [Examples taken from the papaja manual](http://frederikaust.com/papaja_man/writing.html#citations])

---

# Tips & Tricks

- Make sure your references are correct as you go - don't leave it until you have 100 references to check the page numbers of

- Errors can be difficult to solve, knit your Rmd often & get help as early as possible if you're stuck

- No duplicate chunk labels allowed - this will cause an error

- Don't install packages in your code chunks - use the console

- By default, papaja sets global chunk options to echo = F (code is run but hidden) & messages = F, sometimes you might want to set warnings = F too

- papaja reports all numeric values written using inline code to 2 dp by default

- To report equations, enclose in .orange[$]

- References of '.orange[???]' highlight errors, check it exists in your .bib file & check your spelling in your Rmd

---