专栏名称: 生信宝典
生物信息分析入门、晋级和经验分享。Linux、R、Python学习教程;高通量测序数据分析学习教程;生信软件安装教程。所有内容均为原创分享,致力于从基础学习到提高整个过程。
目录
相关文章推荐
BioArt  ·  Cell | ... ·  22 小时前  
BioArt  ·  Nat Genet | ... ·  昨天  
51好读  ›  专栏  ›  生信宝典

别人的电子书,你的电子书,都在bookdown

生信宝典  · 公众号  · 生物  · 2018-01-30 18:15

正文

bookdown 是著名R包作者谢益辉开发的,支持采用 Rmarkdown (R代码可以运行)或普通 markdown 编写文档,然后编译成 HTML , WORD , PDF , Epub 等格式。样式清新,使用简单,值得拥有。(点击 阅读原文 ,跳转博客,所有外链可点)

在Bookdown的官网,有很多免费的用 bookdown 写的R书籍,如Hadley Wickham等撰写的《R for Data Science》,Roger D. Peng撰写的《R Programming for Data Science》, 陈总的《液体活检口袋书》,益辉的《R语言忍者秘笈》,《单细胞数据整体分析流程》https://hemberg-lab.github.io/scRNA.seq.course/index.html (初学单细胞分析可以完全照着这个,在学习过程中改进)。

还有很多基于Bookdown的教程,一时也想不起来,欢迎大家补充。我们前面 转录组 R培训 的教案也是用bookdown写作的,后续再调整下格式,出一批电子书和纸质书,有意向和需求的欢迎联系。

下面分2步讲述,自己如何构建一个Bookdown书籍,第一部分是通过bookdown示例了解其基本功能和使用,第二部分是个人在使用过程中碰到的问题和解决方式。

基本使用

安装必须软件

Rstudio Pandoc 二选一, bookdown 必须安装。

  • Install Rstudio (version>1.0.0) (安装和使用见 Rstudio )

  • Install Pandoc (version>1.17.0.2) 或者参照here。如果系统新,可以直接使用系统自带的 yum apt-get ;如果没有权限或系统比较老,Pandoc的安装可以使用conda,具体配置见 Conda配置 ,配置好运行 conda install -c conda-forge pandoc 即可安装。

  • In R install.packages("bookdown")

Demo示例

克隆或下载https://github.com/rstudio/bookdown-demo示例文件,编译成功后,依葫芦画葫芦修改.

编译成书

运行下载的示例中的 bash _build.sh _book 目录下就是成书.

The content of _build.sh is:

#!/bin/sh
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')"
# 生成pdf需要安装好latex,如果不需要可以注释掉
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')"

在前面的内容运转起来后,再看后面的内容。

Customize our bookdown

准备 Rmd 文件

基本规则
  • 一个典型的 bookdown 文档包含多个章节,每个章节在一个 R Markdown 文件里面 (文件的语法可以是 pandoc 支持的 markdown 语法,但后缀必须为 Rmd )。

  • 每一个章节都必须以 # Chapter title 开头。后面可以跟一段概括性语句,概述本章的内容,方便理解,同时也防止二级标题出现在这一页。默认系统会按照文件名的顺序合并 Rmd 文件。

  • 另外章节的顺序也可在 _bookdown.yml 文件中通过 rmd_files:["file1.Rmd", "file2.Rmd", ..] 指定。

  • 如果有 index.Rmd index.Rmd 总是出现在第一个位置。通常index.Rmd里面也需要有一章节,如果不需要对这一章节编号的话,可以写作 # Preface {-} , 关键是 {-}

  • 在第一个出现的 Rmd 文件中 (通常是 index.Rmd ),可以定义 Pandoc 相关的 YAML metadata , 比如标题、作者、日期等 ( 去掉#及其后的内容 )。

    ```
    title: "My book"
    author: #可以写多行信息,都会被当做Author处理
    - "CT"
    - "CY"
    - "[email protected]"
    date: "`r Sys.Date()`"
    documentclass: article #可以为book或article
    # 如果需要引用参考文献,则添加下面三行内容
    bibliography: [database.bib]  #指定存储参考文献的bib文件,endote或zotero都可以导出这种引文格式
    biblio-style: apalike  #设定参考文献显示类型
    link-citations: yes
    ```
    
    ```{r setup, include=FALSE}
    knitr::opts_chunk$set(echo = FALSE, fig.align="center", out.width="95%", fig.pos='H')
    knitr::opts_chunk$set(cache = FALSE, autodep=TRUE)
    set.seed(0304)
    ```
    ~~~~~~
插入并引用图片(外部图片)

插入图片最好使用 knitr::include_graphics ,可以同时适配HTML和PDF输出。另外当目录下同时存在 name1.png name1.pdf 文件时,会自动选择在HTML展示 name1.png 文件,在 PDF 输出中引入 name1.pdf 格式的文件。

图的标签为 fig-name (不能有下划线),在引用时需使用如下格式 \@ref(fig:fig-name) ,且 fig.cap 也要设置内容。

多张图可以同时展示,图的名字以vector形式传给 include_graphics ,需要设置 out.width=1/number-pics fig.show="hold"

Insert a single pic and refer as Figure \@ref(fig:fig-name). `echo=FALSE` will hide the code block and display the output of `r` command only. These options can be set globally as indicated below.

```{r fig-name, fig.cap="Markdown supported string as caption", fig.align="center", echo=FALSE}
knitr::include_graphics("images/1.png")
```

Suppose we have 3 pictures in `images` folder with names as `Fig1_a`, `Fig1_b`,  `Fig1_c`,  we can refer to them using Figure \@ref(fig:fig1).

```{r fig1, fig.cap="3 sub-plots.", fig.align="center", out.width=33%, fig.show="hold"}
fig1 = list.files("images", pattern="Fig1_.*", full.names=T)
knitr::include_graphics(fig1)
```

Another way of including two pics.

```{r fig-name2,  out.width="49%", fig.show="hold", fig.cap="Markdown supported string as caption",  fig.align="center", echo=FALSE}
knitr::include_graphics(c("images/1.png", "images/2.png"))
```
~~~~~~~~~~~~~~~~

如果图或表的标题中有Markdown语法,输出为HTML时是可以正确解析的,但是输出为PDF时却不可以。这时可以使用 Text Reference 。当图或表的标题太长时,也可以使用 Text Reference 引用一段话作为图和表的标题。

Here is normal text.

(ref:pic-label) This line can be referred in **fig.cap** and markdown syntax is supported for both `HTML` and `PDF` output.

```{r pic-label, fig.cap="(ref:pic-label)"}
knitr::include_graphics("images/1.png")
```
~

输出PDF时不支持使用在线图片,可以加一个判断。

```{r fig-name, fig.cap="Markdown supported string as caption", fig.align="center", echo=FALSE}
if (!file.exists(cover_file 
插入并引用表格(外部表格)

外部表格的名字中必须包含 tab: , 然后是表格的实际名字,格式为 (\#tab:table-name) ; 引用时使用 Table \@ref(tab:table-name) 。 表格名字中不能有下划线。

Check Table \@ref(tab:seq-sum) for detail.

Table: (\#tab:seq-sum) Summary of sequencing reads 测序量总结 (对于双端测序,  *\_1* 表示左端reads, *\_2* 表示右端reads) 

----------------------------------------------------------------------
Sample     Total reads     Total bases Sequence length (nt)     GC content (%) Encoding               
-------- ------------- --------------- ---------------------- ---------------- -----------------------
T8_1        37,106,941   5,566,036,721 138-150                              47 Sanger / Illumina 1.9  

T8_2        37,106,941   5,566,034,285 138-150                              47 Sanger / Illumina 1.9  
----------------------------------------------------------------------
插入并引用表格(内部表格)

插入表格推荐使用 knitr::kable ,只要提供数据矩阵,用 r 读取就可以了。

Check Table \@ref(tab:table-id) for detail.

```{r table-id, include=FALSE}
a 
插入脚注

text^[footnote] is used to get the footnote.

where `type` may be `article`,  `book`,  `manual`,  and so on.^[The type name is case-insensitive,  so it does not matter if it is `manual`,  `Manual`,  or `MANUAL`.]
插入引文

假如我们的 bib 文件中内容如下,如果我们要引用这个文章,只要写 [@chen_m6a_2015] 就可以了。

@article{chen_m6a_2015,
    title = {m6A {RNA} {Methylation} {Is} {Regulated} by {MicroRNAs} and {Promotes} {Reprogramming} to {Pluripotency}},
    volume = {16},
    issn = {1934-5909, 1875-9777},
    url = {http://www.cell.com/cell-stem-cell/abstract/S1934-5909(15)00017-X},
    doi = {10.1016/j.stem.2015.01.016},
    language = {English},
    number = {3},
    urldate = {2016-12-08},
    journal = {Cell Stem Cell},
    author = {Chen, Tong and Hao, Ya-Juan and Zhang, Ying and Li, Miao-Miao and Wang, Meng and Han, Weifang and Wu, Yongsheng and Lv, Ying and Hao, Jie and Wang, Libin and Li, Ang and Yang, Ying and Jin, Kang-Xuan and Zhao, Xu and Li, Yuhuan and Ping, Xiao-Li and Lai, Wei-Yi and Wu, Li-Gang and Jiang, Guibin and Wang, Hai-Lin and Sang, Lisi and Wang, Xiu-Jie and Yang, Yun-Gui and Zhou, Qi},
    month = mar,
    year = {2015},
    pmid = {25683224},
    pages = {289--301},
}

准备YML配置文件

_bookdown.yml

配置输入和输出文件参数。

book_filename: "输出文件的名字" 
output_dir: "输出目录的名字,默认_book"
language:
  ui:
      chapter_name: ""
_output.yml

配置产生输出文件的命令行参数。

bookdown::pdf_book:
  template: ehbio.tex #使用自己定制的pandoc latex模板
  includes: # or only customize part latex module
    in_header: preamble.tex
    before_body: latex/before_body.tex
    after_body: latex/after_body.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
  pandoc_args: --chapters
  toc_depth: 3
  toc_unnumbered: no
  toc_appendix: yes
  quote_footer: ["\\VA{", "}{}"]
bookdown::epub_book:
  stylesheet: css/style.css
bookdown::gitbook:
  css: style.css
  split_by: section
  config:
    toc:
      collapse: none
      before: | #设置toc开头和结尾的链接
          
  •      after: |          
  • [email protected]
  •    download: [pdf, epub, mobi]    edit: https://github.com/rstudio/bookdown/edit/master/inst/examples/%s    sharing:      twitter: no      github: no      facebook: no

    其它定制

    • 不同的文件分别用于 html pdf 输出







    请到「今天看啥」查看全文