R MarkdownをViaualモードで簡単に体験しよう
手元で動かすドキュメント rev2
niszet
2022/10/20
1 このドキュメントについて
このドキュメントは TokyoR98 で説明したTokyoR98 RMarkdown入門 Visual modeではじめようの資料の補足で作成したファイルの更新版です（ややこしいね）。
本ドキュメントはTokyoR102で使用予定です。このファイルはTokyoR98版にVisual Editorの操作について追記したため、こちらが上位互換になりますが、表示例のみ確認する場合は旧版の方が見やすいかもしれません。プレゼン資料とは相補的になっている（はず）ので、必要に応じてそれぞれ参照してください。
R MarkdownをVisual Editorで執筆することに慣れるために、記法のサンプルを置いています。RmdファイルをVisual modeで開いて、対象の書式にカーソルを置くとポップアップ表示が出たり、右側に(…)のボタンが表示されたり、エディタ上部の対応するボタンがハイライトされたりします。自分で書き換えたり、Source modeとVisual modeを切り替えて記法の対応関係を覚えたりすることに使ってください。また、outputを色々と書き換えて、knitしてください。ただし、本ドキュメントで説明していない記法もあります。 Visual R Markdownのページもあわせて確認してみてください。
後半は表示例および記法とPandoc内でのデータ形式と紐づけて説明しています。詳細はPandocのマニュアルを参照してください。実際に見えるものを触って、内部のデータ構造（表現）との対応関係を理解した方が良いと考えているためこのような構成となっています。
RStudioのマニュアルとして、R Markdownに関してはツールバーの [Help] - [Cheat Sheets] から見れる R Markdown Cheat Sheet、R Markdown Reference Guide などがあります。また、Markdownの記法については同じくツールバーの [Help] - [Markdown Quick Reference] でHelpに記法の一覧が出てくるので、これを見ながらでも良いでしょう。
2 Visual Editorのこと
Visual modeを常に有効にする場合は、RStudioの[Tools] - [Global Options…] から、R MarkdownのVisualタブ、GeneralにあるUse visual editor by default for new documentsにチェックを入れてください。
2.1 Visual Editor のツールバーの各ボタンの説明
以下、Visual modeで使用しているとき（Visual Editor）の上部に現れるツールバーの各ボタンの操作について、対応するMarkdown記法とリンクづけて説明します。
Markdownは記号によって意味づけをし、この文字のまとまりは見出しであるというようにコンピュータ側（Pandocなど）に理解しやすい記法となっていますが、慣れないうちは見てもイメージがわきにくいと思います。実際に使ってみて、操作と対応関係をつけて覚える方が良いかもしれません（と思ってこの構成にしています）
2.1.1 Source/Visual
ソースモードとビジュアルモードの切り替え。
2.1.2 B/I/</>
- 太字、イタリック、コードのON/OFF。適用・表示例はインライン要素を参照。
2.1.3 Normal▼
- NormalとHeader1-6が指定できる。Normalは通常の文、Headerは見出しレベル1-6に対応する。出力先フォーマットによっては見出しレベルの数字を大きくしても見た目に反映されないので注意（3までに抑えておくのが良い）
2.1.4 List
点ではじまるリストをつくる。連続して並んでいる行はひとつのリストになる。分ける場合は空行を挟む。
Visual Editor上ではリストにカーソルを置くと右側に(…）のアイコンが出る。クリックすると下記のようにList typeの切り替えが出来る。Tight layout…にチェックを入れると、リストのアイテム間のスペースが狭くなる。
2.1.5 Numbered List
- 番号ではじまるリストをつくる。
- 連続して並んでいる行はひとつのリストになる。
リストを分ける場合は間に空行を挟むと別の番号つきリストとなる。
設定で開始番号、スタイル、デリミタの指定が可能。
2.1.6 Link
ファイル内や外部のファイルへのリンクを作成出来る。
Link toでURL、Heading、IDが選択できる。外部のファイルはURLを指定する。ファイルパスを指定すればローカルファイルも参照できる。
Windowsの場合は絶対パスかつデリミタは
\ではなく/でないといけない。Mac/Linuxは未調査。Visual Editor上でリンクをクリックして（対応したアプリで）ファイルを開くことも可能。
ファイル内の見出し（Header1-6）へのリンクはHeading、IDを振っている箇所にはIDでそれぞれリンク先を指定できる。
- それぞれドキュメント内の出現順にプルダウンメニューに表示される。HeadingはTextやTitle/Tooltipの指定が出来ない。
Attributes持ちの要素はIDを設定できるため、このように画像へのリンクも出来る。見出し（Header）はPandocで処理する際に自動的にidが振られるが、Visual Editor上では明示的に指定したものだけ候補に現れる。
- 日本語の見出しはPandocの変換やSouceモードを挟むと上手く動作しなくなるため、各見出しにVEの機能でAuto Generateで良いので明示的にidを振り、そちらを使用する方がよい。
2.1.7 Image
FileのパスやURLを指定して画像を貼る。Visual Modeで画像を貼り付けすると作業ディレクトリに
imagesというフォルダが作られ、paste-********.pngというファイル名で画像が保存される（下記画像もペーストして自動で保存・埋め込みがされている）
- Visual Editor上でドラッグして位置を変更出来たり、サイズを変更出来たりするので便利。Lock ratioにチェックを入れておけば縦横比は維持できる。Attributes はそちらを参照。
- Advanced では Title Attributeを指定できる。画像にマウスを重ねたときにポップアップする文字列である。
2.1.8 Format
- 書式の設定に関連する物。一部Insertとの割り振りの理由が分からないが。
- 上からTextまでは文字装飾、Bullets & NumberingはList、Numbered Listの設定と同じ。またCode Block以降はコード記法、ブロック引用、ラインブロック、Div、Span、Rawと対応しているためそちらを参照してください（未対応箇所はいずれ Visual Editor 補足 に追記予定）
- Clear Formattingはカーソルが置かれた行に設定された設定を解除するため多用する。ショートカットキーは覚えて損はナシ。
- Edit Attributes はAttributeに説明を置いた。現在カーソルがある要素のAttributeを修正する。ショートカットキー（F4）で(…)をクリックしなくて済む。
2.1.9 Insert
挿入する物についてまとまっている。ショートカットキーはAnyだけ覚えておけば全て対応出来る。
Code Chunkは
R,Python,Bash,Rcpp,SQL,D3,Stanのコードを挿入できる。Table、 Figure/Image、 Link、 Citation、 Footnote、LaTex Math Definition、 Special Characters、Paragraph、Div、Horizontal Rule、Code Block、YAML Block Comment（未対応箇所はいずれ Visual Editor 補足 に追記予定）
Citatioin
2.1.10 Table
表、行、列の挿入および削除、列の左右中央揃え、ヘッダ、キャプションの設定が可能。Markdownの表を手書きで作るのは苦行なので、ちょっとした表を作る時に非常に便利。Word上での操作とほぼ同じように使える。作成した表の見た目は表で説明。
2.1.11 Outline
ドキュメントのアウトラインを表示する。
OptioinのR Markdown、BasicのShow in document outlineで「Sections Only」、「Sections and Named Chunks」、「Sections and All Chunks」が選択できる。全てのチャンクを表示するようにすると名前付けを忘れたチャンクを見つけやすい（？）。
なお、エディタ左下からもジャンプできる。チャンク名は斜体なので他と区別できる。
2.2 Visual Editor 補足
追記予定
3 Pandocの内部データ構造との対応
以下、Pandocのマニュアルへのリンクを貼り、表示と記法とを対応させた形でそれぞれを説明していく。それぞれがVE上ではどこから入力すれば良いかは、Format か Insert のどちらかにあるので探してください。
3.1 インライン要素
インライン要素は文中の要素のこと。文字やその装飾などのこと。
3.1.1 リンク
第98回R勉強会@東京 URLと表示する文字、マウスカーソルを合わせたときにPop upする文字を指定可能。
3.1.2 画像
画像はインライン要素 
なので本来このように行中に書けるのだが、Visual Editor上で扱おうとするとうまくいかない。ただし、出力先では行中に出力されているはずである。バグなのかこのように表示するとCaptionが表示されなくなる。
画像への相互参照、図3.1へリンクが貼られる。
3.1.4 脚注
脚注1はInsertのFootnoteから入れるコトができる。肩の上の数字をクリックすれば脚注の文字列を設定できるので便利。Linkや画像に次いで記法がややこしく感じるため、恩恵はでかい。
3.1.5 インライン数式
\(\sin x +\cos x\)のように、通常の文中に入れる数式の記法。
3.2 ブロック要素
以降で説明してるものはいわゆる段落となる要素。行単位の要素（行単位でなく連続した文はひとつの段落と扱われます）
3.2.1 リスト
リスト要素1
リスト要素2
3.2.2 番号付きリスト
番号つきリスト
番号付きリスト
- チェックボックス付きのリスト。
3.2.3 ブロック引用
引用文に使用。
3.2.5 ラインブロック
一般的なファイルに出力すると他の地の文と区別がつかない。
3.2.6 引用
引用（citation）は (rmarkdown?) のような形式で書く。書式はcssやCSLなどを修正して対応してください。
3.2.8 表
Visual Editor 上での操作は Table にて。Rが生成するものはRでやるべきだが、VE上でもかなり表の編集はしやすくなっており、ExcelやHTML上の表からのコピペも出来る（Excelから貼ると空行空列が入るが、行や列削除も容易）ため、ちょっとした表をつくるのであればむしろVE上で加工した方が早い。ただし、出力先のフォーマット次第で体裁は崩れてしまう点には注意。
| 左揃え | 中央揃え | 右揃え |
|---|---|---|
| 11 | 12 | 13 |
| 21 | 22 | 23 |
3.2.9 ディスプレイ数式
レイアウト上で行全体を使い、地の文と分ける時に使用。
\[ f(x)=\dfrac{1}{\sqrt{2\pi\sigma}}\exp(-\dfrac{(x-\mu)^ 2}{2\sigma^ 2}) \]
3.2.11 Div
単体では特に意味がなくAttributesのidやclassを指定して特別な意味を持たせるために使う。
Visual Editor上ではこのように色がつくが、特別な意味を持つidやclassを持たなければ普通の文章と変わらない形で出力される。
3.3 Rのコード
以下はまだ手がついていません。
コードブロックとインラインコードがある。イ ンラインコードは文中に入れることが出来、R version 4.2.1 (2022-06-23 ucrt) のように書き、knitするとコードが実行結果に置き換わりレンダリングされる。pythonなどが指定できるコードブロックと違い、インラインコードはrのみ。
Rのコードのまとまりをチャンクと呼び、チャンク単位で実行することが出来る。
1つ前のチャンクまでを実行するボタンと、このチャンクを実行するボタンがある。
このボタンで実行するとき、Rの環境はR Markdownの環境ではなく、RStudioの環境なので注意（既に環境中にある変数に影響がある・影響を受ける）
(a <- 1) #()で囲むと代入した値が出力される## [1] 1チャンク名をsetupにすると、チャンク実行時の前処理として実行される。
また、チャンクに名前をつけると相互参照などで参照できる。
チャンクオプションを指定できる。echo、eval, include などは必須。他 は必要に応じて。{ } の中で, を入力すると入力補完が出る
Figure 3.1: cars plot
ggplot(mtcars, aes(x=wt ,y=mpg,color=hp))+geom_point()
表はYAML中で df_print を指定する、チャンク内に paged.print=TRUE を指定するなどするとページ区切りの表になる。表を作るパッケージも沢山あり、 knitr::kable 、 kableExtra 、 flextable 、 gtsummary 、 skimr パッケージなどがある（単純な表作成だけではなく、集計をするパッケージも含む）
mtcars脚注はhtml形式の場合は一番下に表示される↩︎