# 用你的数据写作

让分析输入、脚本、表格和稿件结果保持关联。

当背后的计算就在附近时，结果段落更容易让人信服。用研究项目把分析流程及其输出与稿件放在一起。

## 设置项目

选择 **可复现分析** 研究起点模板。[链接数据文件夹](/docs/linked-folders/)，这样研究工具就能读取原始测量数据，而不必把它们移进论文。

在请求分析之前，先记录各列的含义、单位和任何被排除的数据。

## 给助手一个有边界的任务

使用 `/oleafly-data-analysis`，或 **分析** [研究任务](/docs/research-tasks/)：

> 读取已链接的 Data 文件夹中的测量数据。使用 analysis-plan.md 中的方法比较两种条件。保存脚本、带单位的表格，以及一份说明被排除数据的笔记。保持输入数据不变。

分析脚本需要相应的本地运行环境和库。请让助手检查这些要求，并保存重新运行这项工作的方法。

## 检查输出

阅读脚本，确认所选的数据和方法与研究问题相符。接受结果之前，请检查单位、样本数、缺失值和不确定性。

把表格和图片与生成它们的脚本放在一起。[图片准备技能](/docs/skills/)可以帮助把核对过的结果做成稿件用的图片。

使用 [CLI 代理](/docs/cli-agents/#research-starting-points)时，**可复现性核查** 起点会询问每个结果还需要什么才能被复现：代码、数据、软件版本、随机种子和构建说明。**图片核查** 检查图注、标签、坐标轴单位和可读性。两者都会要求代理在 `research/` 中写一份报告，并且不改动稿件。

## 在文档内运行代码

要让 PDF 中的数字直接来自代码，请用 [Quarto 或 Calepin](/docs/engines/#quarto) 撰写报告。Quarto 在 `.qmd` 或 `.Rmd` 文件中运行 R、Python 或 Julia 代码块，Calepin 则在 Typst 文档中运行代码块。

- 在你选择 **在此项目中允许代码** 之前，每个项目中的代码都是关闭的。代码关闭时，Quarto 显示每个代码块的代码但不显示输出，Calepin 显示代码上次运行时保存的结果。过滤器、短代码、`_extensions` 文件夹、渲染脚本和内联 R 代码，即使在这时也会运行代码，所以使用其中任何一项的项目在你允许代码之前无法编译。
- 代码关闭且电脑上没有 R 时，带有前置元数据的 `.qmd` 文件仍然可以预览，除非它的前置元数据里有 `knitr:` 键。任何其他含有 R 代码的文档，包括 `.Rmd` 文件，即使代码关闭也需要 R。请从 [cloud.r-project.org](https://cloud.r-project.org/) 安装 R，然后再次编译。
- Oleafly 需要 Quarto 1.5 或更新版本。如果你的版本较旧，Oleafly 会使用它自己的副本，或请你从 **设置 → 引擎 → Quarto** 下载一份。没有下载副本时，`_quarto.yml` 项目中的文档会改用你较旧的 Quarto 构建。
- 当项目有装有 Jupyter 的 `.venv`、`venv` 或 `env` 文件夹时，Python 代码在项目自己的环境中运行，Calepin 在项目有 `.venv` 文件夹时使用它。否则代码在 **设置 → 引擎 → Quarto** 的 **语言** 下列出的 Python 中运行。
- `pdf` 或 `beamer` 文档需要 LaTeX。没有安装 TeX 时，请在 Oleafly 提供时安装 TinyTeX，把文档切换为 `format: typst`，或在允许代码之后，在前置元数据中加入 `pdf-engine: tectonic` 来使用内置引擎。
- Quarto 会在文档旁边写出一个同名的工作文件：PDF 对应 `report.tex`，Typst 对应 `report.typ`。如果你已有同名文件，编译会停止并指出它，而不是替换它。请重命名或移动你的文件，然后再次编译。
- 如果 PDF 中缺少韩文、中文或日文字符，警告会指出一个字体，并给出要加入前置元数据的两行：用该字体的 `CJKmainfont:`，以及 `pdf-engine: tectonic`。两行都要加，因为这个字体随内置引擎提供。`pdf-engine: tectonic` 只有在项目允许代码之后才有效。
- 笔记本最长可以运行一小时。超过后，Oleafly 会停止它，日志会显示它运行到的单元格。请缩短或缓存该单元格，然后再次编译。

## 撰写结果

请助手只使用经过审阅的输出来起草结果段落。对照表格检查每一个数字，并把方法与解释区分开。

编译文档，并在 PDF 中检查完整的表格或图片，包括标签和图注。
