2014年8月29日 星期五

R CRAN 的 Package 上傳流程 (The Procedure of Uploading the R Package On R CRAN)

將製作好的 package 上傳到 R CRAN 的流程相當簡單。下面我們一起一步步帶各位將流程走過一次。若下述方法失效時,請參考「如何將 R package 上傳到 R CRAN」內文的舊方法上傳。感謝各位!

01.先到 R 的網站

02.選取左邊欄位的 CRAN,並尋找離自己國家最近的鏡像伺服器。


03.點選 Submitting to CRAN 下的 web form


04.詳細填寫姓名與電子郵件及將 package 檔案上傳,按下 Upload Package 。

再按下 submit 即完成上傳程序的第一步。



05.檢查電子郵件。待系統自動寄一封確認信到您的信箱。將信件打開,並點擊連結。

06.當網頁出現「The maintainer of this package has been sent an email to confirm the submission. After their confirmation the package will be passed to CRAN for review.」時,即完成第三步上傳程序。

管理者會寄一封信件給您,說明您的 package 已經送達到伺服器,請敬候佳音!

07.若您是 update 您的 package ,可以在 package 上傳後,到您 package 專屬的檢測網頁上,觀看更新進度。當完成時,伺服器便會自動寄信給您。下圖是筆者更新 cgAUC 套件的進度表,從圖中可以看到有些機器還尚在檢測此 package 中。

08.當所有機器都將您的 package 都檢測完畢後,便會寄信通知您。不過,通常當一半的機器檢測完畢後,便會先寄信通知您。您便可在 R CRAN 上找到您上傳的 source code package 。若您是用 Unix-like system ,那麼您已經可以下載來使用。但您的機器若是 Windows system ,則下載的 package 應該還會是舊的版本。此時,就是要多等一到兩天,或是等到所有機器都測試完畢,您便可下載 .zip 的套件檔案。

恭喜您!

All works were done in Ivan's Statistics Science Laboratory.

R CRAN 的 Package 上傳規範 (The R CRAN Repository Policy)

在完成 R package 後(請參考「利用 R-Studio 建立 R Package」與「利用 R-Studio 配合 Rcpp Package 建立包含 C/C++ Code 的 R Package」),接下來便是將此 package 上傳到 R CRAN 上,給大家使用您所想出來的絕妙方法。

當然,將東西放在網路上,自然也是要服從管理者所制訂的規範。那麼,就讓我們簡單的來看一下吧!

首先,讓我們來看看「 CRAN Repository Policy 」。這裡面詳細說明了當 R package maintainer 上傳 package 時,所需要注意的事情。以下簡述幾條各位在上傳時可能會發生的錯誤,因 Policy 的內容其實也沒那麼多,所以還是建議各位至少在上傳前細讀一次。

Preamble Section
00.文章一開始便說明當您上傳 package 時,便已同意 CRAN Repository Policy 所說明的每一件事情。所以各位還是耐著性子看一下。當然,若您在上傳 package 時,發生了任何問題,那些回信給您的自願者也會詢問與建議您看一下這份文件,所以…耐著性子,加油吧!

Source packages Section
01.對智財權的保障:
任何在 package 內所有引述或複製的部分,皆須清楚的註明來源與作者。當然,若您的程式碼是親手撰寫的,那麼這部分就沒有問題。

02.The package’s DESCRIPTION file 必須寫上 maintainer 的姓名與可聯絡的電子郵件。當然,如果您的 package 一旦有問題,自然會循此電子郵件去找您。所以,請還是留下正確的電子郵件吧!

03.對使用者電腦安全性的保障:
所遞交的 Source packages ,裡面不可包含任何形式的 binary executable code 。

04.跨平台的通用性:
Package authors 應該盡可能的將 package 內的程式碼,努力提供跨平台(例: Windows 與 Unix-like )上的使用。這部分還蠻有趣的,過去經常有 package 僅能在某些平台上使用。增加這部分的規範,自然是要增加 R 的泛用性。

05.Package 的獨立性:
Packages 的名稱不能與過去在 CRAN 既有的 package 或是在 Bioconductor 上的 packages 名稱相同。所以,請您在為您的 package 取名之前,先到上述的兩個網站上搜尋一下是否有重複的名稱?!

