RファイルをR Markdown形式のファイルに変換するパッケージ(RconVerteR)を作ってみた

## 目次
- [はじめに](#はじめに)
- [関連記事](#関連記事)
- [コード全体](#コード全体)
- [`RconVerteR`パッケージのインストール](#rconverterパッケージのインストール)
- [`R2Rmd`関数の使い方: R --> R Markdown](#r2rmd関数の使い方)
- [`Rmd2R`関数の使い方: R Markdown --> R](#rmd2r関数の使い方)
- [おわりに](#おわりに)



## はじめに
最近, R Markdownの利用が広がっているようですね. 私の周りでも, 他人にRのコードを渡す代わりに, R Markdownを書いて, HTML形式でコードの内容を共有する人が増えてきた気がします. 
（R Markdownに関しては以下の[関連記事](#関連記事)にあげるページがわかりやすくまとまっているのでオススメです. ）


R Markdownは通常RStudio内で書いてゆくと思うのですが, Rコードをメインで書きつつMarkdownも交えて書いてゆくというのに慣れない, という人もいると思います（私です）. 

そんな折, @hgoj さんから, Rコードから直接R Markdown形式に変換する方法を知らないか, と相談を受けました. しかし, 私の調べる限りでは特に見つけられませんでした. 

ただこの変換は, いわゆる正規表現をうまく使ってゆけばなんとかできそうでした. そこで, いろいろなファイルを読み込むのに便利な`readr`パッケージと, 正規表現を扱うのに便利な`stringr`パッケージを利用して, `RconVerteR`というパッケージを新たに作ってみました！


## 関連記事
- [R Markdownによるレポート生成](https://qiita.com/tomotagwork/items/c92fb40a76f56ea16aa4)
- [R MarkdownのHTMLレポートをブラッシュアップ](https://qiita.com/tomotagwork/items/3061a74e1d25cf46e891)
- [knitr ではじめるデータ分析レポート作成 ~基礎編~](https://qiita.com/yu-iskw/items/a3000cb7d5b17ad71731)
- [R Markdown入門](https://kazutan.github.io/HijiyamaR5/rmd_intro.html)



## コード全体
とりあえずコード全体について載せておきます. 
この後, 詳細について少しずつ見てゆきます. 

``` r:コード全体.R
### Install RconVeretR package via devtools
if (!requireNamespace("devtools", quietly = TRUE)){
	install.packages("devtools")
}     ### install devtools

devtools::install_github("KosukeHamazaki/RconVerteR")  ### install RconVerteR


### How to use RconVeretR package
require(RconVerteR)

R2Rmd(fileName = "変換したいRファイルのパス")  ### R --> R Markdown

Rmd2R(fileName = "変換したいR Markdownファイルのパス")  ### R Markdown --> R
```



## `RconVerteR`パッケージのインストール
まず, パッケージのインストール方法に関してご紹介します. 
このパッケージは, [GitHubにて公開](https://github.com/KosukeHamazaki/RconVerteR)しているので, 開発者向けのパッケージ`devtools`を介してインストールできます. 
仮に`devtools`をインストールしていない場合は以下のコードでインストールしましょう. 

``` r
### Install RconVeretR package via devtools
if (!requireNamespace("devtools", quietly = TRUE)){
	install.packages("devtools")
}
```

その後以下のコードで`RconVerteR`パッケージをインストールしましょう. 

``` r
devtools::install_github("KosukeHamazaki/RconVerteR")
require(RconVerteR)
```

特殊なパッケージや`Rcpp`パッケージなどは使っていないので, 特にエラーなくすんなりインストールできるはずです…

さて, `RconVerteR`パッケージをインストールすればわかると思いますが, このパッケージには`R2Rmd`と`Rmd2R`という2つの関数のみから構成されています. 

以下ではそれぞれの関数の簡単な使い方に関して説明します. 




## `R2Rmd`関数の使い方
`R2Rmd`関数は, その名の通り`.R`ファイルを`.Rmd`ファイルに変換する関数です. 
以下の1行のコードを実行すれば良いだけです. 

``` r
R2Rmd(fileName = "変換したいRファイルのパス")  ### R --> R Markdown
```

一番簡単にはこれで終わりで, 元のRファイルと同じ場所に同じファイル名で拡張子が`.Rmd`のファイルが作成されるはずです. あとは普通のR Markdownファイルと同様に`Knit`を行えば, HTML形式のファイルができると思います. 

出力する`.Rmd`ファイルの名前を変更したい場合は, `saveFileName`という引数に保存したいファイル名を指定してみてください. 

ちなみに他にもいくつか引数を用意してあります. 例えば, 
・`textTitle`
・`Author`
・`Date`

は, R Markdownにおいてタイトルなどの設定を行う為の引数です. 

`plotEcho`引数は, plotを描く時にその分のコードを表示させるか決めるもので, `plotEcho = TRUE`ならコードを表示します. 


`outFormat`引数が一番わかりにくいと思うのですが, これは小見出しを作る時に`#`の数をどうするか, という設定に関わる引数です. 
デフォルト（`outFormat = "unknown"`）では, 小見出しの`#`の数はいつも3つで固定になります. 
`outFormat = 1`にすると, 以下のような少し複雑な設定で小見出しの`#`の数を決定します. （私がRでいつもつけている小見出しに準拠しているものなので, 無視してもらって構いません）

例えば`.R`ファイル内で各行の`#`の数が以下のようになっている時, 

``` r:変換前.R
####### R ファイル内の小見出しの付け方
###### R ファイル内でこんな風に
##### 小見出しをつけていると
#### Rmd ファイル内では
### こんな風に変換されます. 
## 各行の"#"の数がどう変化するかに
# 着目してみてください. 
```

`.Rmd`ファイルではこのように変化します. 

``` r:変換後.Rmd
# R ファイル内の小見出しの付け方
## R ファイル内でこんな風に
### 小見出しをつけていると
#### Rmd ファイル内では
##### こんな風に変換されます. 
各行の"#"の数がどう変化するかに
着目してみてください. 
```

こんな感じに`.R`ファイルを決まった形跡で書いていれば, `Rmd`形式に変換した時に自動で小見出しを設定してくれるので便利かもしれません. 



## `Rmd2R`関数の使い方
次に`Rmd2R`関数について紹介します. 
`Rmd2R`関数は, `R2Rmd`とは逆に, `.Rmd`ファイルを`.R`ファイルに変換する関数です. 


ちなみに, `knitr`というパッケージに`purl`という`.Rmd`からRコードのみを抜き取るという関数が実装されており, `Rmd2R`関数はこれと似た関数と言えるかもしれません. 
ただ, `Rmd2R`関数では小見出しなどを残すことができる点が違います. 


さて, 実行の仕方は`R2Rmd`関数と同様単純で

``` r
Rmd2R(fileName = "変換したいR Markdownファイルのパス")  ### R Markdown --> R
```

で基本的にはOKです. 

引数としては, `outFormat`, `textTitle`, `saveFileName`は`R2Rmd`関数と同様です. 

他の引数としては, `remainExplanation`はR Markdown内の説明文を, Rファイル内に残すかどうかを決める引数です. なお小見出しは必ず残ります. 

それから, `Numbering`という引数は以下のように小見出しに`1.`, `1.1.`のような番号を追加するか決定する引数です. 
番号の追加の仕方はR Markdownファイルにおける`#`の数から決定されており, 以下の例のような感じです. 


例えば`.Rmd`ファイル内で以下のような小見出しのつけ方をしている場合, 

``` r:変換前2.Rmd
# R Markdown ファイル内の小見出しの付け方
## R Markdown ファイル内でこんな風に
### 小見出しをつけている場合
### R ファイル内で
#### どう番号がつけられてゆくか

## "#"の数に応じて
### 変化していくのが
#### わかるでしょうか. 
##### 少し複雑ですが
#### わかってもらえると

# 幸いです. 
```

`.R`ファイル内では以下のように番号がつけられます. （`outFormat = "unknown"`の場合）

``` r:変換後2.R
### 1. R Markdown ファイル内の小見出しの付け方
### 1.1. R Markdown ファイル内でこんな風に
### 1.1.1. 小見出しをつけている場合
### 1.1.2. R ファイル内で
### 1.1.2.1 どう番号がつけられてゆくか

### 1.2. "#"の数に応じて
### 1.2.1 変化していくのが
### 1.2.1.1. わかるでしょうか. 
### 1.2.1.1.1. 少し複雑ですが
### 1.2.1.2. わかってもらえると

### 2. 幸いです. 
```

自動で番号付けを行いたい場合は是非活用してみてください. 


## おわりに
いかがだったでしょうか. ここまでRファイルをRmdファイルに変換する`RconVerteR`パッケージのインストールと簡単な使い方に関して紹介してきました. 
もしかしたらこれまでも似たような関数とかあるのかもしれませんが, とりあえず私はこのパッケージを使ってゆこうと思います. （似たような関数があるならコメント欄などで教えていただけると幸いです. ）

当然, 今回の関数を使った変換は完全に思った通りになるとは限らないので, その辺りは変換後に適宜修正していただければと思います. 

ちなみに個人的には, `.Rmd`ファイルより`.R`ファイルで実行をしたかったりすることが多いので, `Rmd2R`関数の方が重宝しそうです笑

最後に, `RconVerteR`パッケージの管理などは私が行なっているので, 使用にあたって不明な点や, 修正してほしい点, 追加してほしい機能などあれば, コメント欄で言っていただければ, できる限り答えてゆきたいと思います.