创作R Markdown小插图
2022年4月26日
摘要
启用说明Bioconductor风格在R Markdown小插图。包
BiocStyle 2.24.0
1先决条件
BioconductorR Markdown格式是建立在上面R包bookdown这反过来又依赖于rmarkdown而且pandoc编译最终输出文档。因此，除非您正在使用RStudio，否则您将需要最新版本的pandoc(> = 1.17.2)。看到Pandoc安装说明有关为您的平台安装pandoc的详细信息。
2开始
要启用Bioconductor风格在你的R Markdown小插图，你需要:
编辑
描述通过添加VignetteBuilder:针织建议:BiocStyle，针织，rmarkdown指定
BiocStyle: html_document或BiocStyle: pdf_document作为输出格式，并在文档头中添加小插图元数据:——title:“Vignette title”作者:“Vignette author”包:PackageName输出:BiocStyle::html_document Vignette: > %\VignetteIndexEntry{Vignette title} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8}——
的装饰图案部分是为了指导R如何建立小插图。1\ VignetteIndexEntry应匹配标题你的小插图的包包含包名的字段用于在输出文档头中打印包版本。没有必要详细说明日期默认情况下，文件编译日期将自动包含。有关指定作者从属关系和摘要的详细信息，请参阅下面的部分。
BiocStyle的html_document而且pdf_document格式函数扩展了相应的原始格式rmarkdown格式，所以它们接受相同的参数html_document而且pdf_document,分别。例如，使用toc_float:真以获得浮动TOC，如本插图所示。
2.1使用R markdown v1
除了默认的降价引擎实现的r CRANpkg(“rmarkdown”)包，也可以编译Bioconductor使用包中的旧markdown v1引擎的文档r CRANpkg(“减价”)．这两个引擎在设置和结果输出方面存在一些差异。
使用减价小插图生成器引擎:
编辑
描述要包含的文件建议:BiocStyle，针织控件中指定小插图引擎
.Rmd文件(在HTML注释中)<！——%% \VignetteEngine{knitr::knitr}——> .使用实例的开头添加以下代码块
.Rmd小插曲' ' ' {r style, echo = FALSE, results = 'asis'} BiocStyle::markdown()' ' '
使用时附加CSS文件的方式减价不同于这是怎么做的rmarkdown．在前一种情况下，可以通过将附加样式表提供给BiocStyle:减价函数。包括custom.css文件使用
' ' ' {r style, echo = FALSE, results = 'asis'} BiocStyle::markdown(css。Files = c('custom.css'))' ' '3.文档标题
3.2摘要和运行报头
摘要可以在相应的字段中输入文档的正面事项，如下例所示。
——title: "标题页的完整标题" shorttitle: "标题的短标题" author: "Vignette author " package: PackageName abstract: >文档摘要输出:BiocStyle::pdf_document——的shorttitle选项指定运行头中使用的标题，而不是文档标题。2只与PDF输出相关
4风格的宏
BiocStyle介绍在参考时有用的以下宏R包:
Biocpkg(“IRanges”)为Bioconductor软件、注释和实验数据包，包括到发布登陆页面的链接，或者如果包只在devel中，则到devel登陆页面的链接，IRanges．CRANpkg(“data.table”)为RCRAN上提供的软件包，包括到FHCRC CRAN镜像登录页面的链接，data.table．Githubpkg(“rstudio / rmarkdown”)为RGitHub上可用的包，包括到包存储库的链接，rmarkdown．Rpackage(“MyPkg”)为R以下的包不上可用Bioconductor， CRAN或GitHub;MyPkg．
它们被称为内联的，例如，' r Biocpkg (IRanges) '．
5代码块
输出代码块的行长被设置为最佳宽度，通常为80个字符，因此不需要手动调整选项(“宽度”)．
6数据
6.1简单的数据
BiocStyle附带三种预定义的数字大小。如下面的例子所示，未特别指明的常规数字相对于段落文本缩进。
情节(汽车)
6.2图标题
没有标题的数字，就像上面的一个，只是放在它们生成的任何地方R代码。如果您通过“代码块”选项将标题分配给图形fig.cap，该地块将自动标记和编号3.对于PDF输出，它将被放置在一个浮动数字环境，也可以引用它。这些特性由bookdown，它定义了一种与格式无关的语法，用于指定交叉引用，请参见节9．图形标签是从代码块标签生成的4对于要工作的交叉引用，块标签只能包含字母数字字符(a-z, a-z, 0-9)，斜杠(/)或破折号(-)加上前缀图:例如，源于数据块的图形的标签喷火将无花果:foo．要引用图形，请使用语法\ @ref(标签)5不要忘记前面的反斜杠!,在那里标签是图形标签，例如，无花果:foo．例如，下面的代码块用于生成图1．
{r图形，fig.cap = "正则图形。第一句…"，echo = FALSE}情节(汽车)' ' '
图1:正则图
图标题的第一句被自动强调作为图标题。
6.3可供选择的数字尺寸
除了常规数字，BiocStyle提供可由指定的小和宽图形fig.small而且fig.wide代码块选项。宽幅图与段落左对齐，并在右侧边缘延伸，如图所示2．小图形表示可能是矩形图形，这些矩形图形相对于文本列居中，参见图3.．
图2:宽图
由带有选项的代码块生成的图形fig.wide = TRUE．
图3:小的图
由带有选项的代码块生成的图形图.small = TRUE．
6.4可访问性的考虑
Alt(替代)文本被屏幕阅读器用来向视障读者提供图像的描述。如果您使用fig.cap相同的文本将自动用作图像的Alt文本。但是，如果您希望包含没有标题的图像，或者希望在标题的alt文本中提供不同的信息，则可以通过fig.alt代码块选项。例如，下面的代码块用于包含本节中显示的第一个图像，以便使用屏幕阅读器将其意图传达给某人。
{r no-cap, fig.alt="没有标题的默认大小的示例图。"}情节(汽车)' ' '您可能还需要考虑图形中使用的调色板，以确保颜色受损的读者也能阅读它们。BiocStyleCRAN没有提供特定的调色板，但在CRAN的软件包中提供了许多选项。也有一些重大的努力所提供的默认颜色面板()在R-4.0.0。Bioconductor包含一些领域特定的软件包，专注于色盲友好的可视化，例如。dittoSeq用于单细胞和批量rna测序数据。
7表
与图表一样，带标题的表格也将被编号，并可以引用。标题输入为以。开头的段落表:6或者只是：，它可以出现在表的前面或后面。添加标签时，请确保标签出现在表单中表标题的开头(\ #标签:标签)，并使用\ @ref(标签:标签)参考它。例如，表1已使用以下代码生成。
水果|价格------- | -----香蕉| 1.2苹果| 1.0橙子| 2.5:(\#tab:table)一个简单的表。标题。| 水果 | 价格 |
|---|---|
| 香蕉 | 1．2 |
| 苹果 | 1．0 |
| 橙子 | 2.5 |
这个函数knitr: kable ()将自动为表环境生成一个标签，哪个是块标签前缀标签:，见表2．
knitr::kable(head(mtcars[， 1:8]， 10)，标题= '一个表的前10行' mtcars '。”)| 英里/加仑 | 共青团 | disp | 惠普 | 见鬼 | wt | qsec | vs | |
|---|---|---|---|---|---|---|---|---|
| 马自达RX4 | 21.0 | 6 | 160.0 | 110 | 3.90 | 2.620 | 16.46 | 0 |
| 马自达RX4 Wag | 21.0 | 6 | 160.0 | 110 | 3.90 | 2.875 | 17.02 | 0 |
| 日产710 | 22.8 | 4 | 108.0 | 93 | 3.85 | 2.320 | 18.61 | 1 |
| 大黄蜂4驱动器 | 21.4 | 6 | 258.0 | 110 | 3.08 | 3.215 | 19.44 | 1 |
| 大黄蜂Sportabout | 18.7 | 8 | 360.0 | 175 | 3.15 | 3.440 | 17.02 | 0 |
| 勇敢的 | 18.1 | 6 | 225.0 | 105 | 2.76 | 3.460 | 20.22 | 1 |
| 喷粉机360 | 14.3 | 8 | 360.0 | 245 | 3.21 | 3.570 | 15.84 | 0 |
| 芝加哥商业交易所240 d | 24.4 | 4 | 146.7 | 62 | 3.69 | 3.190 | 20.00 | 1 |
| 芝加哥商业交易所230 | 22.8 | 4 | 140.8 | 95 | 3.92 | 3.150 | 22.90 | 1 |
| 芝加哥商业交易所280 | 19.2 | 6 | 167.6 | 123 | 3.92 | 3.440 | 18.30 | 1 |
8方程
若要对方程进行编号和引用，请将它们放在方程环境中，并按照语法为它们附加标签(\ #情商:标签)7由于技术上的限制，方程标签必须以情商:,例如,
f \ \}{方程开始离开(k \右)= \ binom p {n} {k} ^ k \离开(1 - p \右)^ {n - k}结束(\ #情商:binom) \{方程}渲染下面的方程。
\[开始\{方程}f \左(k \右)= \ binom p {n} {k} ^ k \离开(1 - p \右)^ {n - k}{1} \ \标签结束{方程}\]
你可以参考方程式(1）通过\ @ref (eq binom):．注意，在HTML输出中，只有标记的方程式才会显示编号。
9交叉引用
除参考数字外(第6)，表(节7)和方程(节)8)，也可以使用相同的语法\ @ref(标签)引用章节，其中标签是section ID。默认情况下，Pandoc将为所有节头生成id，例如:#你好世界将有一个IDhello world．为了避免在更改节头后忘记更新引用标签，您还可以通过追加手动为节头分配ID{# id}到它。
当无法找到引用标签时，您将看到两个问号，如?？，并在R控制台时呈现文档。
10边注
脚注作为边注显示在右页边距上8这是作为脚注输入的边注，这样做的好处是它们看起来离它们被定义的地方很近。
会话信息
这是的输出sessionInfo ()在运行pandoc 2.5编译本文档的系统上:
## R版本4.2.0 RC (2022-04-19 r82224) ##平台:x86_64-pc-linux-gnu(64位)##运行在Ubuntu 20.04.4 LTS ## ##矩阵产品:默认## BLAS: /home/biocbuild/bbs-3.15-bioc/R/lib/libRblas。/home/biocbuild/bbs-3.15-bioc/R/lib/libRlapack。所以## ## locale: ## [1] LC_CTYPE=en_US。UTF-8 LC_NUMERIC= c# # [3] LC_TIME=en_GB LC_COLLATE= c# # [5] LC_MONETARY=en_US。utf - 8 LC_MESSAGES = en_US。UTF-8 ## [7] LC_PAPER=en_US。UTF-8 LC_NAME= c# # [9] LC_ADDRESS=C lc_phone = c# # [11] LC_MEASUREMENT=en_US。UTF-8 LC_IDENTIFICATION=C ## ##附加的基本包:## [1]stats graphics grDevices utils datasets methods基础## ##其他附加包:## [1]BiocStyle_2.24.0 ## ##通过命名空间加载(且未附加):## [1] Rcpp_1.0.8.3 bookdown_0.26 digest_0.6.29 ## [4] R6_2.5.1 jsonlite_1.8.0 magrittr_2.0.3 ## [7] evaluate_0.15 highr_0.9 stringi_1.7.6 ## [10] rlang_1.0.2 cli_3.3.0 jquerylib_0.1.4 ## [13] magick_2.7.3 bslib_0.3.1 rmarkdown_2.14 ## [19] yaml_2.3.5 fastmap_1.1.0 compiler_4.2.0 ## [22] BiocManager_1.30.17 htmltools_0.5.2 knitr_1.38 ## [25] sass_0.4.1