06.Package 的容量限制:
Packages 內含的資料或是文件,不可超過 5 MB 。

07.Package 的檢查時間與硬體控制限制:
檢查 package 時,應盡可能的快,最好是能在幾秒內完成。別忘了, CRAN 現在可是有數千個 package 在上面,且隨時都有人更新或增加。如果您的例子會讓您的 package 跑很久的話,不妨將這些例子標記為註解就好。另外,若 package 有用到多核心處理時,目前的限制為同一時間僅能使用2個核心。

08.Package 的安全性:
Package 內含的程式碼與範例,不應對使用者的電腦與 R 主體有任何惡意的修改或破壞。以下的範例說明很多,請各位簡單看一下。

Submission Section
01.請將 package 在 http://CRAN.R-project.org/submit.html 內上傳,上傳完成後,系統會寄一封確認信件給您。收到信件後,按下信件內的確認連結,即完成上傳動作。若此方法無效,請參考「如何將 R package 上傳到 R CRAN」一文,使用舊方法。

02.上傳的 package 檔案,必須為 source tarballs 檔案,也就是 .tar.gz 檔案。

03.在上傳 package 檔案之前,必須先用 R CMD check --as-cran 過,且在整個檢查的過程中,不能出現任何的 warnings 或 errors 。若您有無法消除的 warnings 或認為所出現的 warnings 是可接受的,請在提交 package 時一併註明。

04.若您是對您過去的 package 做更新,在您上傳您的 package 之後,請在專屬於您的套件網站做進度查詢。例:您的套件名稱為「 cgAUC 」,那麼,請將 http://CRAN.R-project.org/web/checks/check_results_NAME.html 網址內的 NAME 改為 cgAUC ,變成 http://CRAN.R-project.org/web/checks/check_results_cgAUC.html ,便可查詢。然而,在結果尚未公布之前,請勿再進行任何新版本的上傳。直到所有結果測試完畢,方可繼續上傳新的版本。


基本上,簡單的原則是,只要在 R 檢查 package 的操作上沒出現任何 warnings 或 errors ,套件名稱也沒有重複,跨平台可執行,那麼 package 都會符合 CRAN 所制訂的規範。好了,解釋了這麼多,不妨參考下一篇文章:「R CRAN 的 Package 上傳流程」,讓我們一起來遞交一份熱騰騰的 package 吧!

All works were done in Ivan's Statistics Science Laboratory.

利用 R-Studio 配合 Rcpp Package 建立包含 C/C++ Code 的 R Package (Build R Package Including C/C++ Code by Using R-Studio and Rcpp Package)

在「利用 R-Studio 建立 R Package」一文中提到用簡單的方式一步步建立 package 。然而,若所建構的函式,是用 R code 所撰寫,在執行的效率上,相較於用 C/C++ code 來撰寫,會來的較沒效率。若所撰寫的演算法稍微複雜一點或甚至遇到較大量的資料,則 R code 的優勢便削減許多。為了避免 R code 在運算時的低效率特性,我們可將一部份較為複雜的演算法的 R code 轉寫為 C/C++ code 。如此便可大大的增加其運算的效率。

下圖為筆者將同一套演算法的 R code 改寫為 C code 後,跑效能測試後的比較圖。很明顯可以看出,無論是何種 condition , C code  的效能遠比 R code 要來的好很多!

而過去若要將 C/C++ code 包進 package 中,不僅要建立 src 資料、編寫 NAMESPACE 、針對 C/C++ code 進行 compile 等等繁複的程序。在過程中,又常出現許多五花八門的錯誤訊息,讓人摸不著頭緒。所幸,由 Dirk Eddelbuettel, et al. 所發展的 Rcpp package 被整合在 R-Studio 中,讓我們可以用較為簡單的方式,建立一個含有 C/C++ code 的套件。當然,如果您早已習慣 R 原有的操作介面,您也可以參考「 Writing a package that uses Rcpp 」這篇手冊。那麼,以下我們便以 R-Studio 的介面,帶大家一步步邁向目標。

