10  Wrapping up

Intended Learning Outcomes

• Write effective methodological explanations for data analysis decisions
• Apply good practice for code quality and commenting
• Use a checklist to verify that data are understood and a reproducible report is complete and functional
• Be aware of ways to continue developing data skills beyond this course

10.1 Writing about data

Any time you produce a data report — whether for a university course, a workplace, or a research project — you will need to write about what you did and why. These methodological explanations are not about narrating your code line-by-line. They are about explaining the analytical decisions you made and why they matter for interpretation. The reader of your report may not know R, but they still need to understand and trust your results.

10.1.1 Focus on decisions, not code

A common mistake is to describe what the code does rather than what analytical decisions were made and why. The reader of your report should not need to understand R to follow your explanation.

Warning

Poor example:

“I used filter() to remove rows where age was NA, then I used group_by() and summarise() to calculate the mean score for each condition, and then I used ggplot() with geom_boxplot() to make a box plot.”

Better example:

“Participants with missing age data were excluded (n = 12), leaving a final sample of 340. Mean scores were calculated for each experimental condition. A box plot was used to compare condition scores as it allows clear visual comparison of the distributions across a small number of discrete groups.”

The poor example tells the reader which functions were used but nothing about why any of those decisions were made. The better example explains the decisions (what was excluded and why, what was calculated, and why a particular visualisation was chosen) without mentioning any code at all.

10.1.2 What to include in a methodological explanation

For each insight in your report, your explanation should briefly cover whichever of the following are relevant:

• Filters and inclusion criteria — What data did you include or exclude, and why? How many observations were affected?
• Missing data — How did you handle missing values? Were they removed, and if so, from which variables and how many?
• Summary measures — What did you calculate (e.g., means, counts, proportions)? If you report percentages, what is the denominator?
• Choice of table or figure — Why did you choose to present the data the way you did? What does this format make it easy to see?
• Joins — If you combined datasets, what did you join on and how did you verify the result was sensible?

You don’t need to cover all of these for every insight, only those that are relevant. The goal is to give the reader enough information to understand and trust your results without reading the code.

Knowledge check: Writing about data

Which of the following is the best methodological explanation for a figure showing average life satisfaction scores by country?

I made a bar chart of life satisfaction by country.I used group_by(country) and summarise(mean_score = mean(life_satisfaction)) to calculate the means, then made a bar chart with ggplot.Mean life satisfaction scores were calculated for each country. Countries with fewer than 30 respondents were excluded to avoid unreliable estimates (n = 3 countries removed). A bar chart was chosen to allow direct comparison across the 12 remaining countries.The data was grouped and summarised. Missing values were removed using drop_na(). The results are shown in Figure 1.

Tip

Which of the following is the best methodological explanation for a table showing the number of respondents by age group?

The age column was recoded with case_when() into four groups, then I used count() and kable() to display the results.Respondents were grouped into four age categories (18–24, 25–34, 35–44, 45+). A frequency table was used to show the distribution of respondents across groups, as the primary goal was to summarise the sample composition rather than compare a continuous measure.Table 1 shows respondents by age group. The data was wrangled and displayed using tidyverse.I used count() to count the number of respondents in each age group and then displayed it as a table.

10.2 Code quality and commenting

Good code is not just code that works, it is code that someone else (or future you) can read and understand. If you come back to a project after six months, or if a colleague needs to check your work, clear and well-commented code will save everyone a lot of time.

10.2.1 Comments should explain “why”, not “what”

Your code comments should give insight into your reasoning, not describe what R is doing. The code itself already tells the reader what it does; what it cannot tell them is why you made a particular decision.

Warning

Poor commenting:

# filter the data
dat_filtered <- dat |>
  filter(age >= 18) # keep rows where age is 18 or above

# group by condition and calculate the mean
dat_summary <- dat_filtered |>
  group_by(condition) |>
  summarise(mean_score = mean(score, na.rm = TRUE))

Better commenting:

# exclude participants under 18 as the survey targeted adults only
dat_filtered <- dat |>
  filter(age >= 18)

# compare mean scores across conditions, removing 4 missing values
dat_summary <- dat_filtered |>
  group_by(condition) |>
  summarise(mean_score = mean(score, na.rm = TRUE))

In the poor example, the comments simply restate what the code does. In the better example, the comments explain the rationale, why under-18s were removed, and that there were missing values that needed handling.

10.2.2 Keep your code readable

Beyond comments, there are a few simple things you can do to make your code easier to read:

• Use line breaks in pipes — Put each step of a pipeline on its own line. This is much easier to read than one very long line.
• Don’t put everything in one chunk — Break your code into logical sections. Each chunk should do one thing (e.g., load data, wrangle data, create a plot).
• Use meaningful object names — dat_filtered is more informative than d2 or x.
• Be consistent — Pick a naming convention and stick with it. The tidyverse convention is snake_case (e.g., mean_score, dat_filtered).

Knowledge check: Code commenting

Which of the following is the best code comment for the line dat <- dat |> drop_na(score)?

# remove 6 participants with missing scores (incomplete survey responses)# data cleaning step 3# drop NAs# use drop_na to remove NAs from score

10.3 Reproducible report checklist

Whenever you produce a report using R and Quarto, it is worth working through a checklist before you consider it finished. Many of these points may seem obvious, but they are the most common sources of errors and broken renders.

