본문으로 바로가기



Make your own R package! - 10. 설명서(Vignette)와 마크다운(markdown)에 대하여

category R Programming/Rpackage 2017.08.07 12:23
Make your own R package! - 10. 설명서(Vignette)와 마크다운(markdown)에 대하여

Vignette이란 단어를 R 패키지를 만들며 처음 접했을 때, 생소한 단어라서 당황했던 기억이 있다. Vignette의 뜻은 책의 타이틀 페이지나 요약본이라는 뜻인데, 프랑스에서 전해진 단어라서 그런지 우리가 생각하는 비그넷이 아닌 “빈옛(트)”으로 g를 묵음처리해서 발음한다. 다음의 링크를 타고 한번 들어보도록 하자.(http://aha-dic.com/View.asp?Word=vignette)

오늘은 패키지의 설명서라고 할 수 있는 Vignette을 만드는 방법에 대하여 알아보도록 하자. 이제까지 포스팅을 하면서 사용한 함수들을 필자의 패키지에 넣어놓았는데, 이제 필자의 패키지에도 들어있는 함수의 수가 늘어나기 시작했다. 이렇게 패키지가 가지는 함수의 갯수가 늘어날 수록 설명서의 역할은 점점 더 중요해진다. 필자의 경우도 vignette이 친절한 패키지 일 수록 더 사용빈도가 늘어나는 것 같다.

Vignette 초기 셋팅

제일 먼저 할 일은 다음의 명령어를 입력하여 초기 세팅을 하는 것이다. 자신의 설명서 이름을 괄호안에 넣어서 초기화하도록 하자. 필자의 경우는 패키지 이름으로 설정하였다.

devtools::use_vignette("r4issactoast")

위의 명령어는 다음 세가지를 수행한다.

  1. 패키지 폴더에 vignettes라는 폴더를 생성하고, 그 안에 r4issactoast.Rmd 파일을 생성한다. 이 파일이 바로 우리의 설명서를 만들어낼 Rmarkdown 파일이된다.
  2. 패키지 첫 상위폴더의 .gitignore 파일에 “inst/doc”을 추가한다.
  3. DESCRIPTION 파일안에 다음의 내용을 추가한다:
Suggests: knitr, rmarkdown
VignetteBuilder: knitr

마지막 내용은 패키지의 설명서 작성을 위해 사용될 패키지가 knitr 패키지라는 것을 명시해 주는 것이다. 위의 use_vignette 명령을 실행하고 나면 자동으로 r4issactoast.Rmd 파일이 열릴텐데, 파일의 앞부분에 다음과 같은 YAML 코드가 보일 것이다. 이 YAML 코드는 vignette 파일의 메타 데이터를 포함하고 있다.

---
title: "Vignette Title"
author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

위의 코드를 자신의 상황에 맞게 바꾸어주도록 하자. 필자의 설정은 다음과 같다.

---
title: "r4issactoast package vignette"
author: "Issac Lee"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    fig_caption: yes
vignette: >
  %\VignetteIndexEntry{r4issactoast package vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

output 부분의 fig_caption 부분은 r code chunk에 fig.cap = "Your figure caption." 부분을 추가하여 그림이나 그래프에 캡션을 추가할 수 있다.

Markdown에 대하여

예제로 주어진 Rmd 파일은 Rmarkdown 파일인데, 이 파일은 기존의 markdown 파일의 기능에 R 코드를 실행할 수 있는 기능을 추가한 것이므로, 기존에 markdown의 문법을 모두 사용할 수 있다. markdown은 미리 정의된 기호를 통하여 문서를 서식을 지정해 줄 수 있어서 사용자가 글의 내용에 집중 할 수 있도록 하기 위하여 고안된 언어이다. 이 언어에 대한 사용법은 Rstudio의 Pandoc Markdown 페이지 링크로 대체한다.

그림 넣기에 대한 팁

마크다운을 계속하다 보면 제일 짜증나는 케이스가 그림파일을 넣고 싶을 경우인데 필자는 다음과 같은 문법을 사용해서 그림을 넣고 있다. 다음 코드는 현재의 working directory 안의 mypic.png 파일을 너비 560픽셀로 가운데 정렬하고, “my caption”이라는 캡션을 달아주는 markdown 명령어이다.

<div align="center">
![my caption](./mypic.png){width=560}
</div>

위의 명령어도 매번 입력하려면 여간 귀찮은게 아닌데, 필자의 경우는 이 문제를 Rstudio의 add-in 매크로 으로 해결하고 있다. 즉, 다음의 코드를 입력하는 매크로를 작성하여 특정 키를 입력하면 아래의 구문이 생성하도록 설정해놓았다. (필자의 경우는 Ctrl + H, C or L or R을 입력하면 대응하는 정렬이 입력되어 나온다.)

<div align="right">
![](){width=690}
</div>

자세한 사항은 RStudio Addins 페이지와 필자가 짜놓은 add-in 패키지를 참고하자.

Vignette 작성 예

필자의 경우, 이전 포스팅에서 작성한 dpareto 함수의 설명을 다음과 같이 작성하였다.


##  Functions in r4issactoast

### dpareto

The probability density function of the pareto distribution.

$$
\frac{\alpha\,x_\mathrm{m}^\alpha}{x^{\alpha+1}}\text{ for }x\ge x_m
$$

where $x_m > 0$ and $\alpha > 0$.

#. usage
        
        dpareto(x, alpha, x_m, log.p = FALSE)

#. parameters

    `x` is the point where the pdf to be evaluated
    
    `alpha` is the shape parameter of pareto distribution
    
    `x_m` is the scale parameter of pareto distribution
    
    `log.p` is an indicator. Use log.p = TRUE when you want to get a result in a log scale.

#. return

    The pdf value of the pareto distribution with parameters alpha and x_m evaluated at x.
    
#. example
    
    ```r
    library(r4issactoast)
    dpareto(1:5, 2, 3)
    dpareto(1:5, 2, -3:3)
    dpareto(1:5, 2:5, 3)
    ```

이렇게 작성을 마치고 난 후 자신의 결과물을 보려면, Ctrl + Shift + k를 눌러주거나 kitr 버튼을 눌러주면된다.

패키지의 설치

devtools를 사용하여 깃허브에서 패키지를 설치하게되면 기본설정은 vignette을 같이 사용하지 않는 것으로 설정이 되어있다. 패키지 설치 시 vignettes을 같이 설치하려면 다음과 같이 build_vignettes 옵션을 활성화 시켜줘야 한다. 패키지 설치 후 vignette 명령어를 사용하여 자신이 작성한 패키지의 vignette이 잘 활성화 되는지 확인하자.

devtools::install_github(
  "issactoast/r4issactoast",
  build_vignettes= TRUE
)
vignette("r4issactoast")

Reference

[1] Wickham, Hadley. R packages: organize, test, document, and share your code. " O’Reilly Media, Inc.“, 2015.


SHARE TO

신고


티스토리 툴바