Cara menulis pakej R

Apabila anda melihat "Pakej R", anda mungkin berfikir "Sesuatu untuk dikongsi dengan orang lain." Tetapi pakej R juga boleh menjadi kaedah yang baik untuk mengatur kerja anda sendiri untuk diri anda sendiri . Dan terutama masa depan anda.

Pakej R memberi anda struktur yang konsisten, jadi anda lebih cenderung mengubah kod menjadi fungsi. Dan, paling tidak penting: Pakej memberi anda kaedah yang konsisten untuk mendokumentasikan setiap fungsi anda. Oleh itu, tahun depan, ada kemungkinan lebih baik anda ingat bahagian kod anda yang melakukan apa.

Penyediaan sistem

Pertama, anda ingin menyediakan sistem anda. Untuk pembangunan pakej yang mudah, saya cadangkan untuk memastikan pustaka ini dipasang pada sistem anda: devtools, usethis, roxygen2, testthat, knitr, dan rmarkdown.

Anda mungkin memerlukan sedikit persediaan sistem juga. Di Windows, pasang perisian yang dipanggil Rtools. Itu sebenarnya aplikasi perisian, bukan pakej R. Pada Mac, sangat berguna untuk mendapatkan Xcode dari App Store.

Sekiranya anda tidak pasti sama ada sistem anda siap untuk menulis pakej, devtools mempunyai fungsi yang disebut has_devel()yang memeriksa sama ada persekitaran pengembangan pakej anda OK. Saya cadangkan menjalankannya setelah anda memasang devtools.

Sharon Machlis /

Seterusnya, anda boleh membuat pakej baru di RStudio dengan pergi ke File> New Project> New Directory dan memilih R Package.

Anda akan diminta untuk nama pakej dan adakah anda ingin membuat repositori Git (yang biasanya saya lakukan) dan menggunakan packrat (yang biasanya tidak saya lakukan).

Di panel kanan bawah setelah membuat pakej, perhatikan bahawa beberapa fail dan dua direktori telah dibuat. 

Subdirektori R adalah tempat tinggal semua skrip R saya. Folder lelaki adalah untuk dokumentasi — khususnya, fail bantuan fungsi . RStudio juga membuat contoh hello.Rfungsi R.

Terdapat juga beberapa fail penting di direktori utama. Menjelaskan NAMESPACEboleh menjadi artikel dengan sendirinya, tetapi pemula boleh bergantung pada devtools dan pakej ini menguruskannya.

DESCRIPTIONmempunyai beberapa metadata penting yang diperlukan mengenai pakej, jadi anda perlu mengisinya. Ini adalah perkara yang mudah seperti nama pakej, pengarang, keterangan dan lesen. Ini juga ke mana pergantungan pakej pergi.

Pakej ini dapat menangani format pergantungan pakej yang sesuai untuk anda. Sebagai contoh, jika anda memerlukan paket pelumas untuk pakej anda, anda boleh memuatkannya library(usethis)dan kemudian jalankan use_package("lubridate")untuk menambahkan kebergantungan. Anda dapat melihat bagaimana ini secara automatik menambahkan teks yang diperlukan ke DESCRIPTIONfail dalam video yang disematkan di bahagian atas artikel ini (atau dengan menjalankan kod serupa pada sistem anda sendiri).

Tulis dan dokumentasikan fungsi anda

Seterusnya, tulis fungsi seperti biasa, dan simpan sebagai skrip R di direktori R. Anda boleh menamakan fail apa sahaja yang anda mahukan, dan anda boleh memasukkan satu atau lebih fungsi dalam fail tersebut.

Roxygen menawarkan cara mudah untuk menambahkan dokumentasi ke fungsi. Letakkan kursor anda di mana sahaja dalam definisi fungsi dan pilih pilihan menu RStudio Kod> Masukkan Skeleton Roxygen.

Itu memberi anda beberapa perancah untuk mendokumentasikan fungsi dengan cara yang difahami oleh R, seperti 

# 'Tajuk

# '

# '@param hari

# '

# '@pulangan

#' @eksport

# '

#' @contoh

Medan Tajuk cukup jelas, dan anda juga boleh menambah baris untuk penerangan ringkas. Terdapat @paramgaris untuk setiap argumen fungsi (dalam contoh ini, fungsi tersebut mempunyai satu argumen yang disebut day) @return, dan @examples. @paramadalah tempat anda mendokumentasikan jenis data yang seharusnya menjadi argumen dan dapat memberikan sedikit penerangan. @returnmemberitahu apa jenis objek yang dikembalikan. @examplestidak diperlukan, tetapi anda perlu memberi contoh atau menghapus lalai itu @examples.

Untuk mengubah perancah ini menjadi fail bantuan paket R, jalankan devtools::document()fungsinya.

Sekarang jika anda melihat di direktori man, anda harus mempunyai fail bantuan Markdown untuk fungsi baru anda (dan juga yang lain untuk hellofungsi lalai ).

Sharon Machlis,

Anda boleh membina pakej menggunakan tab RStudio Build. Pilihan Pasang dan Mulakan Semula sesuai untuk anda ketika anda sedang mengerjakan kod anda. Apabila anda ingin membuatnya untuk berkongsi, termasuk mendapatkan fail sumber atau fail binari, lihat dropdown Lagi di tab Build.

Jalankan help(package = "yourpackagename")untuk mendapatkan fail bantuan untuk fungsi baru.

Sekiranya anda ingin menulis sketsa pakej, jalankan use_vignette()fungsi pakej ini untuk menetapkannya. Sertakan nama vinyet yang anda mahukan sebagai argumen, seperti usethis::use_vignette("Intro"). Anda akan melihat sketsa lalai, di mana anda boleh mengisi tajuk dan teks penjelasan vignet tersebut.

Mudah-mudahan itu cukup untuk meyakinkan anda bahawa cukup mudah untuk menulis pakej R asas! Masih banyak yang boleh anda lakukan, seperti menambahkan ujian unit dengan ujian yang.

Sekiranya anda ingin mengetahui lebih lanjut mengenai pengujian, lihat catatan Do More With R saya yang lebih awal "Uji kod anda dengan ujian yang". Dan Hadley Wickham mempunyai keseluruhan buku mengenai pakej penulisan, tersedia dalam talian percuma di r-pkgs.had.co.nz, walaupun sekarang agak ketinggalan zaman. Jenny Bryan di RStudio bekerjasama dengan Wickham dalam kemas kini. Anda dapat melihat sedikit kerja yang sedang dijalankan di r-pkgs.org.