環境說明:
處理器:Intel(R) Core(TM)2 Qual CPU Q9550 @ 2.83 GHz 2.83 GHz
記憶體:8.00 GB

作業系統:Windows 7; Service Pack 1; 64 位元
R 版本:3.1.0 (2014-04-10) for Windows; Spring Dance
Rtools 版本: Rtools 3.1 for Windows
R-Studio 版本:RStudio 0.98.1028 - Windows XP/Vista/7/8

01.開啟 R-Studio。

02.安裝 Rcpp package 。在「Console」區塊中輸入「install.packages("Rcpp")」

03.建立新專案:點選 File → New Project... 或者點選右上角的 Project 圖示 → New Project...

04.點選 New Directory

05.點選 R Package

06.在「Type:」中點選 Package w/ Rcpp ,並在「Package name」中輸入您的套件名稱。接著按下「Create Project」


07.你將看到 R-Studio 的右下區塊有產生出建立 R package 時,所需要的檔案。若只單純建立 R package 則沒有 src 資料夾(此資料夾是用來存放 C/C++ code )。

08.將 R 資料夾內的 RcppExports.R 與 src 資料夾內的 rcpp_hello_world.cpp 與 RcppExports.cpp 三個檔案開啟,並進行編輯。

在「 RcppExport.R 」檔案中,您可以編輯任何用 R code 寫的函式。當然,您也可以建立新的 .R 檔案進行編輯。在「 R 」資料夾底下的 .R 檔案,皆是以 R code 來執行。

在「 rcpp_hello_world.cpp 」檔案中,您可以編輯任何用 C/C++ code 寫的函式。當然,您也可以建立新的 .cpp 檔案進行編輯。在「 src 」資料夾底下的 .cpp 檔案,皆是以 C/C++ code 來執行。

在「 RcppExports.cpp 」檔案中,主要是將您在 rcpp_hello_world.cpp 檔案中所撰寫的函式與內含的變數做補述。這是因為原始的 C/C++ code 寫起來相當的繁複,而 Rcpp package 已經協助我們將複雜的部分自動做好,使我們在撰寫 C/C++ code 時,不用作太細緻的撰寫。原則上,我們並不需要特別撰寫這個檔案。

(Note: 詳細撰寫 C/C++ code 的部分,在此並不詳述,請具備一些 C/C++ 的基本知識,或從閱讀 Package 'Rcpp'Rcpp: Seamless R and C++ Integration 中學習。)

09.編輯好所有 R code 與 C/C++ code 函式、DESCRIPTION、NAMESPACE及所有.Rd檔案後,點擊功能表列上的「Build」→「Build and Reload」


10.R-Studio 便會執行 Rcmd.exe 檔案,檢查你的 package 是否有錯誤。若執行都正常後,軟體會自動載入建置好的 package ,如此便可立即使用。

11.若想將 package 給別的使用者使用,便要建立 .zip 檔案。請點選「Build」→「Build Binary Package」,系統便會進行一連串的檢查程序。

若都沒有問題,便會將建構好的 .zip 檔案放置在預設的資料夾中。如此便可將此檔案傳遞給所需要的使用者使用。

12.若想上傳到 CRAN 上,則必須建立 .tar.gz 檔案。但由於上傳到 CRAN 上時, package 必須符合 R CRAN team 所制訂的規範(請參考 CRAN Repository Policy 或參考「R CRAN 的 Package 上傳規範」)。所以,在建立 .tar.gz 檔案前,必須先執行套件的檢查。請點選「Build」→「Check Package」


13.R 便會進行一連串的項目檢查,待檢查完畢並確認無任何警告(Warning)或錯誤(Error)訊息後,即檢查完成。下圖右上區塊為檢查後的結果;右下方為檢查後會出現兩個額外的資料夾:「 src-i386 」與「 src-x64 」,分別給32與64位元系統使用;左邊區塊則為執行預設函式的結果。


14.建立 tar.gz 檔案。點擊「Build」→「Build Source Package」

若都沒有問題,便會建立 .tar.gz 檔案。


其檔案放置在預設的資料夾中。


15.前往 R website 中的 web form 進行套件提交,提交流程請參考「R CRAN 的 Package 上傳流程」。在提交前,請確實閱讀 CRAN Repository Policy 或參考「R CRAN 的 Package 上傳規範」。

16.若您有任何想增加 Rcmd.exe 執行時的參數時,請點選「Build」→「Configure Build Tools...」

便可針對需要的項目進行更改。

如果您無法複製上述的任何步驟,或在過程當中出現錯誤,請讓我知道,方便我協助您,感謝!

All works was done in Ivan's Statistics Science Laboratory.

2014年8月28日 星期四

利用 R-Studio 建立 R Package (Build R Package by Using R-Studio)

先前的一篇文章:「如何製作一個專屬於自己的 R package」提及建立 R package 的流程與安裝軟體。但在流程中,所需安裝的軟體與變數的設定太過繁瑣,對一般的使用者來說,會操作的相當辛苦。所幸,在眾人的努力下,許多流程皆已利用程式設定好指令與參數。使用者再也不用一步步去做設定,只需將自己的函式功能撰寫好,剩下的就交給 R-Studio 就好!

環境說明:
處理器:Intel(R) Core(TM)2 Qual CPU Q9550 @ 2.83 GHz 2.83 GHz
記憶體:8.00 GB

作業系統:Windows 7; Service Pack 1; 64 位元
R 版本:3.1.0 (2014-04-10) for Windows; Spring Dance
Rtools 版本: Rtools 3.1 for Windows
R-Studio 版本:RStudio 0.98.1028 - Windows XP/Vista/7/8

01.開啟 R-Studio。

02.建立新專案:點選 File → New Project... 或者點選右上角的 Project 圖示 → New Project...

03.點選 New Directory

04.點選 R Package

05.輸入 package 名稱後,再點選 Create Project

06.你將看到 R-Studio 的右下區塊有產生出建立 R package 時,所需要的檔案。接著,在 R-Studio 中,進入 R 資料夾。

這些檔案將放在您預設的目錄中,且資料夾以套件名稱命名。

07.點擊 MyPackage.R 後,便可在左上區塊編輯你所需要的函式。

08.編輯好函式、DESCRIPTION、NAMESPACE及所有.Rd檔案後,點擊功能表列上的「Build」→「Build and Reload」

09.R-Studio 便會執行 Rcmd.exe 檔案,檢查你的 package 是否有錯誤。若執行都正常後,軟體會自動載入建置好的 package ,如此便可立即使用。

10.若想將 package 給別的使用者使用,便要建立 .zip 檔案。請點選「Build」→「Build Binary Package」,系統便會進行一連串的檢查程序。


若都沒有問題,便會將建構好的 .zip 檔案放置在預設的資料夾中。如此便可將此檔案傳遞給所需要的使用者使用。


11.若想上傳到 CRAN 上,則必須建立 .tar.gz 檔案。但由於上傳到 CRAN 上時, package 必須符合 R CRAN team 所制訂的規範(請參考 CRAN Repository Policy 或參考「R CRAN 的 Package 上傳規範」)。所以,在建立 .tar.gz 檔案前,必須先執行套件的檢查。請點選「Build」→「Check Package」

12.R 便會進行一連串的項目檢查,待檢查完畢並確認無任何警告(Warning)或錯誤(Error)訊息後,即檢查完成。

若在檢查的過程當中,發生 warnings 、 errors 或未知的訊息請參考「R Check Package 常見的 warnings 、 errors 及 未知的訊息」一文。(撰寫中…)

13.建立 tar.gz 檔案。點擊「Build」→「Build Source Package」

若都沒有問題,便會建立 .tar.gz 檔案。


其檔案放置在預設的資料夾中。


14.前往 R website 中的 web form 進行套件提交,提交流程請參考「R CRAN 的 Package 上傳流程」。在提交前,請確實閱讀 CRAN Repository Policy 或參考「R CRAN 的 Package 上傳規範」。


15.若您有任何想增加 Rcmd.exe 執行時的參數時,請點選「Build」→「Configure Build Tools...」

便可針對需要的項目進行更改。

如何,夠簡單吧!=D

如果您無法複製上述的任何步驟,或在過程當中出現錯誤,請讓我知道,方便我協助您,感謝!

All works were done in Ivan's Statistics Science Laboratory.