In Gedevan-Aleksizde/rmdja: R Markdown Formats for Japanese
(PART) R Markdown と Bookdown の基本機能 {-}
このパートの概要 {-}
ここではまず, R Markdown の基本的な機能を紹介する. つまり bookdown 特有のものではなく, R Markdown 全般で使用できる機能も含めて紹介する. これ以降は自己言及的な説明が多いため, この文書を生成しているソースコードと比較しながら確認することをおすすめする. ここで紹介する機能は BKD, RDG, RCB での記述に基づく.
これら3つのドキュメントを読めば, ほとんどのことは可能になる --- rmdja を作る理由になった LaTeX テンプレートの修正以外は --- のだが, 本稿の重要な目的の1つは複数のファイル形式をなるべく簡単に両立することであるので, それができない書き方には触れないし, 技術文書の作成にあまり使わないような機能の動作確認はおこなわず, 技術文書作成で頻繁に使われ, 便利と思える機能のみ紹介する.
どちらにしろそのうちこれらを翻訳してくれる人が現れることだろう...たぶん.
静的なコンテンツの作成
まずは, 単なるマークアップ, つまりプログラミングの複雑な処理を考えなくても良いタイプの, 簡単な構文を紹介する. それらの多くは一般的な Markdown のものと同じである.
日本語で書かれた資料でごく基本的なことについて, 『R Markdown入門』で一通り紹介されている. やや応用的なことも 『R Markdown ユーザーののための Pandoc's Markdown』に書かれている.
Markdown の基本構文
一応基本の Markdown の構文も挙げておく. 詳細は(ref:BKDB)"Ch. 2.2 Markdown Syntax" を参照.
インラインでの書式変更
テキストの一部のみ書式を変える
アンダースコアで強調 (イタリック)
_underscore_
underscore
** 2つで太字強調
**太字強調**
太字強調
等幅フォント
`bookdown` と `rmdja`
bookdown と rmdja
本文中に入力した URL は自動判別され, ハイパーリンクが付けられる. また, [テキスト](URL) という書式で, テキストに対してハイパーリンクを付けることができる.
URL は自動判別される: https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja
[`rmdja` の github リポジトリ](https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja)
URL は自動判別される: https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja
ブロック要素
以降は行内では使えず, 適切に表示するには前後に改行を挟む必要のあるタイプの構文である.
まず, 引用ブロックを使えばかっこいいエピグラフを書き放題である.
> Нужны новые формы. Новые формы нужны, а если их нет, то лучше ничего не нужно.
>
> 新しいフォーマットが必要なんですよ. 新しいフォーマットが. それがないというなら, いっそ何もないほうがいい.
>
> `\r tufte::quote_footer('--- A. チェーホフ『かもめ』')`
Нужны новые формы. Новые формы нужны, а если их нет, то лучше ничего не нужно.
新しいフォーマットが必要なんですよ. 新しいフォーマットが. それがないというなら, いっそ何もないほうがいい.
r tufte::quote_footer('--- A. チェーホフ『かもめ』')
rmdja では, HTML と PDF 両方で同様のデザインの枠で表示するようにしている.
Markdown では # は見出しを意味するが, bookdown にはさらにオプションが用意されている.
# 見出し名 {-} で, セクション番号のつかない見出しを用意できる. 序文, 章末の参考文献, 付録のセクションに使えるだろう. さらに, bookdown では # (PART) 見出し名 で「部」の見出しを作ることができる. この見出しは セクションの合間に挟まるが, 選択することはできない. 文書が長くなったときに, より大きな区切りを付けるのに役に立つだろう. さらに, # (APPENDIX) 見出し名 {-} で, 以降の見出しの頭に 「補遺 A, B, C, ...」と付番できる.
箇条書きは以下のように書ける.
* iris setosa
* iris versicolor
* iris virginica
- iris setosa
- iris versicolor
- iris virginica
1. iris setosa
2. iris versicolor
3. iris virginica
- iris setosa
- iris versicolor
- iris virginica
インデントを使えばネストできる.
- 課長
- 課長補佐
- 課長補佐代理
- 課長補佐代理心得
Markdown を使った図表の挿入
markdown は表を記入することもできる.
Table: Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
------------- ------------ ------------- ------------
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
Table:Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
画像ファイルも貼り付けられる.
{ width=50% }
しかし, キャプションを付けたり, 表示位置やサイズを細かく調整したり, 注釈を付けたりするためには, 後述するようにRプログラムを経由して出力したほうが良い.
TODO: md 記法で画像貼り付けたときのサイズ統一
コメントアウト
HTML 式の <!-- --> でコメントアウトできる. コメントアウトされた箇所は生成ファイルでもコメントアウトされるのではなく, そもそも出力されなくなる.
数式
LaTeX 記法で数式を記述できる. HTML ならば Mathjax によってレンダリングされる. 数式の記述ルールは少々ややこしい. これは現在の pandoc の仕様で HTML および LaTeX の規格で矛盾なく出力するためやむをえない措置である.
- 改行をしない行内数式は
$ で囲む, または \(, \) で囲む.
- 改行を伴う数式ブロックは
$$ で囲む, または \[, \] で囲む.
align, equation 環境等を使う場合は, 上記の記号を使わず, 直接 LaTeX コマンド \begin{align}... を打ち込む.
\@ref(eq:binom) は二項分布の確率関数である
\begin{align}
f(k) &= {n \choose k} p^{k} (1-p)^{n-k} (\#eq:binom)
\end{align}
その出力は, 以下のようになる.
\@ref(eq:binom) は二項分布の確率関数である
\begin{align}
f(k) &= {n \choose k} p^{k} (1-p)^{n-k} (#eq:binom)
\end{align}
Bookdown では従来の R Markdown でできなかった数式への付番と, 本文中での参照アンカーリンクの自動作成が可能となっている (詳細は \@ref(crossref) 章で). LaTeX にすでに慣れている読者に注意が必要だが, Bookdown 特有の制約として, 付番したい場合は \label{ID} ではなく (\#eq:ID) を使う. また, PDF (LaTeX) と HTML (Mathjax) の仕様には
- PDF では
align は常に数式が付番され, align* 等はどうやっても付番されない
- HTML では
align でも align* であってもラベルを書かなければ付番されず, 書けば付番される.
という違いがある. 両者で同じ表示にこだわるのなら, 付番を取り消す \notag を多用することになるだろう.
さらに, bookdown の機能として, LaTeX の「定理」「定義」「証明」などの環境に対応するものが提供されている (参考: BKD Ch. 2.2 Markdown extensions by bookdown). これらの相互参照も可能である.
例: 以下に補題 \@ref(lem:borelcantelli), 定理 \@ref(thm:theorem1) を示す.
```{lemma borelcantelli, name="ボレル-カンテリの補題"}
${E_1,E_2,\cdots}$をある確率空間の事象とする. これらの事象の確率の和が有限であるなら, それらが無限に多く起こる確率はゼロである. つまり,
\begin{align}
& \sum_{n=1}^\infty \mathrm{P}(X_n) <\infty \Rightarrow \mathrm{P}\left(\lim_{n\to\infty}\sup X_n\right) = 0,\
& \lim_{n\to\infty}\sup X_n = \bigcap_{n=1}^\infty\bigcup_{k\leq n}^\infty E_k
\end{align}
である.
```{proof borelcantelli-proof}
証明は読者の課題とする.
```{theorem theorem1, name="無限の猿定理"}
猿がほとんど確実にタイプライタの全てのキーを無限回叩くならば, ほとんど確実にテキストには任意の作品が含まれる.
```{proof theorem1-proof}
補題 \@ref(lem:borelcantelli) より自明.
カスタムブロック
数式のセクションの定理ブロックの応用で, 独自のブロックセクションを定義することができる. rmdja では BKD Ch. 2.7 Custom blocks で紹介されている例を予め使えるようにしている. それらは type="..." で指定できて, 以下の5種類がある.
cautionimportantmemotipwarning
である.
``{block block-example-caution, type="caution"}
技術書によくある注意を喚起するブロック (caution`).
```{block block-example-important, type="important"}
技術書によくある注意を喚起するブロック (`important`).
``{block block-example-memo, type="memo"}
技術書によくある注意を喚起するブロック (memo`).
```{block block-example-tip, type="tip"}
技術書によくある注意を喚起するブロック (`tip`).
``{block block-example-warning, type="warning"}
技術書によくある注意を喚起するブロック (warning`).
このブロック内では Markdown の基本構文しか使えず, 引用や相互参照などは使えない. これらをブロック内で使いたい場合は `block` の代わりに `block2` と書く. ただしこちらは pandoc の機能のハックであるため, 将来使えなくなる可能性もある.
やや煩雑になるが, Pandoc の fenced Div を利用した書き方は, より安全である.
:::{.infobox .important data-latex="{warning}"}
fenced Div によるブロック
:::
fenced Div によるブロック
:::
この構文の意味の解説は『R Markdown クックブック』などを参考に.
## 脚注
脚注はインラインと, 巻末に書く2通りがある.
```markdown
ここにインラインで脚注^[脚注の本文]
ここにインラインで脚注^[脚注の本文]
本文は巻末に書く[^example-1][^example-2].
[^example-1]: 脚注の本文その2
[^example-2]: 脚注の本文その2
本文は巻末に書く^example-1.
ここにインラインで脚注[^脚注の本文]
インラインで書くほうがシンプルに見えるが, この記法では間を空けずに連続して脚注を書くことができない.
このように書くと^[脚注その1]^[脚注その2]上付きとして認識される
改行・改頁 (改ページ)・改丁
HTMLやTexをそのまま書く場合と違い, Markdown での改行はそのまま反映されるため, 通常は <br> や \\ などを書く必要はない. HTML の場合, 紙への印刷を想定しないため任意のタイミングで改ページするという考え方はない. Webページの分割は章やセクション単位でなされる. PDF の場合は \newpage, \clearpage, \cleardoublepage という3種類の命令文が用意されている.
\newpage はページを改めるが, 段組の場合は次のページではなく次の段に飛ぶ.\clearpage は段組みでもページを改める. またそれ以前に配置した図表のフロートの配置を確定させる. つまり図表をフロートにしても \clearpage をまたいで位置が変わることはない.\cleardoublepage は次の奇数ページまで飛ぶ (いわゆる改丁). 書籍では通例, 章の始めなどを奇数ページに揃える. なお # で章見出しを書いた場合は自動でこの命令文が適用されるため手作業でこの命令文を書く必要はない.
動的なコンテンツの作成
プログラムチャンク
プログラムチャンクは, R Markdown 最大の特徴であり, R のソースコードや, その実行結果を Markdown に挿入できる. さらには R 以外の言語の動作も可能である. 順番が前後してしまったが, 定理などのカスタムブロックは本来はプログラムを入力するためのチャンクブロックであり, それを静的なテキストコンテンツの挿入に流用しているだけである.
以降は R で多くのユーザが頻繁に使うパッケージと, いくつかの技術文書作成に役に立つパッケージをインポートしている前提の説明とする. なお, rmarkdown, bookdown はチャンク内で特に読み込む必要がない.
pkgs <- installed.packages()
for(p in c("tidyverse", "ggthemes", "equatiomatic", "tufte", "kableExtra")){
if(!p %in% pkgs) install.packages(p)
}
if(!"rmarkdown" %in% pkgs) remotes::install_github("rstudio/rmarkdown")
if(!"bookdown" %in% pkgs) remotes::install_github("rstudio/bookdown")
require(tidyverse)
require(ggthemes)
require(equatiomatic)
require(kableExtra)
このように, ログを掲載することもできる. これは再現性を重視する際に重宝するが, 一方で単に画像などの出力だけを掲載したい場合もあるだろう. あるいは, プログラムを解説するためにプログラムは掲載するが実行しない, ということも必要になるかもしれない. プログラムと結果の表示/非表示はどちらも簡単に切り替え可能である. そのためには, チャンクオプションを指定する.
echo: プログラムを掲載するかどうかmessage: プログラム実行結果の標準出力を掲載するかどうかwarning: プログラム実行結果の警告を掲載するかどうかerror: プログラム実行結果のエラーを掲載するかどうかeval: 文書作成時にプログラムを実行するかどうかinclude: 文書作成時にプログラムを実行し, かつ掲載しないかどうかresults: 出力をいつもの R の出力風にするか (markup), 隠すか ("hide"), 出力を区切らずまとめるか ("hold"), テキストをそのまま出力するか ("asis"). 最後は R Markdown のソースコードを動的に生成したい場合などに使う.
``{block, type="memo"}
R の論理値はTRUE/FALSEまたはT/F` と書く.
チャンクごとに個別に設定することも, デフォルト値を一括設定することもできる. 前者の場合, チャンクオプションは `{}` 内部にカンマ `,` で区切って書く. `r` は R で実行するという意味である. チャンクの一般的な記法は以下のようになる.
````
`r ''````r
data(cars)
summary(cars)
`r ''````
````
`r` の直後の `<label>` は**ラベル**と呼ばれ, チャンクのIDとしての機能を持つ (省略された場合は自動で適当な名前がつけられる). ラベルは主に後述の図表の相互参照に使われる. ラベルは英数字とハイフンを使って重複しない範囲で自由に命名できる.
一括設定の場合, 以下のようなプログラムでデフォルト値を上書きできる.
```r
knitr::opts_chunk$set(
echo = F,
message = T,
warnings = F,
error = F
)
なおこのチャンクは eval=F を設定することで, 実行されることなくプログラムのみ掲載している. ただし, プログラムのみを掲載するなら, 以下のように Markdown の機能でも可能である. こちらの記法は {} がなくなっていることに注意する.
`r ''````sh
echo Hello, Bookdown
`r ''````
{} ブロック内の値にはさらに R プログラムで与えることができる. この使い方は後の章で解説する.
これらのオプションがあるおかげでプログラムとその結果の再現を説明したい場合はソースコードも表示させたり, 回帰分析やシミュレーションの結果だけを掲載したい時は結果のみ表示したりできる. これが R Markdown のチャンクの強みである. 例えば Jupyter notebook/lab などは従来, コードセルと出力セルを自由に隠すことができなかった.
チャンクに使用できる言語は R だけではない. つまり Python なども使用できる(詳細は \@ref(python) 章を参照). 以下で対応しているエンジンの一覧を表示できる.
names(knitr::knit_engines$get())
また, 新たにプログラムを追加することもできる. 詳細は RDG Ch. 2.7 Other language engines を参考に.
TODO: 他の言語のプログラムを実行する際の注意点
プログラムで数式を生成する
プログラムチャンクは, 単にプログラムの計算結果を埋め込むだけでなく, 静的なコンテンツを臨機応変に変更して出力させたり, あるいは手作業でやるには煩雑な加工処理を挟んでから表示させるのに役に立つ.
R のプログラムと組み合わせることで回帰分析の結果の数値をコピペすることなく数式で表示することができる. そのためには equatiomatic パッケージの extract_eq() を使う.
まずは, 回帰係数を記号で表現するタイプ. LaTeX 数式をそのまま出力するため, チャンクオプションに results="asis" を付ける必要があることに注意する.
data(mtcars)
fit <- lm(mpg ~., data = mtcars)
extract_eq(fit, wrap = T, ital_vars = T, align_env = "aligned")
さらに use_coef = T で係数を推定結果の数値に置き換えた.
extract_eq(fit, wrap = T, ital_vars = T, use_coef = T, align_env = "aligned")
equatiomatic パッケージは現時点では lm glm に対応しており, lmer への対応も進めているようだ.
TODO: この書き方だと PDF で付番できない
プログラムを使った図の挿入
既に Markdown 記法による図表の挿入方法を紹介したが, プログラムチャンクを介して画像を読み込み表示させることもできる. まずは, R のプログラムで既存の画像ファイルを表示させる方法.
knitr::include_graphics(file.path(img_dir, "Johannes_Gutenberg.jpg"))
もちろんのこと既存の画像だけでなく, データを読み込んでヒストグラムや散布図などを描いた結果を画像として掲載することもできる.
技術文書や学術論文では, 画像の上か下に「図1: XXXXX」のようなキャプションを付けることが多い. 紙の書籍では絵本のように本文と図の順序を厳密に守るより, 余白を作らないよう図の掲載位置を調整する必要があるからだ.
プログラムチャンクにはこのキャプションを入力するオプション fig.cap があるため, plot() 側でタイトルを付けないほうが良い. 例えば ggplot2 パッケージの関数を使い以下のようなチャンクを書く[^standard-graphics].
`r ''````r
data("diamonds")
diamonds <- diamonds[sample(1:NROW(diamonds), size =), ]
ggplot(diamonds, aes(x=carat, y=price, color=clarity)) +
geom_point() +
labs( x = "カラット数", y = "価格") + scale_color_pander(name = "クラリティ") +
theme_classic(base_family = "Noto Sans CJK JP") + theme(legend.position = "bottom")
`r ''````
実際の表示は図 \@ref(fig:plot-sample) のようになる.
data("diamonds")
diamonds <- diamonds[sample(1:NROW(diamonds), size =), ]
ggplot(diamonds, aes(x=carat, y=price, color=clarity)) +
geom_point() +
labs( x = "カラット数", y = "価格") +
scale_color_pander(name = "クラリティ") +
theme_classic(base_family = "Noto Sans CJK JP") +
theme(legend.position = "bottom")
ggplot2 以外のパッケージや言語, たとえば tikz や asymptote, DOT言語も使用できる. これらは \@ref(advanced-graph) 章で紹介する.
(WIP): デフォルトフォントの設定
Windows や Mac では, デフォルトのフォントが日本語グリフを持たないのでグラフが文字化けする. 現時点では最低限 rmdja::set_graphics_font() という関数を呼び出す処理を手動で書き加えなければならない. 本文のフォントと異なり, 現時点 (ver. 0.4.2) では手動設定が必要になる. OSごとのフォント名を調べて指定するのが大変なら, 私が作成した fontregisterer パッケージを使うのも1つの手である. その解説は『おまえはもうRのグラフの日本語表示に悩まない (各OS対応)』に書いた通りである. get_standard_font() で使用中のOSで標準インストールされているセリフ (明朝), サンセリフ (ゴシック) のフォントファミリ名を1つづつ取得するので, その値のどちらかを rmdja::set_graphics_font() に与えれば, ggplot2 および標準グラフィックスのデフォルトのフォントが日本語対応フォントになる.
しかしこの関数は ggplot2 のデフォルトのテーマを更新するだけなので ggthemes パッケージなどが用意するテーマプリセットを使用したい場合はその都度設定が必要である.
require(fontregisterer)
theme_set(ggthemes::theme_pander(base_family = get_standard_font()$serif))
ggplot(DATA, aes(...)) + geom_point() + ... +
theme_economist(base_family = get_standard_font()$sans)
TODO: 図のレイアウト設定
PDF ならばフロート設定のため, 図が離れた位置に配置されることがある. そのため, 「図 \@ref(fig:plot-sample)」 のような相互参照を使うと良いだろう. フロートを使うかどうかは, 後のセクションで解説する TODO
Rのグラフィックデバイスを使っている限り, 通常のRのコンソールと同じコードをチャンク内に書くだけで表示できる.
R のグラフィックデバイスではないとは, RGL や plotly など外部ライブラリに頼ったグラフ作成ツールのことである. 判断できない人は, RStudio 上で実行して, "Plots" ペーンに表示されたら R のグラフィックデバイス, "Viewer" ペーンに表示されたらそうでない, で覚えていただきたい. 後者を表示する方法は \@ref(webapp) 章で後述する. R をこれまで使ったことがなく, それすらも何を言っているのか分からない, という場合は ggplot2 を使ってもらう.
最後の fig.cap="" がキャプションである. ただし, どうも日本語キャプションを書いたあとに他のチャンクオプションを指定するとエラーになるようだ. よって fig.cap= はオプションの末尾に書くべきである. また, fig.cap="" に数式や一部の特殊なテキストを直接入力することができない. この問題は相互参照について解説するセクション \@ref(crossref) で詳細を述べる.
fig.cap 以外のオプションはおそらく頻繁には変えないため, 冒頭でまとめて設定したほうが楽だろう.
knitr::opts_chunk$set(
fig.align = "center",
fig.width = 6.5,
fig.height = 4.5,
out.width = "100%",
out.height = "100%"
)
なお, これらは rmdja でのデフォルト値であるため, 実際にこの値をあえて記述する必要はない.
ここで, fig.width と out.width の違いも述べておく. out.width/out.height は表示する画像サイズの違いで, fig.width/fig.height はプログラムが出力した画像の保存サイズである. よって ggplot2 などを使わず画像ファイルを貼り付けるだけの場合は fig.* は意味をなさない.
[^standard-graphics]: なお, Rユーザーならば標準グラフィック関数である plot() 関数をご存知だろうが, 本稿では基本的により便利な ggplot2 パッケージを使用してグラフを作成している.
R プログラムを使った表の装飾
Markdown 記法を使った表記は既に紹介した. しかしこれは表の数値を全て手動で書かなければならない. R はテーブル状のデータ処理に長けているため, このような煩雑さを省くことができないか, とあなたは思っていないだろうか. もちろん R Markdown では R での作業中に使用しているデータをいちいち手書きなどせずとも表示できるし, テーブルのデザインもある程度自由に設定できる.
R Markdown のデフォルトでは R のコンソールと同様にテキストとして出力されるが, rmdja では異なるデザインで表示されている. これは knitr, kableExtra パッケージなどで事後処理をかけることで見やすいデザインの表に変換しているからである. R Markdown の基本ルールとして, チャンク内で最後に呼び出したオブジェクトが表示される. 例えば mtcars というRが用意する練習用データフレームを, チャンク内で上から10行までを呼び出してみると, 以下のように表示される.
data(mtcars)
mtcars[1:10, ]
これはRのコンソール出力と同じで, プレーンテキストでの出力である. 表として出力する最も簡単な方法は, フォーマット関数に df_print を指定することである. たとえば df_print: kable を指定すると, 表 \@ref(tab:df-print-kable) のようになる.
output: ...:
df_print: kable
mtcars[1:10, ]
kbl(mtcars[1:10, ], caption = "`df_print: kable` の場合", escape = F, format = "pandoc", booktabs = F)
このオプションは R Markdown の処理中にデータフレームの呼び出しを検出し, df_print のオプションに対応したスタイルを変換する関数を適用している. 他のオプションとして, tibble, paged などがあるが現時点の rmdja では大差がないので詳細な説明を省略する (図 \@ref(tab:df-print-ops)).
Table: (#tab:df-print-ops) df_print のオプション一覧
オプション 効果
default print(), コンソール出力と同じ
tibble tibble 対応版 print()
paged rmarkdown::paged_table() による表示, これもオプション引数を指定しなければ大差なし
kable knitr::kable() による表スタイル
よって, これらの関数をチャンク内で呼び出すことで, 手動で表のスタイルを指定することも可能である. 表のスタイルにこだわりたい, 相互参照やキャプションを付けたい, といった場合はこれらのうち knitr::kable() 関数を手動で使うのが1つの手である. 実は, 先ほどの df_print の例も, 実際にはこの関数を呼び出して出力している. この場合, 表のキャプションは kable() 内で指定できる (現時点では, 図とは異なりチャンクオプションではキャプションを指定できない). デフォルトでは caption = の文字列はそのまま出力されるため, 太字強調など Markdown 記法も変換されずそのまま表示されてしまう. これには対処方法がいくつかある.
rmdja パッケージの提供する knitr::kable() または kableExtra::kbl() 関数のラッパを使用する (表 \@ref(tab:display-dataframe-kable-booktabs))escape = F および format = "pandoc" を指定する- (非推奨) HTML と PDF でそれぞれの構文で表を描く処理を自分で書く
rmdja::kable(mtcars[1:10, ], caption = "`booktabs = T` は PDF にのみ影響する", booktabs = T)
(1) の方法が現在最も簡単である. ただし, r rmdja::texlogo("LaTeX") の構文が評価されなくなるため同時に使うことはできない. 例えば太字強調と数式を両方表示したい場合は, knitr::is_latex_output() PDF の場合は完全に r rmdja::texlogo("LaTeX") で, HTML の場合は Markdown で書く, という場合分けを自分で書いて knitr::kable() に与えなければならない(表 \@ref(tab:kable-caption-example)). また, キャプションではなく表内の markdown 構文も評価されない. 表内の markdown 構文を PDF でも反映するには, (2) の方法が必要である.
TODO: この仕様は使いづらいのでそのうちなんとかしたい.
(2) についても, kable() 単体であれば問題ないが, 後に紹介する kableExtra パッケージを併用すると書式設定がうまく反映されなくなることがある. (3) は表 \@ref(tab:kable-caption-example) の記述をキャプションだけでなく, HTML ならば Markdown または HTML タグで, PDF ならば r rmdja::texlogo("LaTeX") で表全体を書き分ける, という方法である. 1つの表を描くのに多大な労力がかかるため推奨しない.
cap <- if(knitr::is_latex_output()) "数式 $a$ と \\textbf{太字}" else "数式 $a$ と **太字**"
kable(
head(mtcars),
caption = cap,
booktabs = T
)
さらに, デフォルトでは kable() が PDF に出力する表のデザインはあまりよろしくないが, kable() 関数は過剰な罫線のない表の出力も簡単である. r rmdja::texlogo("LaTeX") を使ったことのある人は知っているかもしれないが, これは booktabs.sty を使った表のスタイルになっている^[もし何らかの理由でこのスタイルにならない, あるいはあえてしたくない, と言う場合は kable() 関数で booktabs = T を指定せよ.].
また, kable() を使う利点として, 表の絡む名に好きな名前を与えられるというものがある. データフレームの列 (変数) 名は, 括弧などプログラミングで特別な意味を持つ文字を使うことができない. そこで, kable() の col.names 引数に表のカラム名を改めて与えることで, こういった文字も出力できる.
kable() による表のスタイルは kableExtra パッケージを使うことで様々にカスタマイズできる. 例えば HTML 版ではデフォルトで奇数偶数行の背景色が異なるが, PDF ではそうなっていない. また, 図表の位置は常にフロートであり, 余白ができにくいように表示位置が前後する (これは技術文書や学術論文では普通のことだが). さらに, 表が本文の領域からはみ出しており見栄えが悪い. これらの設定をHTML版に近づけたい場合は kableExtra::kable_styling() を使って簡単にデザインを変えることができる (表 \@ref(tab:display-dataframe-kable-2)). 以下のように, full_width は表の幅を本文幅にそろえるオプションである. や十分に幅の小さい表に対しては逆に間延びして見づらいためデフォルトでは無効となっているが, このようにして表幅を調整するのに使える. さらに latex_options は PDF にのみ有効なオプションである. "striped" が奇数偶数の色分け[^tabu-error], "hold_position" が表示位置を「なるべく」固定するオプションである (それでも表示位置が大きくずれて気に入らない場合 "HOLD_position" を代わりに使うとよい). ただし HTML と違い PDF では改ページがあるためこのオプションを多様すると, 以下のように本文に無駄な余白が増えることに注意する.
rmdja::kable(
mtcars[1:10, ], booktabs = T,
caption = "奇数行を強調し, PDF では `booktabs` を利用"
) %>%
kable_styling(
full_width = if(knitr::is_latex_output()) T else NULL,
latex_options = c("striped", "hold_position"))
このように, R Markdown ではまず表示したい表と同じ構造のデータフレームを作ることで, 簡単にスタイルの調整された表を掲載できる.
他にもいくつか表のスタイルをカスタマイズするためのパッケージが存在する. より発展的な表のスタイル指定方法については \@ref(advanced-tabulate) 章で話す.
[^tabu-error]: ただし, full_width = T を指定した時, striped, あるいは他の色の指定の命令が反映されないことがある. これは 2019年時点での tabu.sty の不具合であるため, Issues #1 で配布されている開発者によるパッチを適用しなければならない.また, それ以外にも表の幅を調整する方法がある. 詳細は \@ref(advanced-tabulate) 章を参考に.
相互参照と引用
相互参照 {#crossref}
図表や式へのアンカーリンク
図, 表, 式などに番号を自動で割り当て, さらにハイパーリンクを付加できる. \@ref(ID) を使う. 現状では refstyle や prettyref のように接頭語を自動で付けてくれないが, そのうちなんとかなるかもしれない.
bookdown の相互参照は, LaTeX の prettyref.sty のように, 接頭語:参照ID という記法になる. 参照IDは通常, チャンクIDと同じである. 既に紹介したように, 数式参照の接頭語は eq で, 定理は thm である. 図表は fig, tab. その他の接頭語は BKD Ch. 2.2 Markdown extensions by bookdown を参考に.
表への相互参照
Markdown 記法で表を書く場合, 以下のように Table: の直後にラベルを記入する (表 \@ref(tab:tab-md)).
Table: (\#tab:tab-md) Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
------------- ------------ ------------- ------------
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
Table: (#tab:tab-md) Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
章への相互参照
章見出しへの相互参照も可能である. これはPandocの機能を利用しているため, 接頭辞は不要である. Pandocの仕様により欧文であればタイトルがそのまま参照IDとなるが, 非欧文の文字に対して適用されないため, 基本的に日本語文書の場合は参照したい章の見出しの後にスペースを入れて {#参照ID} と書く必要がある. そして本文中で参照する場合 \@ref(参照ID) と表記する.
特殊な相互参照
チャンクオプションの fig.cap などに TeX 数式を書いても正しく表示できない. そのような場合は ref 参照を使う. (ref:figcap1) \coloremoji{🌸} $\sum \oint \mathfrak{A} \mathscr{B} \mathbb{C}$ \coloremoji{🌸} と書くと, 図 \@ref(fig:caption) のキャプションにも特殊な記号が使える.
(ref:figcap1) \coloremoji{🌸} $\sum \oint \mathfrak{A} \mathscr{B} \mathbb{C}$ \coloremoji{🌸}
なお, 複数指定する場合は連続させず, 改行で1行空けて宣言する必要がある.
ggplot(tibble(x = 1, y = 1, z = "テスト")) + geom_label(aes(x = x, y = y, label = z)) + theme_classic()
この参照は一度しか使えない.
PDF での表示では, 図 \@ref(fig:caption) のキャプションの外側が文字化けしていることだろう. これは絵文字出力に関する問題で, 別のセクションで解説する.
これはかなり強力で,
- 定義される前の行にも適用される
- チャンクオプションだけでなく出力結果にも適用される
という仕様である.
TODO: 自己言及的な文章は書かないならこれくらいの認識でいいだろうが, より正確な話はどうするか
文献引用 {#bibliography}
YAMLフロントマターの biblography: に文献管理ファイル (.bib, .json 等) を指定することで, ファイルに含まれる文献への参照が可能になる. @引用ID で本文に引用を与えられ, 文書に引用した文献の一覧が自動で生成される. また, citr パッケージにより, RStudio Addins に文献に対応する引用IDを取り出して挿入する機能が追加される.
(ref:citr-caption) citr パッケージの例
knitr::include_graphics(file.path(img_dir, "citr.png"))
一方で, この記述が文書においてどのようなスタイルで出力されるかは文献引用を処理するプログラムによって変化する. そのプログラムには3つの候補がある. R Markdown の文献引用は pandoc を経由して処理され, 現時点では pandoc-citeproc (default), r rmdja::texlogo("BibTeX") (natbib), r rmdja::texlogo("BibLaTeX") (biblatex) の選択をサポートしている. pandoc-citeproc 以外はもともと r rmdja::texlogo("LaTeX") 用に作られたため, HTML では常に pandoc-citeproc で処理される. PDF ではそれに加えて bibtex, biblatex を指定することもできる. (default とは別なのでややこしいが) rmdja はデフォルトでは PDF 出力時に biblatex を使用する. これはフォーマット引数の citation_package で変更できる. 正確には以下の3つの値のどれかを指定する.
default: pandoc-citeproc を使用する.biblatex: r rmdja::texlogo("BibLaTeX") を使用する. デフォルト. スタイルのデフォルトはこちらが用意した jauthoryear というもの.natbib: r rmdja::texlogo("BibTeX") を使用し, 本文中の参照には natbib.sty が使われる[^natbib-contraint]. ただし, 日本語 (マルチバイト文字) の含まれる文献情報を出力する場合は特殊な設定をしないと製本処理がハングアップする (後述).
[natbib-contraint]: ただし citeit, citep など natbib.sty の提供していた多様な引用子オプションは使えない. これは pandoc の制約によるものである.
文献引用スタイルのカスタマイズ
rmdja では, 本文中の引用トークンのデフォルト設定を, 文書タイプでは「著者-年」形式に, スライドでは番号形式にしている. このカスタマイズについて簡単な解説をする. 従来の R Markdown ではカスタマイズに以下のようなYAMLフロントマター項目を使っていた.
biblio-style: PDF用スタイルファイルnatbiboptions/biblatexoptions: それぞれ natbib または biblatex を使う場合のスタイルに関するオプション csl: CSL用スタイルファイル
, biblio-title: 「参考文献」タイトルの文字列
このうち biblio-style, natbiboptions, biblatexoptions はフォーマット関数で指定する. 例えば以下のように.
output:
rmdja::pdf_book_ja:
citation_package: biblatex
citation_options:
- style=jauthoryear
- natbib=true
これは pandoc の記法を利用した従来のR Markdown で以下のように書いているのと同様であり, citation_package: natbib ならば biblatexoptions が natbiboptions に置き換わる.
output:
....:
citation_package: natbib
biblio-style: jauthoryear
biblatexoptions:
- natbib=true
2通りの記法が存在するのはやや混乱するかもしれないが, 後方互換性を考慮し rmdja ではこれらの2通りの記法どちらでも受け付けるようにしている.
biblatex 以外のエンジンで出力したい, 例えば指定された .bst のスタイルで文献一覧を出力したい場合は, (u)r rmdja::texlogo("pBibTeX") が必要になる. その操作の詳細は \@ref(biblio-advaneced) 章を参照.
文献リスト生成エンジンの違いについて
pandoc-citeproc, bibtex, biblatex はそれぞれ引用文献リストのスタイルを記述するファイルがあり, それぞれ拡張子は .csl, .bst, .bbx/.cbx, である. .csl は MS Word のスタイルと同じもので, XMLで記述されている[^CSL-editor]. .bst は r rmdja::texlogo("BibTeX") 用のフォーマットで, 自分で改造するには逆ポーランド記法の構文に慣れねばならない. そして r rmdja::texlogo("BibLaTeX") はスタイルを r rmdja::texlogo("LaTeX") のマクロで記述でき, さらにそういった細かい記述のスタイルファイルを用意しなくとも指定できるオプションがいくつか存在する(ここまで, 表 \@ref(tab:biblio-comparison)).
現バージョンでは biblatex がデフォルトである. 現在の日本語圏の r rmdja::texlogo("LaTeX") 使用者にとっては .bst ファイルの種類が充実しているため natbib を使いたいところだが, R Markdown の場合エンジンが r rmdja::texlogo("BibTeX") であるため日本語が使えない. (u)r rmdja::texlogo("pBibTeX") を使うにはやや複雑な手順が必要である. よって, デフォルトでそのような下準備をさせるべきでないと考えたので rmdja では biblatex をデフォルトとし, 日本語表示に最低限のスタイルだけを用意している.
tibble(
`item` = as.character(lapply(c("`pandoc-citeproc`", "`biblatex`", "`bibtex`"), function(x) if(is_latex_output()) commonmark::markdown_latex(x) else x )),
`HTML` = c(T, F, F),
`PDF` = c(T, T, T),
`日本語` = c(T, T, F),
`指定名` = as.character(lapply(c("`default`", "`biblatex`", "`natbib`"), function(x) if(is_latex_output()) commonmark::markdown_latex(x) else x)),
`文献ファイル` = c(".json", ".bib", ".bib/.bibtex"),
`文献スタイル` = c(".csl", ".bbx/.cbx", ".bst")
) %>% kable(caption = "引用プログラムごとの違い", booktabs = T, escape = F) %>%
kable_styling(full_width = F)
[^CSL-editor]: 簡単なカスタマイズなら CSL editor というWebサービスでできる. しかしあくまでXMLなので, あまり複雑な処理はできないことに注意する.
(WIP) 簡単なレイアウト・スタイル変更
前章では文書の内容に関する構文を紹介した. ここでは, 文書全体のデザインやスタイルの設定方法のうち, rmdja が用意している簡単なものを紹介する.
フォント変更
フォント変更の方法は HTML と PDF で大きく違う. まずは HTMLについて. _output.yml にはデフォルトのフォントを設定できるが, 選択肢は sans と serif しかない.
output: rmdja::gitbook_ja:
config:
fontsettings:
family: serif
しかし HTML は文字通りHTMLで出力しているため, CSS の使い方次第でいくらでもデザインを変えることができる. 例えば自作した CSS ファイルを以下のように指定できる.
output:
output: rmdja::gitbook_ja:
css: ABC.css
PDF を生成する場合, ver 0.3 以降ではデフォルトのフォントファミリを OS に応じて変えている. もし変更したい場合はYAMLフロントマターの以下の項目を変更する
mainfont: 欧文セリフフォントファミリsansfont: 欧文サンセリフフォントファミリmonofont: 等幅フォントファミリ (コードの表示などに使用)jfontpreset: 和文フォントファミリのプリセットjmainfont: 和文メインフォントファミリ (一般に明朝体を指定)jsansfont: 和文セリフフォントファミリ (一般にゴシック体を指定)jmonofont: 和文等幅フォントファミリ (コードの表示などに使用)
jfontpreset は zxjafont または luatex-ja によるプリセットで, 3種類の和文フォントを一括指定できる. 個別指定したフォントはこれを上書きする. 特にこだわりがないなら一括指定で良いが, ソースコードを多く掲載する場合は M+ や Ricty などのフォントを用意すると良いだろう. rmdja ではデフォルトで3種類の和文フォントファミリに対して, OSごとの標準日本語フォントが選択される (図 \@ref(tab:japreset-default)). いずれも各OSで標準でインストールされているはずであるが, 現時点ではフォントが実際にインストールされているか確認する機能はない.
data.frame(
Mac = c("游書体", "ヒラギノ ProN"),
Linux = rep("Noto", 2),
Windows8 = rep("游書体", 2),
Windows_old = rep("MSフォント", 2), row.names = c(rmdja::texlogo("XeLaTeX"), rmdja::texlogo("LuaLaTeX"))) %>%
kable(row.names = T,
col.names = c("Mac", "Linux", "Windows (8以降)", "Windows (それ以前)"),
caption = "デフォルトで使用される日本語フォントファミリ",
booktabs = T, escape = F, format = "pandoc")
それ以外で使用可能な主なプリセット名は表 \@ref(tab:japreset-list) の通り. これらは r rmdja::texlogo("XeLaTeX"), r rmdja::texlogo("LuaLaTeX") でそれぞれ zxjafont.sty, luatex-ja.sty を利用してフォントが埋め込まれる. 両者の多くではプリセット名が共通しているが, 一部例外もあることに注意 (特に r rmdja::texlogo("XeLaTeX") は luatex-ja との互換性を考慮してエイリアスをいくつも用意している). また, より詳細な一覧やオプションの全貌については, ⼋登崇之氏の『PXchfon パッケージ』および zxjafont のマニュアル と, 『luatex-ja の使い方』を確認してほしい.
parse_latex <- function(x){
if(is_latex_output()) commonmark::markdown_latex(x)
else x
}
tibble(
family = c("MS ゴシック/明朝", "游書体", "ヒラギノ系", "Noto フォント", "源ノ角ゴ/明朝", "原ノ味フォント", "梅フォント", "小塚フォント", "IPA (Ex) フォント"),
XeLaTeX = c("`ms`",
"`yu-win10`",
"`hiragino-pro`",
"`noto`/`noto-jp`",
"`sourcechan-jp`",
"`haranoaji`",
"`ume`",
"`kozuka-pro`",
"`ipa`/`ipaex`"),
LuaLaTeX = c("`ms`",
"`yu-win10`",
"`hiragino-pro`",
"`noto-otf`/`noto-otc`",
"`sourcehan-jp`",
"`haranoaji`",
"`ume`",
"`kozuka-pro`",
"`ipa`/`ipaex`"
),
details = c(
paste(rmdja::texlogo("XeLaTeX"), "のみ HGフォントと併用する", if(is_latex_output()) "\\texttt{ms-hg}" else "`ms-hg`", "などのバリエーションあり"),
parse_latex("Windows 8 以前は `yu-win`, Mac では `yu-osx`"),
parse_latex("`hiragino-pron` で ProN/StdN版を指定"),
"",
"",
"",
"",
parse_latex("`-pr6` で ProVI版, `-pr6n` で Pro6N版を指定なども指定可能"),
paste(rmdja::texlogo("XeLaTeX"), "のみ", if(is_latex_output()) "\\texttt{ipa-hg}" else "`ipa-hg`", "などのバリエーションあり")
)
) %>%
mutate(across(c(XeLaTeX, LuaLaTeX), ~if(is_latex_output()) map_chr(.x, commonmark::markdown_latex) else .x)) %>%
kbl(caption = "主な指定可能なフォントプリセット名",
booktabs = T, escape = F,
col.names = c("フォント", rmdja::texlogo("XeLaTeX"), rmdja::texlogo("LuaLaTeX"), "備考")
) %>%
column_spec(4, width = "10em")
さらに, それぞれの項目に対してオプションを設定する場合, options と接尾辞のついた項目が用意されている. 欧文と和文フォントで全く異なるタイプのフォントを使ったために相対的なサイズが合わず不格好な場合は
mainfont: Palatinno
mainfontoptions:
- Scale=0.9
などと書いて調整できる.
YAML フロントマターの設定によるスタイル変更
RMD ファイルの冒頭に書かれているYAMLフロントマターは様々なことが設定できる. これらのオプションは Pandoc のものに対応している. HTML はスタイルのほとんどが 規格化された CSS で操作できるため, 主に PDF に関するものである. また, 本章はあくまで簡易的な機能解説であるため, より詳細な解説は後の章で再度取り上げる.
ハイパーリンクの配色変更
たとえば PDF では, 以下のようにしてハイパーリンクの色を変更できる.
link-citations: true
linkcolor: blue
citecolor: blue
urlcolor: magenta
まず, ハイパーリンクを有効にする, link-citations:true が必要である. 次に, リンクの種類ごとに色を指定できる. linkcolor は文書内のハイパーリンクの色, citecolor は巻末の参考文献リストへのリンクの色, そして urlcolor は文書外の URL へのリンクの色である.
また, ページのヘッダ・フッタは pagestyle で指定できる.
pagestyle: headings
文書クラスによっても多少変わるが, プリセットが4種類用意されている.
empty: 何も表示しないplain: ページ数のみ表示headings: ヘッダに罫線を引き, ページ数だけでなく章のタイトルも表示するfancy: ユーザによるカスタマイズ (WIP)
(3) が一般的な書籍のものに近いスタイルである. (1-3) は, タイトルページや調整のための白紙ページなどはかならずしも変更されない. そういった根本的な変更がしたい場合のため, (4) が用意されている. しかし, 現時点では fancyhdr.sty の使い方を知る必要がある.
r rmdja::texlogo("LaTeX") エンジンの変更
PDF の出力は rrmdja::texlogo("LaTeX")を使用する. その処理プログラムにはいくつかバリエーションがあり,rmdjaではr rmdja::texlogo("XeLaTeX")とrmdja::texlogo("LuaLaTeX")の使用を想定している (R Markdown ではr rmdja::texlogo("pdfLaTeX")もサポートしているが, これは日本語表示が難しいためrmdja` では採用していない).
両者は多少の違いがある (正確には, 両者それぞれに対応した和文組版パッケージの違いにも由来する).
- 組版の違い.
r rmdja::texlogo("XeLaTeX") で和文組版を制御する zxjatype.sty にはいくつか改善の余地が残っている.
- 速度の違い. 年々改善されているようだが, それでも
r rmdja::texlogo("LuaLaTeX") は処理の遅さが目立つ^[ただし R Markdown に限って言えば R コードの処理時間のほうが問題となることもある. また, r rmdja::texlogo("XeLaTeX") であっても文献処理や索引処理など関連プログラムを多く使用すればそれなりに遅くなる.].
- フォントレンダの違い. 一概に言うのは難しいが, デフォルト設定では文字のウェイトや和文・欧文の相対的なバランスが微妙に異なる.
- 和文・欧文を同時に扱う際の挙動の違い.
r rmdja::texlogo("LuaLaTeX") は和文と欧文の処理ルールが競合する時, 和文の処理を優先する傾向がある. 一方で rrmdja::texlogo("XeLaTeX")(およびzxjatype.sty`) はなるべく両者を共存できるように作られている.
もし和文組版の厳格さを優先したいのなら rrmdja::texlogo("LuaLaTeX")を使うべきである. しかし処理速度があまりに遅いとか, 欧文の扱いが気に入らないとかの場合はr rmdja::texlogo("XeLaTeX") を使うと良い. 特に書籍形式でなくプレゼンテーション資料であれば, 組版ルールの厳格さはあまり気にならないことだろう.
文書クラスのカスタマイズ
デフォルトでは bxjsbook という文書クラスを使用している. この他 rmdja では bxjsreport, ltjsbook, ltjsreport, ljreq という文書クラスに対応している. ただし ljreq は r rmdja::texlogo("LuaLaTeX") でのみ動作する.
LaTeX のカスタマイズ
PDF のデザインを微調整したい場合, 自分で r rmdja::texlogo("LaTeX") のソースに変更を加える必要がある. よってこの機能は r rmdja::texlogo("LaTeX") の使用に慣れたユーザのみが使用してほしい.
r rmdja::texlogo("LaTeX") のソースに変更を加える方法は2つ. 1つは header-includes を使うことである.
header-includes:
- ...
- ...
これでリスト風にプリアンブルを書くことができる. ただし, % を使った改行エスケープは使用できない. もう1つは, 出力フォーマットの includes に設定する方法で, 以下のように命令文ではなく TEX ファイルを指定する.
output: rmdja::pdf_book_ja:
includes:
in_header: i.tex
before_body: b.tex
after_body: a.tex
それぞれ, プリアンブル, 本文冒頭 (document 環境, 表紙や目次等の直後), 本文後に挿入される. しかし, TEX ファイルの大枠は Pandoc のテンプレートファイルで決まっているため競合することもある. よってテンプレートを確認しながら作る必要がある. テンプレートファイルは Pandoc 独自の簡易なマクロが挿入されている以外は通常の r rmdja::texlogo("LaTeX") ソースと同じである^[現時点では日本語版ユーザーガイドでも未翻訳のパート. しかし if, for 文など簡単な制御構文しかないため, 結局 r rmdja::texlogo("LaTeX") のマクロを使うことが多いだろう. https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html#templates, https://pandoc.org/MANUAL.html#templates].
テンプレートファイルは R で以下を実行して得られるディレクトリにある. beamer-ja.tex.template は beamer 用, document-ja.tex.template はそれ以外の文書用である.
system.file("resources/pandoc-templates", package = "rmdja")
テンプレートを修正しなければ意図した変更ができない場合, 以下のようにして別のテンプレートファイルを指定できる.
output: rmdja::pdf_book_ja:
template: new-file
チャンク/コードおよび出力ブロックのスタイルの一括変更
すでに書いたように, コードブロックのシンタックスハイライトはいくつかのプリセットを適用できる. また, チャンクオプションにはいろいろなものがあり, それらは全て, knitr::opts_chunk::set() で以降のチャンクに対して一括して適用できる. 詳細は https://yihui.org/knitr/options/#code-decoration などを見てもらうとして, いくつかを抜粋する. YAMLフォーマットと違い, チャンクオプションは全て R のコードとして評価されるため, 論理値は TRUE/FALSE または T/Fと表記すること.
highlight: シンタックスハイライトを適用するかどうか.background: コードブロックの背景色. デフォルトは #F7F7F7 つまり灰色である.tidy, tidy.opts: コードの自動整形を適用するかどうかと, そのオプション. rmdja のデフォルト設定では styler パッケージを使用している. 詳しくは付録 \ref(autoformatter) を参照.prompt: コードブロックにプロンプト記号 > を表示するかどうかcomment: 出力ブロックの行頭に表示する記号. デフォルトは ##size: 出力ブロックのフォントサイズindent: 出力ブロックのインデント
行番号の表示
行番号の表示は attr.source = c(".numberLines", .lineAnchors") を指定する.
rmdja で提供するフォーマットでは, `YAML フロントマターで一括して行番号を表示することを指定できる.
output: rmdja::pdf_document_ja:
add_rownumber: true
このオプションは上記のチャンクオプションのデフォルト値を変更するものである. よって, これを設定した状態で任意のコードブロックの行番号を非表示としたい場合は逆にチャンクオプション attr.source = NULL を指定する.
コードブロックのページまたぎ禁止
長いソースコードを掲載するとページまたぎが発生する. 現時点では, rmdja の機能としてコードブロックに個別にページまたぎを許可・禁止を指定する機能はない (Pandoc の基本機能の範囲でサポートされていないため) が, 一括で指定することはできる. 例えば
header-includes:
- \@ifpackageloaded{fvextra}{}{\usepackage{fvextra}}
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\},breaklines,breakanywhere,samepage=true}
と書く. ただし直接関係あるのは samepage=true だけである. これはテンプレートの記述を上書きするという乱暴な方法なので, 他のデフォルトオプションも混在している. commandchars=\\\{\} はシンタックスハイライトに関する設定で, 基本的に消すべきでない. breaklines は行途中の折り返しを許可するもの, breakanywhere はどこでも行の折り返しを許可するというもので, いずれもデフォルトのコード自動整形と関係がある. ちなみに TEX ファイルを開いて highliting 環境に個別に samepage=true オプションを指定すれば個別に折り返しを禁止できる.
(WIP) rmdja による文書作成支援機能
クリエイティブ・コモンズの表記
Web公開する文書ならばクリエイティブ・コモンズの表記をつけたいところだ. 公式サイトで毎回発行するのは面倒なので表示する関数を用意にした. ハイパーリンクも付けるようにしている. チャンクでは results="asis" オプションが必要になる. また, 通常は echo=F を設定すべきだろう. 冒頭の表記もこれで作成している. もちろんそれぞれの媒体に対応している.
文言の生成は未対応
ルビ表記
ルビはおそらくCJK言語など一部の言語でしか使われていない (アラビア語とかヘブライ語とかの補助記号は詳しく知らないが多分グリフとしてサポートされてるっぽいので無視) ため, ルビ表記も R Markdown ではサポートされていない. そこで簡単にルビを表示できる関数 rmdja::ruby() を用意した. インライン実行で使う. PDF での配置は pxrubrica.sty を利用したグループルビである. よって, 1字ごとに配置 (モノルビ) にしたいとか, 突出指定とか, 細かいことはHTMLタグやCSSやLaTeXコマンドを自分で書く. 妥協案として, 1字ごとに呼び出す手もある.
グループルビの例: とある科学のr rmdja::ruby("超電磁砲", "レールガン"), r rmdja::ruby("皇帝", "カイザー")ラインハルト, r rmdja::ruby("柊館", "シュテッヒパルムシュロス"), r rmdja::ruby("黒色槍騎兵", "シュワルツ・ランツェンレイター"), r rmdja::ruby("喜連瓜破", "きれうりわり"), , r rmdja::ruby("MEXICO", "メキシコ")
分割して出力した例: r rmdja::ruby("喜", "き")``r rmdja::ruby("連", "れ")``r rmdja::ruby("瓜", "うり")``r rmdja::ruby("破", "わり"), r rmdja::ruby("黒色", "シュワルツ")``r rmdja::ruby("槍騎兵", "ランツェンレイター") ,
TODO: それ以外にも便利機能を少しづつ増やしていく予定
Gedevan-Aleksizde/rmdja documentation built on Sept. 28, 2021, 2:49 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
(PART) R Markdown と Bookdown の基本機能 {-}
このパートの概要 {-}
ここではまず, R Markdown の基本的な機能を紹介する. つまり bookdown 特有のものではなく, R Markdown 全般で使用できる機能も含めて紹介する. これ以降は自己言及的な説明が多いため, この文書を生成しているソースコードと比較しながら確認することをおすすめする. ここで紹介する機能は BKD, RDG, RCB での記述に基づく.
これら3つのドキュメントを読めば, ほとんどのことは可能になる --- rmdja を作る理由になった LaTeX テンプレートの修正以外は --- のだが, 本稿の重要な目的の1つは複数のファイル形式をなるべく簡単に両立することであるので, それができない書き方には触れないし, 技術文書の作成にあまり使わないような機能の動作確認はおこなわず, 技術文書作成で頻繁に使われ, 便利と思える機能のみ紹介する.
どちらにしろそのうちこれらを翻訳してくれる人が現れることだろう...たぶん.
静的なコンテンツの作成
まずは, 単なるマークアップ, つまりプログラミングの複雑な処理を考えなくても良いタイプの, 簡単な構文を紹介する. それらの多くは一般的な Markdown のものと同じである.
日本語で書かれた資料でごく基本的なことについて, 『R Markdown入門』で一通り紹介されている. やや応用的なことも 『R Markdown ユーザーののための Pandoc's Markdown』に書かれている.
Markdown の基本構文
一応基本の Markdown の構文も挙げておく. 詳細は(ref:BKDB)"Ch. 2.2 Markdown Syntax" を参照.
インラインでの書式変更
テキストの一部のみ書式を変える
アンダースコアで強調 (イタリック)
_underscore_
underscore
** 2つで太字強調
**太字強調**
太字強調
等幅フォント
`bookdown` と `rmdja`
bookdown と rmdja
本文中に入力した URL は自動判別され, ハイパーリンクが付けられる. また, [テキスト](URL) という書式で, テキストに対してハイパーリンクを付けることができる.
URL は自動判別される: https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja [`rmdja` の github リポジトリ](https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja)
URL は自動判別される: https://github.com/Gedevan-Aleksizde/my_latex_templates/tree/master/rmdja
ブロック要素
以降は行内では使えず, 適切に表示するには前後に改行を挟む必要のあるタイプの構文である.
まず, 引用ブロックを使えばかっこいいエピグラフを書き放題である.
> Нужны новые формы. Новые формы нужны, а если их нет, то лучше ничего не нужно.
>
> 新しいフォーマットが必要なんですよ. 新しいフォーマットが. それがないというなら, いっそ何もないほうがいい.
>
> `\r tufte::quote_footer('--- A. チェーホフ『かもめ』')`
Нужны новые формы. Новые формы нужны, а если их нет, то лучше ничего не нужно.
新しいフォーマットが必要なんですよ. 新しいフォーマットが. それがないというなら, いっそ何もないほうがいい.
r tufte::quote_footer('--- A. チェーホフ『かもめ』')
rmdja では, HTML と PDF 両方で同様のデザインの枠で表示するようにしている.
Markdown では # は見出しを意味するが, bookdown にはさらにオプションが用意されている.
# 見出し名 {-} で, セクション番号のつかない見出しを用意できる. 序文, 章末の参考文献, 付録のセクションに使えるだろう. さらに, bookdown では # (PART) 見出し名 で「部」の見出しを作ることができる. この見出しは セクションの合間に挟まるが, 選択することはできない. 文書が長くなったときに, より大きな区切りを付けるのに役に立つだろう. さらに, # (APPENDIX) 見出し名 {-} で, 以降の見出しの頭に 「補遺 A, B, C, ...」と付番できる.
箇条書きは以下のように書ける.
* iris setosa * iris versicolor * iris virginica
- iris setosa
- iris versicolor
- iris virginica
1. iris setosa 2. iris versicolor 3. iris virginica
- iris setosa
- iris versicolor
- iris virginica
インデントを使えばネストできる.
- 課長
- 課長補佐
- 課長補佐代理
- 課長補佐代理心得
Markdown を使った図表の挿入
markdown は表を記入することもできる.
Table: Markdown 記法の表 Sepal.Length Sepal.Width Petal.Length Petal.Width ------------- ------------ ------------- ------------ 5.1 3.5 1.4 0.2 4.9 3.0 1.4 0.2 4.7 3.2 1.3 0.2 4.6 3.1 1.5 0.2 5.0 3.6 1.4 0.2 5.4 3.9 1.7 0.4
Table:Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
画像ファイルも貼り付けられる.
{ width=50% }
しかし, キャプションを付けたり, 表示位置やサイズを細かく調整したり, 注釈を付けたりするためには, 後述するようにRプログラムを経由して出力したほうが良い.
TODO: md 記法で画像貼り付けたときのサイズ統一
コメントアウト
HTML 式の <!-- --> でコメントアウトできる. コメントアウトされた箇所は生成ファイルでもコメントアウトされるのではなく, そもそも出力されなくなる.
数式
LaTeX 記法で数式を記述できる. HTML ならば Mathjax によってレンダリングされる. 数式の記述ルールは少々ややこしい. これは現在の pandoc の仕様で HTML および LaTeX の規格で矛盾なく出力するためやむをえない措置である.
- 改行をしない行内数式は
$で囲む, または\(,\)で囲む. - 改行を伴う数式ブロックは
$$で囲む, または\[,\]で囲む. align,equation環境等を使う場合は, 上記の記号を使わず, 直接 LaTeX コマンド\begin{align}...を打ち込む.
\@ref(eq:binom) は二項分布の確率関数である
\begin{align}
f(k) &= {n \choose k} p^{k} (1-p)^{n-k} (\#eq:binom)
\end{align}
その出力は, 以下のようになる.
\@ref(eq:binom) は二項分布の確率関数である
\begin{align} f(k) &= {n \choose k} p^{k} (1-p)^{n-k} (#eq:binom) \end{align}
Bookdown では従来の R Markdown でできなかった数式への付番と, 本文中での参照アンカーリンクの自動作成が可能となっている (詳細は \@ref(crossref) 章で). LaTeX にすでに慣れている読者に注意が必要だが, Bookdown 特有の制約として, 付番したい場合は \label{ID} ではなく (\#eq:ID) を使う. また, PDF (LaTeX) と HTML (Mathjax) の仕様には
- PDF では
alignは常に数式が付番され,align*等はどうやっても付番されない - HTML では
alignでもalign*であってもラベルを書かなければ付番されず, 書けば付番される.
という違いがある. 両者で同じ表示にこだわるのなら, 付番を取り消す \notag を多用することになるだろう.
さらに, bookdown の機能として, LaTeX の「定理」「定義」「証明」などの環境に対応するものが提供されている (参考: BKD Ch. 2.2 Markdown extensions by bookdown). これらの相互参照も可能である.
例: 以下に補題 \@ref(lem:borelcantelli), 定理 \@ref(thm:theorem1) を示す.
```{lemma borelcantelli, name="ボレル-カンテリの補題"} ${E_1,E_2,\cdots}$をある確率空間の事象とする. これらの事象の確率の和が有限であるなら, それらが無限に多く起こる確率はゼロである. つまり,
\begin{align} & \sum_{n=1}^\infty \mathrm{P}(X_n) <\infty \Rightarrow \mathrm{P}\left(\lim_{n\to\infty}\sup X_n\right) = 0,\ & \lim_{n\to\infty}\sup X_n = \bigcap_{n=1}^\infty\bigcup_{k\leq n}^\infty E_k \end{align}
である.
```{proof borelcantelli-proof}
証明は読者の課題とする.
```{theorem theorem1, name="無限の猿定理"} 猿がほとんど確実にタイプライタの全てのキーを無限回叩くならば, ほとんど確実にテキストには任意の作品が含まれる.
```{proof theorem1-proof}
補題 \@ref(lem:borelcantelli) より自明.
カスタムブロック
数式のセクションの定理ブロックの応用で, 独自のブロックセクションを定義することができる. rmdja では BKD Ch. 2.7 Custom blocks で紹介されている例を予め使えるようにしている. それらは type="..." で指定できて, 以下の5種類がある.
cautionimportantmemotipwarning
である.
``{block block-example-caution, type="caution"}
技術書によくある注意を喚起するブロック (caution`).
```{block block-example-important, type="important"}
技術書によくある注意を喚起するブロック (`important`).
``{block block-example-memo, type="memo"}
技術書によくある注意を喚起するブロック (memo`).
```{block block-example-tip, type="tip"}
技術書によくある注意を喚起するブロック (`tip`).
``{block block-example-warning, type="warning"}
技術書によくある注意を喚起するブロック (warning`).
このブロック内では Markdown の基本構文しか使えず, 引用や相互参照などは使えない. これらをブロック内で使いたい場合は `block` の代わりに `block2` と書く. ただしこちらは pandoc の機能のハックであるため, 将来使えなくなる可能性もある. やや煩雑になるが, Pandoc の fenced Div を利用した書き方は, より安全である.
:::{.infobox .important data-latex="{warning}"} fenced Div によるブロック :::
fenced Div によるブロック ::: この構文の意味の解説は『R Markdown クックブック』などを参考に. ## 脚注 脚注はインラインと, 巻末に書く2通りがある. ```markdown ここにインラインで脚注^[脚注の本文]
ここにインラインで脚注^[脚注の本文]
本文は巻末に書く[^example-1][^example-2]. [^example-1]: 脚注の本文その2 [^example-2]: 脚注の本文その2
本文は巻末に書く^example-1.
ここにインラインで脚注[^脚注の本文]
インラインで書くほうがシンプルに見えるが, この記法では間を空けずに連続して脚注を書くことができない.
このように書くと^[脚注その1]^[脚注その2]上付きとして認識される
改行・改頁 (改ページ)・改丁
HTMLやTexをそのまま書く場合と違い, Markdown での改行はそのまま反映されるため, 通常は <br> や \\ などを書く必要はない. HTML の場合, 紙への印刷を想定しないため任意のタイミングで改ページするという考え方はない. Webページの分割は章やセクション単位でなされる. PDF の場合は \newpage, \clearpage, \cleardoublepage という3種類の命令文が用意されている.
\newpageはページを改めるが, 段組の場合は次のページではなく次の段に飛ぶ.\clearpageは段組みでもページを改める. またそれ以前に配置した図表のフロートの配置を確定させる. つまり図表をフロートにしても\clearpageをまたいで位置が変わることはない.\cleardoublepageは次の奇数ページまで飛ぶ (いわゆる改丁). 書籍では通例, 章の始めなどを奇数ページに揃える. なお#で章見出しを書いた場合は自動でこの命令文が適用されるため手作業でこの命令文を書く必要はない.
動的なコンテンツの作成
プログラムチャンク
プログラムチャンクは, R Markdown 最大の特徴であり, R のソースコードや, その実行結果を Markdown に挿入できる. さらには R 以外の言語の動作も可能である. 順番が前後してしまったが, 定理などのカスタムブロックは本来はプログラムを入力するためのチャンクブロックであり, それを静的なテキストコンテンツの挿入に流用しているだけである.
以降は R で多くのユーザが頻繁に使うパッケージと, いくつかの技術文書作成に役に立つパッケージをインポートしている前提の説明とする. なお, rmarkdown, bookdown はチャンク内で特に読み込む必要がない.
pkgs <- installed.packages() for(p in c("tidyverse", "ggthemes", "equatiomatic", "tufte", "kableExtra")){ if(!p %in% pkgs) install.packages(p) } if(!"rmarkdown" %in% pkgs) remotes::install_github("rstudio/rmarkdown") if(!"bookdown" %in% pkgs) remotes::install_github("rstudio/bookdown") require(tidyverse) require(ggthemes) require(equatiomatic) require(kableExtra)
このように, ログを掲載することもできる. これは再現性を重視する際に重宝するが, 一方で単に画像などの出力だけを掲載したい場合もあるだろう. あるいは, プログラムを解説するためにプログラムは掲載するが実行しない, ということも必要になるかもしれない. プログラムと結果の表示/非表示はどちらも簡単に切り替え可能である. そのためには, チャンクオプションを指定する.
echo: プログラムを掲載するかどうかmessage: プログラム実行結果の標準出力を掲載するかどうかwarning: プログラム実行結果の警告を掲載するかどうかerror: プログラム実行結果のエラーを掲載するかどうかeval: 文書作成時にプログラムを実行するかどうかinclude: 文書作成時にプログラムを実行し, かつ掲載しないかどうかresults: 出力をいつもの R の出力風にするか (markup), 隠すか ("hide"), 出力を区切らずまとめるか ("hold"), テキストをそのまま出力するか ("asis"). 最後は R Markdown のソースコードを動的に生成したい場合などに使う.
``{block, type="memo"}
R の論理値はTRUE/FALSEまたはT/F` と書く.
チャンクごとに個別に設定することも, デフォルト値を一括設定することもできる. 前者の場合, チャンクオプションは `{}` 内部にカンマ `,` で区切って書く. `r` は R で実行するという意味である. チャンクの一般的な記法は以下のようになる.
````
`r ''````r
data(cars)
summary(cars)
`r ''````
````
`r` の直後の `<label>` は**ラベル**と呼ばれ, チャンクのIDとしての機能を持つ (省略された場合は自動で適当な名前がつけられる). ラベルは主に後述の図表の相互参照に使われる. ラベルは英数字とハイフンを使って重複しない範囲で自由に命名できる.
一括設定の場合, 以下のようなプログラムでデフォルト値を上書きできる.
```r
knitr::opts_chunk$set(
echo = F,
message = T,
warnings = F,
error = F
)
なおこのチャンクは eval=F を設定することで, 実行されることなくプログラムのみ掲載している. ただし, プログラムのみを掲載するなら, 以下のように Markdown の機能でも可能である. こちらの記法は {} がなくなっていることに注意する.
`r ''````sh echo Hello, Bookdown `r ''````
{} ブロック内の値にはさらに R プログラムで与えることができる. この使い方は後の章で解説する.
これらのオプションがあるおかげでプログラムとその結果の再現を説明したい場合はソースコードも表示させたり, 回帰分析やシミュレーションの結果だけを掲載したい時は結果のみ表示したりできる. これが R Markdown のチャンクの強みである. 例えば Jupyter notebook/lab などは従来, コードセルと出力セルを自由に隠すことができなかった.
チャンクに使用できる言語は R だけではない. つまり Python なども使用できる(詳細は \@ref(python) 章を参照). 以下で対応しているエンジンの一覧を表示できる.
names(knitr::knit_engines$get())
また, 新たにプログラムを追加することもできる. 詳細は RDG Ch. 2.7 Other language engines を参考に.
TODO: 他の言語のプログラムを実行する際の注意点
プログラムで数式を生成する
プログラムチャンクは, 単にプログラムの計算結果を埋め込むだけでなく, 静的なコンテンツを臨機応変に変更して出力させたり, あるいは手作業でやるには煩雑な加工処理を挟んでから表示させるのに役に立つ.
R のプログラムと組み合わせることで回帰分析の結果の数値をコピペすることなく数式で表示することができる. そのためには equatiomatic パッケージの extract_eq() を使う.
まずは, 回帰係数を記号で表現するタイプ. LaTeX 数式をそのまま出力するため, チャンクオプションに results="asis" を付ける必要があることに注意する.
data(mtcars) fit <- lm(mpg ~., data = mtcars) extract_eq(fit, wrap = T, ital_vars = T, align_env = "aligned")
さらに use_coef = T で係数を推定結果の数値に置き換えた.
extract_eq(fit, wrap = T, ital_vars = T, use_coef = T, align_env = "aligned")
equatiomatic パッケージは現時点では lm glm に対応しており, lmer への対応も進めているようだ.
TODO: この書き方だと PDF で付番できない
プログラムを使った図の挿入
既に Markdown 記法による図表の挿入方法を紹介したが, プログラムチャンクを介して画像を読み込み表示させることもできる. まずは, R のプログラムで既存の画像ファイルを表示させる方法.
knitr::include_graphics(file.path(img_dir, "Johannes_Gutenberg.jpg"))
もちろんのこと既存の画像だけでなく, データを読み込んでヒストグラムや散布図などを描いた結果を画像として掲載することもできる.
技術文書や学術論文では, 画像の上か下に「図1: XXXXX」のようなキャプションを付けることが多い. 紙の書籍では絵本のように本文と図の順序を厳密に守るより, 余白を作らないよう図の掲載位置を調整する必要があるからだ.
プログラムチャンクにはこのキャプションを入力するオプション fig.cap があるため, plot() 側でタイトルを付けないほうが良い. 例えば ggplot2 パッケージの関数を使い以下のようなチャンクを書く[^standard-graphics].
`r ''````r
data("diamonds")
diamonds <- diamonds[sample(1:NROW(diamonds), size =), ]
ggplot(diamonds, aes(x=carat, y=price, color=clarity)) +
geom_point() +
labs( x = "カラット数", y = "価格") + scale_color_pander(name = "クラリティ") +
theme_classic(base_family = "Noto Sans CJK JP") + theme(legend.position = "bottom")
`r ''````
実際の表示は図 \@ref(fig:plot-sample) のようになる.
data("diamonds") diamonds <- diamonds[sample(1:NROW(diamonds), size =), ] ggplot(diamonds, aes(x=carat, y=price, color=clarity)) + geom_point() + labs( x = "カラット数", y = "価格") + scale_color_pander(name = "クラリティ") + theme_classic(base_family = "Noto Sans CJK JP") + theme(legend.position = "bottom")
ggplot2 以外のパッケージや言語, たとえば tikz や asymptote, DOT言語も使用できる. これらは \@ref(advanced-graph) 章で紹介する.
(WIP): デフォルトフォントの設定
Windows や Mac では, デフォルトのフォントが日本語グリフを持たないのでグラフが文字化けする. 現時点では最低限 rmdja::set_graphics_font() という関数を呼び出す処理を手動で書き加えなければならない. 本文のフォントと異なり, 現時点 (ver. 0.4.2) では手動設定が必要になる. OSごとのフォント名を調べて指定するのが大変なら, 私が作成した fontregisterer パッケージを使うのも1つの手である. その解説は『おまえはもうRのグラフの日本語表示に悩まない (各OS対応)』に書いた通りである. get_standard_font() で使用中のOSで標準インストールされているセリフ (明朝), サンセリフ (ゴシック) のフォントファミリ名を1つづつ取得するので, その値のどちらかを rmdja::set_graphics_font() に与えれば, ggplot2 および標準グラフィックスのデフォルトのフォントが日本語対応フォントになる.
しかしこの関数は ggplot2 のデフォルトのテーマを更新するだけなので ggthemes パッケージなどが用意するテーマプリセットを使用したい場合はその都度設定が必要である.
require(fontregisterer) theme_set(ggthemes::theme_pander(base_family = get_standard_font()$serif)) ggplot(DATA, aes(...)) + geom_point() + ... + theme_economist(base_family = get_standard_font()$sans)
TODO: 図のレイアウト設定
PDF ならばフロート設定のため, 図が離れた位置に配置されることがある. そのため, 「図 \@ref(fig:plot-sample)」 のような相互参照を使うと良いだろう. フロートを使うかどうかは, 後のセクションで解説する TODO
Rのグラフィックデバイスを使っている限り, 通常のRのコンソールと同じコードをチャンク内に書くだけで表示できる.
R のグラフィックデバイスではないとは, RGL や plotly など外部ライブラリに頼ったグラフ作成ツールのことである. 判断できない人は, RStudio 上で実行して, "Plots" ペーンに表示されたら R のグラフィックデバイス, "Viewer" ペーンに表示されたらそうでない, で覚えていただきたい. 後者を表示する方法は \@ref(webapp) 章で後述する. R をこれまで使ったことがなく, それすらも何を言っているのか分からない, という場合は ggplot2 を使ってもらう.
最後の fig.cap="" がキャプションである. ただし, どうも日本語キャプションを書いたあとに他のチャンクオプションを指定するとエラーになるようだ. よって fig.cap= はオプションの末尾に書くべきである. また, fig.cap="" に数式や一部の特殊なテキストを直接入力することができない. この問題は相互参照について解説するセクション \@ref(crossref) で詳細を述べる.
fig.cap 以外のオプションはおそらく頻繁には変えないため, 冒頭でまとめて設定したほうが楽だろう.
knitr::opts_chunk$set( fig.align = "center", fig.width = 6.5, fig.height = 4.5, out.width = "100%", out.height = "100%" )
なお, これらは rmdja でのデフォルト値であるため, 実際にこの値をあえて記述する必要はない.
ここで, fig.width と out.width の違いも述べておく. out.width/out.height は表示する画像サイズの違いで, fig.width/fig.height はプログラムが出力した画像の保存サイズである. よって ggplot2 などを使わず画像ファイルを貼り付けるだけの場合は fig.* は意味をなさない.
[^standard-graphics]: なお, Rユーザーならば標準グラフィック関数である plot() 関数をご存知だろうが, 本稿では基本的により便利な ggplot2 パッケージを使用してグラフを作成している.
R プログラムを使った表の装飾
Markdown 記法を使った表記は既に紹介した. しかしこれは表の数値を全て手動で書かなければならない. R はテーブル状のデータ処理に長けているため, このような煩雑さを省くことができないか, とあなたは思っていないだろうか. もちろん R Markdown では R での作業中に使用しているデータをいちいち手書きなどせずとも表示できるし, テーブルのデザインもある程度自由に設定できる.
R Markdown のデフォルトでは R のコンソールと同様にテキストとして出力されるが, rmdja では異なるデザインで表示されている. これは knitr, kableExtra パッケージなどで事後処理をかけることで見やすいデザインの表に変換しているからである. R Markdown の基本ルールとして, チャンク内で最後に呼び出したオブジェクトが表示される. 例えば mtcars というRが用意する練習用データフレームを, チャンク内で上から10行までを呼び出してみると, 以下のように表示される.
data(mtcars) mtcars[1:10, ]
これはRのコンソール出力と同じで, プレーンテキストでの出力である. 表として出力する最も簡単な方法は, フォーマット関数に df_print を指定することである. たとえば df_print: kable を指定すると, 表 \@ref(tab:df-print-kable) のようになる.
output: ...: df_print: kable
mtcars[1:10, ]
kbl(mtcars[1:10, ], caption = "`df_print: kable` の場合", escape = F, format = "pandoc", booktabs = F)
このオプションは R Markdown の処理中にデータフレームの呼び出しを検出し, df_print のオプションに対応したスタイルを変換する関数を適用している. 他のオプションとして, tibble, paged などがあるが現時点の rmdja では大差がないので詳細な説明を省略する (図 \@ref(tab:df-print-ops)).
Table: (#tab:df-print-ops) df_print のオプション一覧
オプション 効果
default print(), コンソール出力と同じ
tibble tibble 対応版 print()
paged rmarkdown::paged_table() による表示, これもオプション引数を指定しなければ大差なし
kable knitr::kable() による表スタイル
よって, これらの関数をチャンク内で呼び出すことで, 手動で表のスタイルを指定することも可能である. 表のスタイルにこだわりたい, 相互参照やキャプションを付けたい, といった場合はこれらのうち knitr::kable() 関数を手動で使うのが1つの手である. 実は, 先ほどの df_print の例も, 実際にはこの関数を呼び出して出力している. この場合, 表のキャプションは kable() 内で指定できる (現時点では, 図とは異なりチャンクオプションではキャプションを指定できない). デフォルトでは caption = の文字列はそのまま出力されるため, 太字強調など Markdown 記法も変換されずそのまま表示されてしまう. これには対処方法がいくつかある.
rmdjaパッケージの提供するknitr::kable()またはkableExtra::kbl()関数のラッパを使用する (表 \@ref(tab:display-dataframe-kable-booktabs))escape = Fおよびformat = "pandoc"を指定する- (非推奨) HTML と PDF でそれぞれの構文で表を描く処理を自分で書く
rmdja::kable(mtcars[1:10, ], caption = "`booktabs = T` は PDF にのみ影響する", booktabs = T)
(1) の方法が現在最も簡単である. ただし, r rmdja::texlogo("LaTeX") の構文が評価されなくなるため同時に使うことはできない. 例えば太字強調と数式を両方表示したい場合は, knitr::is_latex_output() PDF の場合は完全に r rmdja::texlogo("LaTeX") で, HTML の場合は Markdown で書く, という場合分けを自分で書いて knitr::kable() に与えなければならない(表 \@ref(tab:kable-caption-example)). また, キャプションではなく表内の markdown 構文も評価されない. 表内の markdown 構文を PDF でも反映するには, (2) の方法が必要である.
TODO: この仕様は使いづらいのでそのうちなんとかしたい.
(2) についても, kable() 単体であれば問題ないが, 後に紹介する kableExtra パッケージを併用すると書式設定がうまく反映されなくなることがある. (3) は表 \@ref(tab:kable-caption-example) の記述をキャプションだけでなく, HTML ならば Markdown または HTML タグで, PDF ならば r rmdja::texlogo("LaTeX") で表全体を書き分ける, という方法である. 1つの表を描くのに多大な労力がかかるため推奨しない.
cap <- if(knitr::is_latex_output()) "数式 $a$ と \\textbf{太字}" else "数式 $a$ と **太字**" kable( head(mtcars), caption = cap, booktabs = T )
さらに, デフォルトでは kable() が PDF に出力する表のデザインはあまりよろしくないが, kable() 関数は過剰な罫線のない表の出力も簡単である. r rmdja::texlogo("LaTeX") を使ったことのある人は知っているかもしれないが, これは booktabs.sty を使った表のスタイルになっている^[もし何らかの理由でこのスタイルにならない, あるいはあえてしたくない, と言う場合は kable() 関数で booktabs = T を指定せよ.].
また, kable() を使う利点として, 表の絡む名に好きな名前を与えられるというものがある. データフレームの列 (変数) 名は, 括弧などプログラミングで特別な意味を持つ文字を使うことができない. そこで, kable() の col.names 引数に表のカラム名を改めて与えることで, こういった文字も出力できる.
kable() による表のスタイルは kableExtra パッケージを使うことで様々にカスタマイズできる. 例えば HTML 版ではデフォルトで奇数偶数行の背景色が異なるが, PDF ではそうなっていない. また, 図表の位置は常にフロートであり, 余白ができにくいように表示位置が前後する (これは技術文書や学術論文では普通のことだが). さらに, 表が本文の領域からはみ出しており見栄えが悪い. これらの設定をHTML版に近づけたい場合は kableExtra::kable_styling() を使って簡単にデザインを変えることができる (表 \@ref(tab:display-dataframe-kable-2)). 以下のように, full_width は表の幅を本文幅にそろえるオプションである. や十分に幅の小さい表に対しては逆に間延びして見づらいためデフォルトでは無効となっているが, このようにして表幅を調整するのに使える. さらに latex_options は PDF にのみ有効なオプションである. "striped" が奇数偶数の色分け[^tabu-error], "hold_position" が表示位置を「なるべく」固定するオプションである (それでも表示位置が大きくずれて気に入らない場合 "HOLD_position" を代わりに使うとよい). ただし HTML と違い PDF では改ページがあるためこのオプションを多様すると, 以下のように本文に無駄な余白が増えることに注意する.
rmdja::kable( mtcars[1:10, ], booktabs = T, caption = "奇数行を強調し, PDF では `booktabs` を利用" ) %>% kable_styling( full_width = if(knitr::is_latex_output()) T else NULL, latex_options = c("striped", "hold_position"))
このように, R Markdown ではまず表示したい表と同じ構造のデータフレームを作ることで, 簡単にスタイルの調整された表を掲載できる.
他にもいくつか表のスタイルをカスタマイズするためのパッケージが存在する. より発展的な表のスタイル指定方法については \@ref(advanced-tabulate) 章で話す.
[^tabu-error]: ただし, full_width = T を指定した時, striped, あるいは他の色の指定の命令が反映されないことがある. これは 2019年時点での tabu.sty の不具合であるため, Issues #1 で配布されている開発者によるパッチを適用しなければならない.また, それ以外にも表の幅を調整する方法がある. 詳細は \@ref(advanced-tabulate) 章を参考に.
相互参照と引用
相互参照 {#crossref}
図表や式へのアンカーリンク
図, 表, 式などに番号を自動で割り当て, さらにハイパーリンクを付加できる. \@ref(ID) を使う. 現状では refstyle や prettyref のように接頭語を自動で付けてくれないが, そのうちなんとかなるかもしれない.
bookdown の相互参照は, LaTeX の prettyref.sty のように, 接頭語:参照ID という記法になる. 参照IDは通常, チャンクIDと同じである. 既に紹介したように, 数式参照の接頭語は eq で, 定理は thm である. 図表は fig, tab. その他の接頭語は BKD Ch. 2.2 Markdown extensions by bookdown を参考に.
表への相互参照
Markdown 記法で表を書く場合, 以下のように Table: の直後にラベルを記入する (表 \@ref(tab:tab-md)).
Table: (\#tab:tab-md) Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
------------- ------------ ------------- ------------
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
Table: (#tab:tab-md) Markdown 記法の表
Sepal.Length Sepal.Width Petal.Length Petal.Width
5.1 3.5 1.4 0.2
4.9 3.0 1.4 0.2
4.7 3.2 1.3 0.2
4.6 3.1 1.5 0.2
5.0 3.6 1.4 0.2
5.4 3.9 1.7 0.4
章への相互参照
章見出しへの相互参照も可能である. これはPandocの機能を利用しているため, 接頭辞は不要である. Pandocの仕様により欧文であればタイトルがそのまま参照IDとなるが, 非欧文の文字に対して適用されないため, 基本的に日本語文書の場合は参照したい章の見出しの後にスペースを入れて {#参照ID} と書く必要がある. そして本文中で参照する場合 \@ref(参照ID) と表記する.
特殊な相互参照
チャンクオプションの fig.cap などに TeX 数式を書いても正しく表示できない. そのような場合は ref 参照を使う. (ref:figcap1) \coloremoji{🌸} $\sum \oint \mathfrak{A} \mathscr{B} \mathbb{C}$ \coloremoji{🌸} と書くと, 図 \@ref(fig:caption) のキャプションにも特殊な記号が使える.
(ref:figcap1) \coloremoji{🌸} $\sum \oint \mathfrak{A} \mathscr{B} \mathbb{C}$ \coloremoji{🌸}
なお, 複数指定する場合は連続させず, 改行で1行空けて宣言する必要がある.
ggplot(tibble(x = 1, y = 1, z = "テスト")) + geom_label(aes(x = x, y = y, label = z)) + theme_classic()
この参照は一度しか使えない.
PDF での表示では, 図 \@ref(fig:caption) のキャプションの外側が文字化けしていることだろう. これは絵文字出力に関する問題で, 別のセクションで解説する.
これはかなり強力で,
- 定義される前の行にも適用される
- チャンクオプションだけでなく出力結果にも適用される
という仕様である.
TODO: 自己言及的な文章は書かないならこれくらいの認識でいいだろうが, より正確な話はどうするか
文献引用 {#bibliography}
YAMLフロントマターの biblography: に文献管理ファイル (.bib, .json 等) を指定することで, ファイルに含まれる文献への参照が可能になる. @引用ID で本文に引用を与えられ, 文書に引用した文献の一覧が自動で生成される. また, citr パッケージにより, RStudio Addins に文献に対応する引用IDを取り出して挿入する機能が追加される.
(ref:citr-caption) citr パッケージの例
knitr::include_graphics(file.path(img_dir, "citr.png"))
一方で, この記述が文書においてどのようなスタイルで出力されるかは文献引用を処理するプログラムによって変化する. そのプログラムには3つの候補がある. R Markdown の文献引用は pandoc を経由して処理され, 現時点では pandoc-citeproc (default), r rmdja::texlogo("BibTeX") (natbib), r rmdja::texlogo("BibLaTeX") (biblatex) の選択をサポートしている. pandoc-citeproc 以外はもともと r rmdja::texlogo("LaTeX") 用に作られたため, HTML では常に pandoc-citeproc で処理される. PDF ではそれに加えて bibtex, biblatex を指定することもできる. (default とは別なのでややこしいが) rmdja はデフォルトでは PDF 出力時に biblatex を使用する. これはフォーマット引数の citation_package で変更できる. 正確には以下の3つの値のどれかを指定する.
default:pandoc-citeprocを使用する.biblatex:r rmdja::texlogo("BibLaTeX")を使用する. デフォルト. スタイルのデフォルトはこちらが用意したjauthoryearというもの.natbib:r rmdja::texlogo("BibTeX")を使用し, 本文中の参照にはnatbib.styが使われる[^natbib-contraint]. ただし, 日本語 (マルチバイト文字) の含まれる文献情報を出力する場合は特殊な設定をしないと製本処理がハングアップする (後述).
[natbib-contraint]: ただし citeit, citep など natbib.sty の提供していた多様な引用子オプションは使えない. これは pandoc の制約によるものである.
文献引用スタイルのカスタマイズ
rmdja では, 本文中の引用トークンのデフォルト設定を, 文書タイプでは「著者-年」形式に, スライドでは番号形式にしている. このカスタマイズについて簡単な解説をする. 従来の R Markdown ではカスタマイズに以下のようなYAMLフロントマター項目を使っていた.
biblio-style: PDF用スタイルファイルnatbiboptions/biblatexoptions: それぞれnatbibまたはbiblatexを使う場合のスタイルに関するオプションcsl: CSL用スタイルファイル ,biblio-title: 「参考文献」タイトルの文字列
このうち biblio-style, natbiboptions, biblatexoptions はフォーマット関数で指定する. 例えば以下のように.
output: rmdja::pdf_book_ja: citation_package: biblatex citation_options: - style=jauthoryear - natbib=true
これは pandoc の記法を利用した従来のR Markdown で以下のように書いているのと同様であり, citation_package: natbib ならば biblatexoptions が natbiboptions に置き換わる.
output: ....: citation_package: natbib biblio-style: jauthoryear biblatexoptions: - natbib=true
2通りの記法が存在するのはやや混乱するかもしれないが, 後方互換性を考慮し rmdja ではこれらの2通りの記法どちらでも受け付けるようにしている.
biblatex 以外のエンジンで出力したい, 例えば指定された .bst のスタイルで文献一覧を出力したい場合は, (u)r rmdja::texlogo("pBibTeX") が必要になる. その操作の詳細は \@ref(biblio-advaneced) 章を参照.
文献リスト生成エンジンの違いについて
pandoc-citeproc, bibtex, biblatex はそれぞれ引用文献リストのスタイルを記述するファイルがあり, それぞれ拡張子は .csl, .bst, .bbx/.cbx, である. .csl は MS Word のスタイルと同じもので, XMLで記述されている[^CSL-editor]. .bst は r rmdja::texlogo("BibTeX") 用のフォーマットで, 自分で改造するには逆ポーランド記法の構文に慣れねばならない. そして r rmdja::texlogo("BibLaTeX") はスタイルを r rmdja::texlogo("LaTeX") のマクロで記述でき, さらにそういった細かい記述のスタイルファイルを用意しなくとも指定できるオプションがいくつか存在する(ここまで, 表 \@ref(tab:biblio-comparison)).
現バージョンでは biblatex がデフォルトである. 現在の日本語圏の r rmdja::texlogo("LaTeX") 使用者にとっては .bst ファイルの種類が充実しているため natbib を使いたいところだが, R Markdown の場合エンジンが r rmdja::texlogo("BibTeX") であるため日本語が使えない. (u)r rmdja::texlogo("pBibTeX") を使うにはやや複雑な手順が必要である. よって, デフォルトでそのような下準備をさせるべきでないと考えたので rmdja では biblatex をデフォルトとし, 日本語表示に最低限のスタイルだけを用意している.
tibble( `item` = as.character(lapply(c("`pandoc-citeproc`", "`biblatex`", "`bibtex`"), function(x) if(is_latex_output()) commonmark::markdown_latex(x) else x )), `HTML` = c(T, F, F), `PDF` = c(T, T, T), `日本語` = c(T, T, F), `指定名` = as.character(lapply(c("`default`", "`biblatex`", "`natbib`"), function(x) if(is_latex_output()) commonmark::markdown_latex(x) else x)), `文献ファイル` = c(".json", ".bib", ".bib/.bibtex"), `文献スタイル` = c(".csl", ".bbx/.cbx", ".bst") ) %>% kable(caption = "引用プログラムごとの違い", booktabs = T, escape = F) %>% kable_styling(full_width = F)
[^CSL-editor]: 簡単なカスタマイズなら CSL editor というWebサービスでできる. しかしあくまでXMLなので, あまり複雑な処理はできないことに注意する.
(WIP) 簡単なレイアウト・スタイル変更
前章では文書の内容に関する構文を紹介した. ここでは, 文書全体のデザインやスタイルの設定方法のうち, rmdja が用意している簡単なものを紹介する.
フォント変更
フォント変更の方法は HTML と PDF で大きく違う. まずは HTMLについて. _output.yml にはデフォルトのフォントを設定できるが, 選択肢は sans と serif しかない.
output: rmdja::gitbook_ja: config: fontsettings: family: serif
しかし HTML は文字通りHTMLで出力しているため, CSS の使い方次第でいくらでもデザインを変えることができる. 例えば自作した CSS ファイルを以下のように指定できる.
output: output: rmdja::gitbook_ja: css: ABC.css
PDF を生成する場合, ver 0.3 以降ではデフォルトのフォントファミリを OS に応じて変えている. もし変更したい場合はYAMLフロントマターの以下の項目を変更する
mainfont: 欧文セリフフォントファミリsansfont: 欧文サンセリフフォントファミリmonofont: 等幅フォントファミリ (コードの表示などに使用)jfontpreset: 和文フォントファミリのプリセットjmainfont: 和文メインフォントファミリ (一般に明朝体を指定)jsansfont: 和文セリフフォントファミリ (一般にゴシック体を指定)jmonofont: 和文等幅フォントファミリ (コードの表示などに使用)
jfontpreset は zxjafont または luatex-ja によるプリセットで, 3種類の和文フォントを一括指定できる. 個別指定したフォントはこれを上書きする. 特にこだわりがないなら一括指定で良いが, ソースコードを多く掲載する場合は M+ や Ricty などのフォントを用意すると良いだろう. rmdja ではデフォルトで3種類の和文フォントファミリに対して, OSごとの標準日本語フォントが選択される (図 \@ref(tab:japreset-default)). いずれも各OSで標準でインストールされているはずであるが, 現時点ではフォントが実際にインストールされているか確認する機能はない.
data.frame( Mac = c("游書体", "ヒラギノ ProN"), Linux = rep("Noto", 2), Windows8 = rep("游書体", 2), Windows_old = rep("MSフォント", 2), row.names = c(rmdja::texlogo("XeLaTeX"), rmdja::texlogo("LuaLaTeX"))) %>% kable(row.names = T, col.names = c("Mac", "Linux", "Windows (8以降)", "Windows (それ以前)"), caption = "デフォルトで使用される日本語フォントファミリ", booktabs = T, escape = F, format = "pandoc")
それ以外で使用可能な主なプリセット名は表 \@ref(tab:japreset-list) の通り. これらは r rmdja::texlogo("XeLaTeX"), r rmdja::texlogo("LuaLaTeX") でそれぞれ zxjafont.sty, luatex-ja.sty を利用してフォントが埋め込まれる. 両者の多くではプリセット名が共通しているが, 一部例外もあることに注意 (特に r rmdja::texlogo("XeLaTeX") は luatex-ja との互換性を考慮してエイリアスをいくつも用意している). また, より詳細な一覧やオプションの全貌については, ⼋登崇之氏の『PXchfon パッケージ』および zxjafont のマニュアル と, 『luatex-ja の使い方』を確認してほしい.
parse_latex <- function(x){ if(is_latex_output()) commonmark::markdown_latex(x) else x } tibble( family = c("MS ゴシック/明朝", "游書体", "ヒラギノ系", "Noto フォント", "源ノ角ゴ/明朝", "原ノ味フォント", "梅フォント", "小塚フォント", "IPA (Ex) フォント"), XeLaTeX = c("`ms`", "`yu-win10`", "`hiragino-pro`", "`noto`/`noto-jp`", "`sourcechan-jp`", "`haranoaji`", "`ume`", "`kozuka-pro`", "`ipa`/`ipaex`"), LuaLaTeX = c("`ms`", "`yu-win10`", "`hiragino-pro`", "`noto-otf`/`noto-otc`", "`sourcehan-jp`", "`haranoaji`", "`ume`", "`kozuka-pro`", "`ipa`/`ipaex`" ), details = c( paste(rmdja::texlogo("XeLaTeX"), "のみ HGフォントと併用する", if(is_latex_output()) "\\texttt{ms-hg}" else "`ms-hg`", "などのバリエーションあり"), parse_latex("Windows 8 以前は `yu-win`, Mac では `yu-osx`"), parse_latex("`hiragino-pron` で ProN/StdN版を指定"), "", "", "", "", parse_latex("`-pr6` で ProVI版, `-pr6n` で Pro6N版を指定なども指定可能"), paste(rmdja::texlogo("XeLaTeX"), "のみ", if(is_latex_output()) "\\texttt{ipa-hg}" else "`ipa-hg`", "などのバリエーションあり") ) ) %>% mutate(across(c(XeLaTeX, LuaLaTeX), ~if(is_latex_output()) map_chr(.x, commonmark::markdown_latex) else .x)) %>% kbl(caption = "主な指定可能なフォントプリセット名", booktabs = T, escape = F, col.names = c("フォント", rmdja::texlogo("XeLaTeX"), rmdja::texlogo("LuaLaTeX"), "備考") ) %>% column_spec(4, width = "10em")
さらに, それぞれの項目に対してオプションを設定する場合, options と接尾辞のついた項目が用意されている. 欧文と和文フォントで全く異なるタイプのフォントを使ったために相対的なサイズが合わず不格好な場合は
mainfont: Palatinno mainfontoptions: - Scale=0.9
などと書いて調整できる.
YAML フロントマターの設定によるスタイル変更
RMD ファイルの冒頭に書かれているYAMLフロントマターは様々なことが設定できる. これらのオプションは Pandoc のものに対応している. HTML はスタイルのほとんどが 規格化された CSS で操作できるため, 主に PDF に関するものである. また, 本章はあくまで簡易的な機能解説であるため, より詳細な解説は後の章で再度取り上げる.
ハイパーリンクの配色変更
たとえば PDF では, 以下のようにしてハイパーリンクの色を変更できる.
link-citations: true linkcolor: blue citecolor: blue urlcolor: magenta
まず, ハイパーリンクを有効にする, link-citations:true が必要である. 次に, リンクの種類ごとに色を指定できる. linkcolor は文書内のハイパーリンクの色, citecolor は巻末の参考文献リストへのリンクの色, そして urlcolor は文書外の URL へのリンクの色である.
また, ページのヘッダ・フッタは pagestyle で指定できる.
pagestyle: headings
文書クラスによっても多少変わるが, プリセットが4種類用意されている.
empty: 何も表示しないplain: ページ数のみ表示headings: ヘッダに罫線を引き, ページ数だけでなく章のタイトルも表示するfancy: ユーザによるカスタマイズ (WIP)
(3) が一般的な書籍のものに近いスタイルである. (1-3) は, タイトルページや調整のための白紙ページなどはかならずしも変更されない. そういった根本的な変更がしたい場合のため, (4) が用意されている. しかし, 現時点では fancyhdr.sty の使い方を知る必要がある.
r rmdja::texlogo("LaTeX") エンジンの変更
PDF の出力は rrmdja::texlogo("LaTeX")を使用する. その処理プログラムにはいくつかバリエーションがあり,rmdjaではr rmdja::texlogo("XeLaTeX")とrmdja::texlogo("LuaLaTeX")の使用を想定している (R Markdown ではr rmdja::texlogo("pdfLaTeX")もサポートしているが, これは日本語表示が難しいためrmdja` では採用していない).
両者は多少の違いがある (正確には, 両者それぞれに対応した和文組版パッケージの違いにも由来する).
- 組版の違い.
r rmdja::texlogo("XeLaTeX")で和文組版を制御するzxjatype.styにはいくつか改善の余地が残っている. - 速度の違い. 年々改善されているようだが, それでも
r rmdja::texlogo("LuaLaTeX")は処理の遅さが目立つ^[ただし R Markdown に限って言えば R コードの処理時間のほうが問題となることもある. また,r rmdja::texlogo("XeLaTeX")であっても文献処理や索引処理など関連プログラムを多く使用すればそれなりに遅くなる.]. - フォントレンダの違い. 一概に言うのは難しいが, デフォルト設定では文字のウェイトや和文・欧文の相対的なバランスが微妙に異なる.
- 和文・欧文を同時に扱う際の挙動の違い.
r rmdja::texlogo("LuaLaTeX")は和文と欧文の処理ルールが競合する時, 和文の処理を優先する傾向がある. 一方でrrmdja::texlogo("XeLaTeX")(およびzxjatype.sty`) はなるべく両者を共存できるように作られている.
もし和文組版の厳格さを優先したいのなら rrmdja::texlogo("LuaLaTeX")を使うべきである. しかし処理速度があまりに遅いとか, 欧文の扱いが気に入らないとかの場合はr rmdja::texlogo("XeLaTeX") を使うと良い. 特に書籍形式でなくプレゼンテーション資料であれば, 組版ルールの厳格さはあまり気にならないことだろう.
文書クラスのカスタマイズ
デフォルトでは bxjsbook という文書クラスを使用している. この他 rmdja では bxjsreport, ltjsbook, ltjsreport, ljreq という文書クラスに対応している. ただし ljreq は r rmdja::texlogo("LuaLaTeX") でのみ動作する.
LaTeX のカスタマイズ
PDF のデザインを微調整したい場合, 自分で r rmdja::texlogo("LaTeX") のソースに変更を加える必要がある. よってこの機能は r rmdja::texlogo("LaTeX") の使用に慣れたユーザのみが使用してほしい.
r rmdja::texlogo("LaTeX") のソースに変更を加える方法は2つ. 1つは header-includes を使うことである.
header-includes:
- ...
- ...
これでリスト風にプリアンブルを書くことができる. ただし, % を使った改行エスケープは使用できない. もう1つは, 出力フォーマットの includes に設定する方法で, 以下のように命令文ではなく TEX ファイルを指定する.
output: rmdja::pdf_book_ja: includes: in_header: i.tex before_body: b.tex after_body: a.tex
それぞれ, プリアンブル, 本文冒頭 (document 環境, 表紙や目次等の直後), 本文後に挿入される. しかし, TEX ファイルの大枠は Pandoc のテンプレートファイルで決まっているため競合することもある. よってテンプレートを確認しながら作る必要がある. テンプレートファイルは Pandoc 独自の簡易なマクロが挿入されている以外は通常の r rmdja::texlogo("LaTeX") ソースと同じである^[現時点では日本語版ユーザーガイドでも未翻訳のパート. しかし if, for 文など簡単な制御構文しかないため, 結局 r rmdja::texlogo("LaTeX") のマクロを使うことが多いだろう. https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html#templates, https://pandoc.org/MANUAL.html#templates].
テンプレートファイルは R で以下を実行して得られるディレクトリにある. beamer-ja.tex.template は beamer 用, document-ja.tex.template はそれ以外の文書用である.
system.file("resources/pandoc-templates", package = "rmdja")
テンプレートを修正しなければ意図した変更ができない場合, 以下のようにして別のテンプレートファイルを指定できる.
output: rmdja::pdf_book_ja: template: new-file
チャンク/コードおよび出力ブロックのスタイルの一括変更
すでに書いたように, コードブロックのシンタックスハイライトはいくつかのプリセットを適用できる. また, チャンクオプションにはいろいろなものがあり, それらは全て, knitr::opts_chunk::set() で以降のチャンクに対して一括して適用できる. 詳細は https://yihui.org/knitr/options/#code-decoration などを見てもらうとして, いくつかを抜粋する. YAMLフォーマットと違い, チャンクオプションは全て R のコードとして評価されるため, 論理値は TRUE/FALSE または T/Fと表記すること.
highlight: シンタックスハイライトを適用するかどうか.background: コードブロックの背景色. デフォルトは#F7F7F7つまり灰色である.tidy,tidy.opts: コードの自動整形を適用するかどうかと, そのオプション.rmdjaのデフォルト設定ではstylerパッケージを使用している. 詳しくは付録 \ref(autoformatter) を参照.prompt: コードブロックにプロンプト記号>を表示するかどうかcomment: 出力ブロックの行頭に表示する記号. デフォルトは##size: 出力ブロックのフォントサイズindent: 出力ブロックのインデント
行番号の表示
行番号の表示は attr.source = c(".numberLines", .lineAnchors") を指定する.
rmdja で提供するフォーマットでは, `YAML フロントマターで一括して行番号を表示することを指定できる.
output: rmdja::pdf_document_ja: add_rownumber: true
このオプションは上記のチャンクオプションのデフォルト値を変更するものである. よって, これを設定した状態で任意のコードブロックの行番号を非表示としたい場合は逆にチャンクオプション attr.source = NULL を指定する.
コードブロックのページまたぎ禁止
長いソースコードを掲載するとページまたぎが発生する. 現時点では, rmdja の機能としてコードブロックに個別にページまたぎを許可・禁止を指定する機能はない (Pandoc の基本機能の範囲でサポートされていないため) が, 一括で指定することはできる. 例えば
header-includes:
- \@ifpackageloaded{fvextra}{}{\usepackage{fvextra}}
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\},breaklines,breakanywhere,samepage=true}
と書く. ただし直接関係あるのは samepage=true だけである. これはテンプレートの記述を上書きするという乱暴な方法なので, 他のデフォルトオプションも混在している. commandchars=\\\{\} はシンタックスハイライトに関する設定で, 基本的に消すべきでない. breaklines は行途中の折り返しを許可するもの, breakanywhere はどこでも行の折り返しを許可するというもので, いずれもデフォルトのコード自動整形と関係がある. ちなみに TEX ファイルを開いて highliting 環境に個別に samepage=true オプションを指定すれば個別に折り返しを禁止できる.
(WIP) rmdja による文書作成支援機能
クリエイティブ・コモンズの表記
Web公開する文書ならばクリエイティブ・コモンズの表記をつけたいところだ. 公式サイトで毎回発行するのは面倒なので表示する関数を用意にした. ハイパーリンクも付けるようにしている. チャンクでは results="asis" オプションが必要になる. また, 通常は echo=F を設定すべきだろう. 冒頭の表記もこれで作成している. もちろんそれぞれの媒体に対応している.
文言の生成は未対応
ルビ表記
ルビはおそらくCJK言語など一部の言語でしか使われていない (アラビア語とかヘブライ語とかの補助記号は詳しく知らないが多分グリフとしてサポートされてるっぽいので無視) ため, ルビ表記も R Markdown ではサポートされていない. そこで簡単にルビを表示できる関数 rmdja::ruby() を用意した. インライン実行で使う. PDF での配置は pxrubrica.sty を利用したグループルビである. よって, 1字ごとに配置 (モノルビ) にしたいとか, 突出指定とか, 細かいことはHTMLタグやCSSやLaTeXコマンドを自分で書く. 妥協案として, 1字ごとに呼び出す手もある.
グループルビの例: とある科学のr rmdja::ruby("超電磁砲", "レールガン"), r rmdja::ruby("皇帝", "カイザー")ラインハルト, r rmdja::ruby("柊館", "シュテッヒパルムシュロス"), r rmdja::ruby("黒色槍騎兵", "シュワルツ・ランツェンレイター"), r rmdja::ruby("喜連瓜破", "きれうりわり"), , r rmdja::ruby("MEXICO", "メキシコ")
分割して出力した例: r rmdja::ruby("喜", "き")``r rmdja::ruby("連", "れ")``r rmdja::ruby("瓜", "うり")``r rmdja::ruby("破", "わり"), r rmdja::ruby("黒色", "シュワルツ")``r rmdja::ruby("槍騎兵", "ランツェンレイター") ,
TODO: それ以外にも便利機能を少しづつ増やしていく予定
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.