Building a Data Analysis Report in R
A data analysis report in R is a self-contained document that interleaves narrative text, R code, and its output — plots, tables, and inline computed values — so the reader sees exactly how each conclusion was produced rather than trusting a static slide export from an analysis nobody can re-run. R Markdown (and its successor Quarto) is the standard tool for this: you write plain Markdown for prose and fenced code chunks for R, and knitting the document executes every chunk fresh and weaves the results directly into the final HTML, PDF, or Word output.
Cricket analogy: An R Markdown report re-running every code chunk on knit is like a match referee re-checking every umpiring decision with fresh replay footage before the result is confirmed, rather than trusting a written scorecard someone typed up after the fact.
Setting Up an R Markdown / Quarto Report
An .Rmd or .qmd file begins with a YAML header specifying the title, author, date, and output format (html_document, pdf_document, word_document, or a Quarto equivalent), followed by the document body where prose is written in plain Markdown and R code lives in fenced chunks. Each chunk accepts options — echo = FALSE to hide code and show only output, fig.width and fig.height to control plot sizing, message = FALSE and warning = FALSE to suppress package startup noise — that give fine-grained control over what the final reader actually sees.
Cricket analogy: The YAML header setting output format (html_document vs pdf_document) is like a broadcaster choosing between a TV feed and a radio commentary feed from the same live match — same underlying game, different delivery format for the audience.
---
title: "Q2 Customer Churn Analysis"
author: "Data Team"
date: "2026-07-10"
output: html_document
---
## Summary
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE)
library(dplyr)
library(ggplot2)
churn <- read.csv("data/churn_q2.csv")
```
Churn this quarter was `r round(mean(churn$churned) * 100, 1)`%.
```{r churn-plot, fig.width=7, fig.height=4}
ggplot(churn, aes(x = plan_type, fill = factor(churned))) +
geom_bar(position = "fill") +
labs(y = "Proportion", fill = "Churned")
```Structuring the Analysis: Import, Clean, Explore
A well-structured analysis report follows a consistent narrative arc: an early chunk imports raw data with readr::read_csv() or similar and immediately checks its shape and types with glimpse() or str(), a cleaning section handles missing values, type coercion, and outlier flags explicitly rather than silently, and an exploratory section computes summary statistics and early visualizations before any modeling begins. Keeping these phases as distinct, labeled sections — not one giant undifferentiated chunk — means a reader (including future you) can jump straight to "where did this filtering happen?" without re-reading the entire script.
Cricket analogy: Structuring a report into import, clean, and explore phases is like a Test match's distinct sessions — morning session for openers settling in, the middle session for handling a testing spell, and the final session for building a scoring platform — each phase clearly demarcated on the scorecard.
Visualizations and Tables for Reporting
For narrative reports, ggplot2 remains the standard for figures because its layered syntax makes it easy to add clear titles, axis labels, and annotations that a plot needs when it's read by someone who wasn't in the room for the analysis, while packages like gt, kableExtra, or DT turn a plain data frame into a formatted, publication-ready table with sortable columns, conditional cell coloring, or captions. The most common mistake in report tables is dumping a raw print(df) into the document — a reader parsing 40 unlabeled columns of a base R print output learns far less than they would from three clearly labeled summary tables built with gt::gt().
Cricket analogy: A raw print(df) dump in a report is like handing someone an unedited ball-by-ball CSV instead of a formatted scorecard — gt::gt() is the equivalent of turning that raw feed into the clean scorecard broadcasters actually show on screen.
The gt package (built by the same team behind ggplot2's tidyverse conventions) lets you build a formatted table with the same layered-grammar philosophy as ggplot2: gt(df) |> tab_header() |> fmt_number() |> tab_style() — each function adds one piece of formatting, composed the same way geoms and themes compose in a ggplot2 chart.
Rendering, Parameterizing, and Sharing Reports
Beyond a single static report, R Markdown and Quarto support parameters — declared in the YAML header as params: region: "West" — that let the same .Rmd template generate a different report per region, per month, or per client by passing different parameter values to rmarkdown::render() or quarto::quarto_render(), which is how many organizations automate dozens of near-identical reports from one source file instead of copy-pasting a script 20 times. For sharing, knitting to html_document with self_contained: true embeds all images and CSS into a single portable HTML file, while pdf_document (via LaTeX/tinytex) produces a fixed, print-ready document better suited for formal or archival distribution.
Cricket analogy: Parameterized reports generating one output per region are like a broadcaster running the same match-report template for every venue on tour, swapping in the ground name and pitch conditions instead of writing a fresh report from scratch for each stop.
self_contained: true HTML reports and pdf_document output via tinytex can silently fail to render on a colleague's machine if they're missing a system dependency (a LaTeX package for PDF, or a font for HTML) — always test-render on a clean machine or CI runner before assuming a knit that works locally will work everywhere.
- R Markdown (.Rmd) and Quarto (.qmd) interleave prose, executable R code chunks, and their output into one reproducible document.
- A YAML header controls title, author, and output format (html_document, pdf_document, word_document); chunk options like echo and fig.width control what's shown.
- Structure the analysis into distinct, labeled import/clean/explore sections rather than one undifferentiated script.
- Use ggplot2 for annotated, reader-friendly figures and gt/kableExtra/DT for formatted tables instead of raw print(df) output.
- Parameters in the YAML header let one template generate many reports (per region, client, or month) via rmarkdown::render().
- html_document with self_contained: true produces a portable single-file report; pdf_document is better for formal, archival distribution.
- Always test-render reports on a clean machine or CI runner before assuming they'll knit successfully elsewhere.
Practice what you learned
1. What is the primary advantage of an R Markdown/Quarto report over a static slide export of analysis results?
2. Where is the output format (e.g., html_document, pdf_document) specified in an .Rmd file?
3. Which chunk option would you set to hide the R code itself while still showing its output (plots, tables) in the final report?
4. What problem does using gt::gt() or kableExtra to format a data frame solve, compared to a raw print(df) in a report?
5. What do parameters declared in an R Markdown/Quarto YAML header (params:) enable?
Was this page helpful?
You May Also Like
R Markdown Basics
Learn how to combine R code, output, and narrative text into reproducible documents, reports, and slides using R Markdown.
ggplot2 Basics
Learn ggplot2's grammar of graphics—aesthetics, geoms, facets, and themes—to build layered, publication-quality charts in R.
dplyr Basics
Learn the core dplyr verbs—filter, select, mutate, arrange, summarise, and group_by—for fast, readable data manipulation in R.
R Best Practices
Practical conventions for writing maintainable, reproducible R code: project structure, style, vectorization, and testing.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics