未记录事实核验 · 状态：维护中

记录仅说明核验时间与维护状态，不保证适用于所有环境；使用前请留意正文中的版本、适用条件与风险提示。

warning 适用边界与维护说明

本文适合已有R与数据整理基础的读者学习输出控制、参数化批量报告及流水线组织，不是开箱即用的完整项目；本次仅作全文结构审阅，未执行代码或进行外部事实核验。运行示例需自行提供sales_data及city、sales、month等字段，明确时间粒度与金额单位，并由模板加载或接收数据；report_month仅作展示标签，不筛选月份，模拟增长率不代表真实同比。缓存建模与targets片段是结构示意，仍需补齐数据、建模对象、业务函数和报告模板；命令行示例仅展示流水线执行，定时调度须另行配置。Quarto跨语言示例需配置knitr/reticulate环境并将R片段写成可执行代码块，不能默认在Jupyter环境共享对象。自动更新仅限成功重新渲染时实际执行并被文档引用的结果，手写结论与缓存仍需检查；待创建的targets延伸文档不影响本文现有示例的参考用途。

R Markdown与数据报告自动化

abstract 学习目标

理解R Markdown的工作原理（knitr + pandoc流水线）
掌握代码块参数控制报告输出的核心技巧
能够使用参数化报告一个模板生成多份报告
了解Quarto的新特性及其与R Markdown的关系

quote 核心洞察

R Markdown的本质是"可执行的文档"——文档里的代码会真正运行，结果会自动嵌入文档。这意味着成功重新渲染时，执行代码产生并被文档引用的结果可以自动更新；手写正文仍需检查，缓存配置、输入变化和渲染失败也可能造成内容不同步。这是数据驱动报告的正确工作方式。

一、R Markdown的工作原理

.Rmd文件 (R代码 + Markdown文本)
    ↓ knitr
.md文件 (纯Markdown + 代码输出结果)
    ↓ pandoc
输出文件 (HTML / PDF / Word / PPT)

这个两步流程意味着：

knitr 负责执行代码、捕获输出（图表/表格/文字）
pandoc 负责格式转换，支持几十种输出格式

只需改一行output:配置，同一份.Rmd文件可以输出为HTML网页、PDF报告、Word文档，甚至PPT幻灯片。

二、文档结构与YAML配置

一个完整的R Markdown文档由三部分构成：

---
title: "2024年Q4销售分析报告"
author: "数据分析团队"
date: "`r Sys.Date()`"     # 动态日期，每次渲染自动更新
output:
  html_document:
    toc: true              # 自动生成目录
    toc_float: true        # 目录悬浮在侧边
    toc_depth: 3           # 目录显示到三级标题
    number_sections: true  # 章节自动编号
    code_folding: show     # 代码块默认展开（show/hide/none）
    theme: flatly          # Bootstrap主题
    highlight: tango       # 代码高亮风格
---

常用输出格式配置：

# PDF报告（需要LaTeX环境）
output:
  pdf_document:
    latex_engine: xelatex  # 中文PDF的常用选择，仍需配置可用的中文字体；并非唯一方案
    toc: true
    number_sections: true

# Word文档（便于领导批注）
output:
  word_document:
    reference_docx: template.docx  # 用公司Word模板

# PPT幻灯片
output:
  powerpoint_presentation:
    reference_doc: template.pptx

# 多格式同时输出
output:
  html_document: default
  pdf_document:
    latex_engine: xelatex

三、代码块参数：控制输出的精细手术刀

代码块的格式是：```{r chunk-name, option1=value, option2=value}

3.1 核心参数速查

参数	默认值	作用
`echo`	TRUE	是否在报告中显示代码
`eval`	TRUE	是否执行这段代码
`results`	"markup"	文字输出显示方式（"hide"=不显示）
`include`	TRUE	FALSE=代码执行但结果和代码均不显示
`warning`	TRUE	是否显示警告信息
`message`	TRUE	是否显示提示信息（如包加载提示）
`error`	TRUE	knitr默认将错误写入输出并继续；R Markdown渲染通常将其设为FALSE，遇错停止
`cache`	FALSE	是否缓存计算结果（耗时操作必备）
`fig.width`	7	图片宽度（英寸）
`fig.height`	7	图片高度（英寸，可由全局或代码块设置覆盖）
`fig.cap`	NULL	图片标题
`out.width`	NULL	输出宽度（"80%"、"500px"）
`dpi`	72	图片分辨率（打印用300）

3.2 实际使用场景

场景1：加载包时不显示任何信息

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = FALSE,       # 全局设置：不显示代码
  message = FALSE,    # 不显示提示信息
  warning = FALSE,    # 不显示警告
  fig.width = 8,
  fig.height = 5,
  dpi = 150
)
library(tidyverse)
library(knitr)
library(kableExtra)
```

场景2：展示代码但不运行（教学文档）

```{r demo, eval=FALSE, echo=TRUE}
# 这段代码会显示在报告中，但不执行
model <- lm(y ~ x, data = df)
```

场景3：耗时计算缓存结果

```{r expensive-model, cache=TRUE, cache.extra=file.mtime("data/raw.csv")}
# 第一次运行需要10分钟；后续运行直接读缓存
# cache.extra确保数据文件更新时重新计算
big_model <- train(y ~ ., data = big_data, method = "rf", ...)
```

四、优质表格输出

library(knitr)
library(kableExtra)