10.3.1 Know your data

Before you write a single line of analysis code, make sure you understand the data you are working with.

• Open and inspect the data — Use glimpse(), head(), or View() to look at the structure. How many rows and columns are there? What does each row represent?
• Understand the variables — What does each column contain? What are the units of measurement? Are categorical variables stored as characters or factors? Check any accompanying documentation or codebook.
• Check for missing data — Use e.g., summary() to see which columns have missing values and how many. Decide how you will handle them before you start your analysis, not halfway through.
• Check for unexpected values — Are there values that don’t make sense, like negative ages or dates in the future? Use count() on categorical variables to check for typos or inconsistent labels (e.g., “Male”, “male”, “M”).
• Understand how datasets relate — If you have multiple data files, identify the common variables that link them. Check whether the key variables match across files (e.g., are there IDs in one file that don’t appear in the other?).

10.3.2 Reproducibility

• Restart R and run all chunks in order — Restart R then Run > Run All (or use the Render button). If you have been running chunks out of order during development, your report may rely on objects that exist in your environment but not in the script. This is the single most common reason reports fail to render.
• Use relative file paths — Use paths relative to your project folder (e.g., read_csv("data/myfile.csv")) rather than absolute paths (e.g., read_csv("C:/Users/me/Documents/data/myfile.csv")). Absolute paths will not work on anyone else’s computer.
• Do not manually edit the data files — All data cleaning must be done in code. If you have opened the data in Excel and made changes, your report is not reproducible.
• Load all packages at the top — Put all your library() calls in the setup chunk at the start of your document. This makes it immediately clear what your report depends on.

10.3.3 Content and presentation

• Use inline code for all numbers in the text — Every number reported in the narrative should be produced using inline R code, not typed out. This ensures that if the data change, the numbers update automatically.
• Label tables and figures clearly — Do your tables have informative column names? Do your figures have appropriate axis labels, titles, or captions? Could a reader understand them without reading the code?
• Control code visibility — Use echo: false in chunks where the code is not needed in the rendered output. The reader of a report usually wants to see results, not the code that produced them.
• Check the rendered output — Open the rendered HTML (or PDF) and read it as a reader would. Does the narrative flow? Are figures and tables appearing where you expect?

Knowledge check: Reproducibility and data checking

Why is it important to restart R and run all chunks in order before rendering your report?

It is faster than rendering the document directly.It clears the console so the report looks tidy.It checks that your script does not depend on objects that only exist because you ran chunks out of order during development.It ensures your packages are up to date.

What is wrong with the following file path in a Quarto report: read_csv("C:/Users/emily/Desktop/ADS/data/survey.csv")?

The file extension should be .xlsx, not .csv.The folder name 'ADS' should be in lowercase.You should use read.csv() instead of read_csv().It uses an absolute file path which will not work on another computer, making the report non-reproducible.

True or false: it is acceptable to open your data file in Excel and fix a typo before loading it into R, as long as you note the change in a comment. TRUE FALSE

You load a dataset and run count(dat, gender) and see the values “Female”, “female”, “F”, and “Male”. What is the most likely problem?

The gender column should be numeric, not character.There are inconsistent labels that need to be recoded before analysis.The count() function is not appropriate for character variables.The data has too many columns.

Which of the following is the best first step when you receive a new dataset?

Run a statistical test to check for significant differences.Start writing ggplot code to visualise the main variables.Inspect the structure of the data using functions like glimpse(), summary(), or head() to understand what each variable contains.Immediately filter out any rows with missing data using drop_na().

10.4 Extending your skills

This book and course are only intended to get you started with the skills you will need to begin your journey into data skills. Below are some suggestions for where you might go next.

10.4.1 More plots

Appendix H will introduce you to some more plot styles, like maps and word clouds, and things you can do with plots, such as add annotations.

Lisa participated in the 2022 30 Day Chart Challenge and ended up collecting all 30 plots in a tutorial book with step-by-step explanations of how they created them.

Figure 10.1: An example map plot with annotations

10.4.2 Websites and presentations with Quarto

We’ve been concentrating on creating single documents with Quarto, but you can do much more with it, such as create presentations and websites. See the Quarto guide for a list of everything that it can do.

Appendix A will teach you how to create a simple webpage using quarto, link multiple pages, and style your content using css.

You can easily create presentations using revealjs in Quarto. Get started by creating a new Quarto document, pasting in the following, and rendering it.

---
title: "Presentation Title"
author: "Your Name"
format: revealjs
---

## Slide 1 Title

- Bullet Point 1
- Bullet Point 2

## Slide 2 Title

. . .

- Bullet Point 1

. . .

- Bullet Point 2

Check the revealjs Quarto docs for many more things you can do with presentations.

10.5 Glossary

term	definition
css	Cascading Style Sheet: A system for controlling the visual presentation of HTML in web pages.
quarto	An open-source scientific and technical publishing system.

10.6 Further resources

• Quarto guide
• R for Data Science (2e) — a comprehensive free textbook covering data import, tidying, transformation, visualisation, and communication
• ggplot2: Elegant Graphics for Data Analysis — the definitive guide to ggplot2
• Data transformation cheat sheet
• Data visualisation cheat sheet