2  分析环境安装与使用

2.1 文档目的

本文说明如何建立 ivdtools 分析环境、创建 R Markdown 项目、导入和核验数据、 执行渐进式分析并保存可复现结果。

2.2 安装 R

ivdtools 0.1.1 要求 R >= 4.1.0。建议使用仍受支持的较新 R 版本，并保持项目内 所有人员的主版本和依赖版本一致。

2.2.1 Windows 和 macOS

从 CRAN 下载对应系统的安装程序：https://cran.r-project.org/。

  • Windows：安装 R；只有从源码编译含本地代码的包时才需要匹配版本的 Rtools。
  • macOS：根据处理器架构选择安装包；从源码编译时可能需要 Xcode Command Line Tools。

2.2.2 Debian/Ubuntu

系统仓库可以安装基础 R：

sudo apt update
sudo apt install r-base r-base-dev

2.2.3 Fedora

sudo dnf install R R-devel

Linux 发行版仓库中的 R 版本可能较旧；若项目需要较新的 R，应按照 CRAN 对应发行版的 说明配置软件源。

2.3 选择编辑器

推荐使用 .Rmd 或 .qmd 文件记录代码、文字、表格和图形。

软件 Windows Linux macOS 适用情况
RStudio ✓ ✓ ✓ 开箱即用，适合初学者和常规分析
Positron ✓ ✓ ✓ 适合希望使用新一代 Posit IDE 的用户
Visual Studio Code ✓ ✓ ✓ 需要配置 R、Quarto 等扩展
Jupyter ✓ ✓ ✓ 需要 Python、Jupyter 和 R kernel
PyCharm ✓ ✓ ✓ 需要相应 R 支持和额外配置

RStudio 和 Positron 可从 https://posit.co/downloads/ 获取；Visual Studio Code 可从 https://code.visualstudio.com/Download 获取。

2.4 安装 R 包

当 ivdtools 已在所用 CRAN 镜像发布时：

代码 
install.packages(c("ivdtools", "rmarkdown", "knitr"))

数据导入可按需安装附加包：

代码 
install.packages(c("readr", "readxl"))

2.5 新建项目

在 RStudio 中选择 File > New File > R Markdown。

最小文档模板：

---
title: "IVD 分析报告"
author: "分析人员"
date: "填写报告日期"
output:
  html_document:
    toc: true
    number_sections: true
---

随后插入一个名为 setup、设置了 include=FALSE 的 R 代码块，内容如下：

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(ivdtools)

2.6 导入和核验数据

2.6.1 CSV

基础 R：

代码 
dat <- read.csv(
  "data-raw/method-comparison.csv",
  stringsAsFactors = FALSE,
  check.names = FALSE
)

使用 readr：

代码 
dat <- readr::read_csv(
  "data-raw/method-comparison.csv",
  show_col_types = FALSE
)

2.6.2 Excel

代码 
dat <- readxl::read_excel(
  "data-raw/method-comparison.xlsx",
  sheet = "data"
)

若 Excel 文件包含公式、合并单元格或人工格式，应先确认导入后的 值、列名和数据类型与原表一致。

2.7 运行代码

在 .Rmd 中插入 R 代码块，使用代码块右上角按钮运行当前块，或从上到下运行全部代码。

为确保可复现，最终报告应通过全新 R 会话从头渲染，而不是只依赖 Console 中已经存在的对象。

2.8 导出结果

2.8.1 表格

读取帮助页中说明的结果字段后，可写出 CSV：

代码 
# 示例：实际字段应根据相应对象帮助页确认
result_table <- mc$regression
saveRDS(result_table, "tables/regression-result.rds")

复杂对象优先保存为 RDS，以保留类和属性；需要与其他软件交换时再整理为扁平数据框并 导出 CSV。

2.8.2 图形

代码 
p <- plot(mc, type = "bland_altman")
ggplot2::ggsave(
  "figures/bland-altman.png",
  plot = p,
  width = 7,
  height = 5,
  dpi = 300
)

2.9 渲染和保存

在 RStudio 中点击 Knit，或者运行：

代码 
rmarkdown::render(
  "report/analysis.Rmd",
  output_format = "html_document",
  clean = TRUE
)

分析完成后记录环境信息：

代码 
sessionInfo()

建议归档：

  1. 未修改的原始数据；
  2. .Rmd 源文件；
  3. 渲染后的 HTML/PDF；
  4. 可读结果和图形；
  5. sessionInfo()环境信息；