# 基础kable表格
summary_table <- sales_data %>%
  group_by(city) %>%
  summarise(
    平均销售额 = round(mean(sales), 1),
    销售总额   = sum(sales),
    模拟增长率 = scales::percent(runif(1, -0.1, 0.3))  # 随机演示值，非真实同比
  )

# kableExtra美化
summary_table %>%
  kable(
    caption = "表1：各城市销售汇总",
    col.names = c("城市", "平均销售额", "销售总额", "模拟增长率"),
    align = c("l", "r", "r", "r"),
    format.args = list(big.mark = ",")  # 千位分隔符
  ) %>%
  kable_styling(
    bootstrap_options = c("striped", "hover", "condensed"),
    full_width = FALSE,
    position = "left"
  ) %>%
  row_spec(which(summary_table$city == "上海"), bold = TRUE, color = "#E91E63") %>%
  add_header_above(c(" " = 1, "销售数据" = 3)) %>%
  footnote(general = "示例表格：增长率为随机演示值；数据来源及统计区间须按实际输入注明")

五、参数化报告：一个模板生成N份报告

这是R Markdown最强大的功能之一。在YAML中定义参数，脚本批量渲染不同参数的报告。

模板文件 city_report_template.Rmd：

---
title: "`r params$city` 城市月度销售报告"
date: "`r params$report_month`"
output: html_document
params:
  city: "北京"                    # 默认值
  report_month: "2024-12"
  min_sales_threshold: 50
---

在文档主体中使用参数：

```{r load-data, include=FALSE}
# 根据参数过滤数据
city_data <- sales_data %>%
  filter(city == params$city,
         sales >= params$min_sales_threshold)

avg_sales <- mean(city_data$sales)
```

## `r params$city` `r params$report_month` 销售情况

当前输入数据中，**`r params$city`** 满足销售额阈值的记录共有 **`r nrow(city_data)`** 条，
平均销售额为 **`r round(avg_sales, 1)`**，单位以输入数据定义为准；本示例尚未按报告月份过滤数据。

```{r trend-chart, fig.cap=paste0(params$city, "月度趋势")}
ggplot(city_data, aes(x = month, y = sales)) +
  geom_line(color = "#2196F3") +
  labs(title = paste0(params$city, " 销售趋势")) +
  theme_minimal()
```

批量渲染脚本：

library(rmarkdown)
library(purrr)

# 为每个城市生成一份报告
cities <- c("北京", "上海", "广州", "深圳", "杭州")

walk(cities, function(city) {
  render(
    input  = "city_report_template.Rmd",
    output_file = paste0("reports/", city, "_2024-12.html"),
    params = list(
      city = city,
      report_month = "2024-12",
      min_sales_threshold = 50
    ),
    quiet = TRUE  # 不在控制台打印渲染日志
  )
  cat("已生成：", city, "报告\n")
})

一次性生成5座城市的报告，取代每月手动修改Excel的重复劳动。

六、Quarto：R Markdown的进化版

Quarto是Posit（原RStudio公司）2022年推出的下一代科学发布系统，可视为R Markdown的官方继承者。

主要改进：

特性	R Markdown	Quarto
支持语言	主要R，可用reticulate跑Python	原生支持R/Python/Julia/Observable JS
配置方式	YAML header + 代码块参数混用	统一的YAML配置，更一致
输出格式	丰富	更丰富，新增Manuscript/Website
协作功能	有限	内置Freeze机制（不同语言执行结果可冻结）
工具支持	RStudio为主	VS Code/RStudio/JupyterLab均一流支持

Quarto文档示例（.qmd文件）：

---
title: "季度分析报告"
format:
  html:
    toc: true
    code-fold: true        # 代码默认折叠
    code-tools: true       # 右上角显示代码查看按钮
  pdf:
    latex-engine: xelatex
execute:
  echo: false
  warning: false
  cache: true
---

# Quarto原生支持Python代码块
import pandas as pd
df = pd.read_csv("data.csv")
print(df.describe())

# 使用reticulate执行引擎且Python代码已在同一会话执行时，R可访问Python对象
library(reticulate)
r_df <- py$df  # 访问Python中的df变量

迁移建议：新项目直接用Quarto；老项目按需迁移，R Markdown在相当长的时间内仍受支持。

七、与数据流水线集成

7.1 定时自动生成报告（结合Make/targets）

library(targets)
library(tarchetypes)
library(readr)

# _targets.R 流水线定义文件
# 需另行提供clean_sales、run_model及接收data/model参数的报告模板
list(
  # 数据准备
  tar_target(raw_data, read_csv("data/sales.csv")),
  tar_target(clean_data, clean_sales(raw_data)),
  tar_target(model_result, run_model(clean_data)),

  # 最后自动渲染报告
  tar_render(
    monthly_report,
    "report_template.Rmd",
    params = list(data = clean_data, model = model_result)
  )
)

# 在命令行运行整条流水线
Rscript -e "targets::tar_make()"

7.2 整合reticulate跑Python代码

# 在R Markdown中调用Python
library(reticulate)
use_python("/usr/bin/python3")

```{python}
import sklearn
from sklearn.ensemble import GradientBoostingClassifier
# Python代码在这里执行
model = GradientBoostingClassifier()
```

```{r}
# 在R中访问Python对象
py_model <- py$model
cat("Python模型已加载到R环境\n")
```