Narzędzia użytkownika

Narzędzia witryny


r_pakiet_howto

Jak stworzyć pakiet R zgodnie ze sztuką?

Na początku wypada odnieść do biblii - http://r-pkgs.had.co.nz

W skrócie:

  • Zakładamy repozytorium dla pakietu na GitHub-ie
  • Tworzymy projekt RStudio powiązany z repozytorium GitHub-a.
  • Konfigurujemy projekt, tak by używać:

co zostanie opisane poniżej.

Zakładanie repozytorium pakietu na GitHub-ie

Jednorazowe czynności wstępne

  • Instalujemy git-a:
    • pod Windows:
    • na Macu
    • pod Linuksem:
      • instalujemy z paczek (np. pod Debianem/Ubuntu: sudo apt-get install git)
  • Jeśli nie mamy jeszcze konta na GitHub-ie, zakładamy je.
  • Generujemy sobie klucz SSH i rejestrujemy go na GitHub-ie (dzięki temu nie będziemy musieli podawać loginu i hasła podczas komunikacji z repozytorium):
    • pod Windowsami
      • uruchamiamy aplikację GitHub-a i przechodzimy kreator rejestracji konta
    • na Macu
      • uruchamiamy aplikację GitHub-a i przechodzimy kreator rejestracji konta
    • pod Linuksem

Zakładanie repozytorium

  • Logujemy się na nasze konto na GitHub-ie
  • Klikamy ikonkę + (czwarta od prawej na górnej belce) i wybieramy New repository
  • Wypełniamy:
    • w Repository name wpisujemy nazwę pakietu
    • wybieramy typ repozytorium Public
    • zaznaczamy Initialize this repository with a README
    • wybieramy Add .gitignore: R
    • wybieramy Add a license: MIT License
    • klikamy Create repository

Zakładanie projektu RStudio dla pakietu

  • File→New Project…
  • Wybieramy Version Control
  • Wybieramy Git
  • W kolejnym okienku:
    • W Repository URL wpisujemy git@github.com:{nazwa_użytkownika}/{nazwa pakietu}.git, np. git@github.com:zozlak/ZPD.git (użytkownik zozlak, pakiet ZPD)
    • wskazujemy katalog, w którym zostanie umieszczony katalog projektu przycikiem Browse…
    • klikamy Create Project

Konfigurujemy projekt RStudio

  • W rolecie Files klikamy na pliku {nazwa pakietu}.Rproj (np. ZPD.Rproj)
  • W zakładce General wybieramy:
    • Restore .RData into workspace at startup: No
    • Save workspace to .RData on exit: No
  • W zakładce Code Editing:
    • upewniamy się, że Text encoding: to UTF-8
  • W zakładce Build Tools…:
    • z listy Project build tools: wybieramy Package
    • zaznaczamy Use devtools package functions if available
    • zaznaczamy Generate documentation with Roxygen, a następnie pod przyciskiem Congfigure… obok:
      • Use roxygen to generate: - zaznaczamy Rd file, Collate field, NAMESPACE file
      • Automatically roxygenize when running - zaznaczamy wszystko (R CMD check, Source and binary package builds, Build & Reload)
  • Zatwierdzamy OK
  • Konstruujemy szkielet pakietu poleceniami (w konsoli R):
    devtools::setup()
  • Edytujemy plik DESCRIPTION
    • zupełniamy pola Title, Desciption i Authors@R
    • w pole License: wpisujemy MIT + file LICENSE
    • dopisujemy pola:
      • Encoding: UTF-8
      • VignetteBuilder: knitr
      • Suggests: knitr, testthat
  • Edytujemy plik README.md (stronę powitalną umieszczaną na GitHub-ie), tak by zawierał krótki opis pakietu oraz instrukcję instalacji, patrz np. README.md
  • Zatwierdzamy zmiany i wypychamy na serwer:
    • w rolecie Git zaznaczamy wszystkie pliki i klikamy Commit
    • podajemy opis commitu i zatwierdzamy przyciskiem Commit
    • wysyłamy je na GitHub-a przyciskiem Push

Korzystanie z gałęzi w Gicie

Tzw. gałęzie to świetny wynalazek, który pozwala nam nie narażać końcowych użytkowników pakietu na obcowanie z nanoszonymi przez nas w kodzie zmianami (np. dodawaniem nowych funkcji) tak długo, jak długo nie zostaną one doprowadzone do etapu produkcyjnego, jednocześnie umożliwiając wspólną pracę na rozwijanym kodzie.

Z filozofią używania gałęzi można zapoznać się np. tutaj: http://nvie.com/posts/a-successful-git-branching-model

A sposób używania gałęzi w RStudio opisany został np. na stronie Christiana Lempa.

Więcej informacji o sposobie używania gałęzi Gita w RStudio znajduje się na podstronie poświęconej używaniu Gita.

Korzystanie z Roxygen-a

Winietka pakietu roxygen2: https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html

Materiały o dokumentowaniu pakietów R przy pomocy Roxygena na stronie Hadley'a Wickhama.

Testy

Materiały o pisaniu testów do pakietów R na stronie Hadley'a Wickhama.

Jednostkowe

Integracyjne

Pokrycia

r_pakiet_howto.txt · ostatnio zmienione: 2016/08/24 17:31 przez t.zoltak