본문으로 바로가기



Make your own R package! - 4. 나만의 함수 추가하기 with roxygen2

category R Programming/Rpackage 2017.07.05 23:09
Make your own R package! - 4. 나만의 함수 추가하기 with roxygen2

이번 포스팅에서 사용될 R 패키지는 다음과 같다.

library(devtools)
library(roxygen2)

저번 포스팅을 통해서 필자는 DESCRIPTION 파일 설정에 대하여 알아보았다. 이번 시간에는 함수를 추가하는 방법에 대하여 알아보도록 하자.

추가할 함수 마련하기

필자가 r4issactoast패키지를 만들기로 결심한 것은 최근의 통계 포스팅 시리즈를 연재하면서 부터이다. 따라서 필자는 예전에 만들어놓은 감마분포의 MOME 함수를 패키지에 넣도록 하겠다. 함수는 다음과 같다.(함수와 관련된 내용은 이전 포스팅을 참고하자.)

mom_gamma <- function(sample_g){
    x_bar  <- mean(sample_g)
    x2_bar <- mean(sample_g^2)
    
    mom_theta <- (x2_bar - x_bar^2) / x_bar
    mom_k <- x_bar / mom_theta
    
    list(k_hat = mom_k, theta_hat = mom_theta)
}

위의 코드를 패키지의 R폴더에 inference.R 파일을 만들고 붙여넣고 저장하자. 또한, 이제는 필요가 없는 R폴더의 hello.R 파일과 mam폴더의 hello.Rd 파일은 삭제하도록 한다.

패키지 폴더 구조

패키지 폴더 구조

그 다음 Build 탭의 Check 버튼을 눌러보면, 다음과 같은 경고 메세지가 뜨는 것을 알 수 있다.

mom_gamma 함수에 대한 warning 메세지

이 경고 메세지는 우리가 방금 패키지에 넣은 mom_gamma() 함수에 대한 문서가 없다는 내용이다. 즉, 사용자가 우리의 패키지를 설치한 후 mom_gamma()를 사용하려 할 때 보여줄 정보가 없으므로, 사용자는 코드를 직접 보기 전까지는 함수가 어떠한 입력값을 가지고, 결과값은 어떤 형식인지에 대한 정보를 알 수 없는 것이다.

이전 패키지의 구조를 살펴본 포스팅에서 패키지의 man 폴더에 .Rd 파일이 이러한 역할을 한다고 배웠다. 그리고 우리는 아직 mom_gamma 함수에 대한 설명서 파일을 만들지 않았기 때문에, 이러한 경고 메세지가 나오는 것이다.

roxygen2 패키지를 이용한 설명서 관리 자동화

본론으로 들어가서, 이러한 경고 메세지를 안 받기 위해서는 각 함수별로 .Rd 파일을 작성해야 한다. roxygen2 패키지는 이러한 함수 설명서 파일 작성을 R코드 안의 #'태그를 이용하여 자동화 시켜준다. roxygen2를 이용할 경우 두 가지 큰 장점이 있는데,

1. 함수별 설명서 파일(.Rd)를 만들어줄 필요가 없어진다.
2. NAMESPACE 파일을 손 댈 필요가 없어진다.

1번 만으로도 정말 좋은데, 2번까지 해주면 ‘정말이지 고맙습니다..ㅠ’ 라는 생각이 든다.

roxygen2 패키지는 일반적인 코멘트는 #와 차별을 위해서 #' 기호를 사용하여 태그를 인식한다.(엔터 왼쪽에 있는 ‘작은따옴표’ 키이다.) 아래와 같이 inference.R 파일 안에 정의된 함수의 위쪽에 roxygen 코멘트를 붙여주자.

#' Method of Moments Estimator for gamma dist.
#'
#' mom_gamma function will calculate mom estimate for the shape parameter "k" and the scale parameter "theta" by using given sample.
#'
#' @param sample_g the given sample to calculate the estimate of the parameters.
#' @return A 2 by 1 vector containing estimate of parameters k and theta: c(k, theta)
#' @examples
#'   my_sample <- rgamma(50, shape = 2, scale = 3)
#'   mom_gamma(my_sample)
#' @export
mom_gamma <- function(sample_g){
    x_bar  <- mean(sample_g)
    x2_bar <- mean(sample_g^2)
    
    mom_theta <- (x2_bar - x_bar^2) / x_bar
    mom_k <- x_bar / mom_theta
    
    list(k_hat = mom_k, theta_hat = mom_theta)
}
  • Title: 먼저 제일 위쪽에 자리잡은 줄은 설명서 제목으로 사용된다.
  • Description: 제목에서 한줄을 뗀 다음 줄은 설명서에서 함수의 description란에 위치하게 된다.
  • @param: 함수에 들어가는 입력값(parameter)을 명시해주고, 이에 대한 설명을 써주면 된다.
  • @return: 함수의 결과값에 대한 설명을 써준다.
  • @example: 함수를 실제로 어떻게 적용하는지에 대한 예를 적어주면 된다. 이 부분은 배포를 염두해 두고 있는 입장이라면 신경을 가장 많이 써야한다. 예제가 부실한 패키지는 사용하기도 싫어지기 때문이다.
  • @export: 이 태그는 설명서가 아닌 NAMESPACE에 대한 태그이다. 이 태그를 붙이게 되면 패키지를 설치한 사용자가 mom_gamma() 함수를 사용할 수 있게 된다. 태그의 의미 그대로 함수를 패키지의 밖으로 내보낼 수 있도록 만들어 준다.

roxygen2 패키지의 적용

이제 roxygen2 패키지를 적용할 수 있는 준비가 다 되었다. roxygen2을 사용하여 설명서 파일을 작성하는 것은 아주 쉽다. 그냥 devtools::document() 함수를 실행시켜주면 자동으로 roxygen2 패키지를 사용해서 설명서와 그 외의 것들을 처리해주기 때문이다. 단, roxygen2패키지가 NAMESPACE 파일까지 자동으로 처리하게끔 하기 위해서는 현재 패키지 폴더의 NAMESPACE 파일을 지워줘야 한다. 따라서, 우리가 할 일은 다음과 같다.

  1. 패키지 폴더에 있는 NAMESPACE 파일을 삭제한다.
  2. 콘솔창에 devtools::document() 명령어를 입력한다.

이것으로 인해 바뀌는 점은 3가지 이다.

  1. man 폴더에 mom_gamma.Rd 파일이 생성된다. 파일을 Preview 해보면 다음과 같은 문서가 생성되는 것을 알 수 있다.
    mom_gamma.Rd preview

    mom_gamma.Rd preview

  2. DESCRIPTION 파일의 내용에 RoxygenNote: 항목이 추가된다. 패키지 작성에 roxygen이 이용되었다는 것을 나타내는 것으로 생각된다.
  3. NAMESPACE 파일의 내용에 아래와 같은 내용이 추가 된다. 아래에서 보여지는 것처럼 앞으로 NAMESPACE 파일은 건드리지 않아도 된다.
# Generated by roxygen2: do not edit by hand
export(mom_gamma)

패키지 확인

Rstudio의 빌드(Build)탭에서 제공하는 check 버튼을 누르면 이전에 보였던 경고 메세지가 더 이상 나오지 않는 것을 알 수 있다.

roxygen2 적용 후 check 결과

roxygen2 적용 후 check 결과

변경된 사항을 Git > Commit을 누른 후, 변경 사항을 간략히 입력하고 Commit 버튼과 Push를 차례로 눌러 Github에 변동사항을 반영하도록 하자. 이제 패지키가 잘 작동하는지 확인하기 위하여 다음의 명령어를 사용하여 패키지를 설치 후 함수를 사용해보자.

devtools::install_github("issactoast/r4issactoast")
library(r4issactoast)
my_sample <- rgamma(100, shape = 2, scale = 4)
mom_gamma(my_sample)
##     k_hat theta_hat 
##  1.943065  3.984109

마치며

사실 패키지를 만들어서 배포 한다는 것은 엄청 피곤한 일이 된다. 왜냐하면 자신이 짠 코드를 사용자에게 설명해야하며, 이용하기에 불편하지 않게 하만드는 일련의 과정이 제작자의 몫이기 때문이다. (그렇지 않으면 사용자는 다른 편리한 패키지를 찾아 떠나게 된다.) 하지만 어렵게 짠 자신의 코드의 사용성을 증가시키는 일은 보람된 일이며, 사실 어렵게 짠 코드는 시간이 지나고 나서 다시보면 자기 자신도 어떻게 짰었는지 까먹는 일이 (필자는) 부지기수이기 때문에 사용 설명서 작성은 중요하다. 이번 시간에 패키지에 추가한 함수는 순수한 R코드 만을 사용한 함수였다. 다음 시간에는 다른 패키지에서 함수를 빌려와 함수를 작성했을 경우, 패키지의 dependense를 어떻게 설정해야 하는지에 대하여 알아보도록 하겠다.

참고 문헌

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

[2] Jennifer (Jenny) Bryan, Write your own R package STAT 545

[3] 오픈소스SW라이선스 종합정보시스템 (https://olis.or.kr/license/introduction.do)

[4] Writing R extension (https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file)


SHARE TO



티스토리 툴바