15 Pakiety

Pakiety są powszechnie wykorzystywane podczas pracy z językiem R. Celem sekcji 3.5 było wprowadzenie do tego czym one są, jak się je instaluje oraz dołącza. Najważniejszą tam informacją było, że pakiety są zorganizowanymi zbiorami funkcji. Oznacza to, że nie tylko posiadamy pewną liczbę stworzonych funkcji, ale także są one ułożone w pewien ustalony sposób. Funkcje w pakietach posiadają też swoją dokumentację (jej struktura została przedstawiona w sekcji 3.4) czy przykładowe dane. Pakiety, oprócz swojej unikalnej nazwy, posiadają również informacje o swojej wersji, autorach, zależnościach i licencji.

Informacje w tym rozdziale powinny pozwolić na stworzenie podstawowego pakietu R. Istnieje jednak wiele dodatkowych aspektów i kwestii w tym temacie, które zostały tutaj wspomniane pobieżnie lub pominięte. W celu poznania i zrozumienia złożonych aspektów tworzenia pakietów R cennymi źródłami wiedzy może być książki R packages (Wickham 2015) oraz rOpenSci Packages: Development, Maintenance, and Peer Review (rOpenSci et al. 2019). Dodatkowo, w niektórych przypadkach pomocna może być oficjalna dokumentacja Writing R Extensions (R Core Team 2019).

15.1 Nazwa pakietu

Nazwa nowego pakietu musi spełniać kilka wymagań: składać się tylko ze znaków ASCII, cyfr i kropek, mieć co najmniej dwa znaki oraz zaczynać się od litery i nie kończyć się kropką (R Core Team 2019). Ważne jest również myślenie o nazwie pakietu tak jak o nazwach funkcji (sekcja 2.4) - nazwy pakietów powinny ułatwiać zrozumienie ich zawartości. Dodatkowo, z uwagi na istnienie wielu pakietów warto najpierw sprawdzić czy pakiet o wymyślonej przez nas nazwie już nie istnieje. Można to przykładowo zrobić używając pakietu available (Ganz et al. 2019), który sprawdza przy wybrana nazwa nie jest już zajęta oraz czy nie ma ona jakiegoś niepożądanego przez nas znaczenia.

15.2 Tworzenie szkieletu pakietu

Kolejnym krokiem jest stworzenie szkieletu pakietu, czyli zorganizowanego zbioru plików i folderów, do których później należy dodać odpowiednie informacje i funkcje. Znacznie w tym może pomóc pakiet usethis (Wickham and Bryan 2020), który zawiera szereg funkcji ułatwiających budowanie pakietów R.

library(usethis)

Do stworzenia szkieletu pakietu służy funkcja create_packages(), w której należy podać ścieżkę do nowego pakietu. W tej ścieżce ostatnia nazwa folderu określa również nazwę pakietu.55

usethis::create_package("~/Documents/mojpakiet")

W efekcie działania powyższej funkcji stworzony zostanie nowy folder mojpakiet zawierający kilka plików oraz otwarty zostanie nowy projekt RStudio zawierający ten pakiet. Najważniejsze nowe pliki to:

  1. mojpakiet.Rproj - plik projektu RStudio
  2. DESCRIPTION - plik zawierający podstawowe informacje o pakiecie
  3. R/ - w tym pustym folderze konieczne będzie umieszczenie nowych funkcji R
  4. NAMESPACE - ten plik określa, między innymi, jakie funkcje są dostępne w tym pakiecie. Ten plik i jego zawartość jest tworzona automatycznie

Dodatkowo w prawym górnym panelu RStudio pojawi się nowy panel “Build”.

15.3 Opis pakietu

Plik DESCRIPTION zawiera opis (metadane) pakietu, w tym jego nazwę, tytuł, wersję, autorów, opis, czy licencję.

Package: mojpakiet
Title: Moje Funkcje Robiace Wszystko
Version: 0.0.1
Authors@R: 
    person(given = "Imie",
           family = "Nazwisko",
           role = c("cre", "aut"),
           email = "imie.nazwisko@example.com")
Description: Tworzenie, przeliczanie i wyliczanie wszystkiego. 
    Czasami nawet więcej.
License: CC0
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.1.1

Tytuł pakietu (Title:) w jednym krótkim zdaniu (sloganie) określa do czego służy ten pakiet.56 Składa się on ze słów rozpoczynających się z dużej litery.

Wersja pakietu (Version:) pozwala jego użytkownikom na zobaczenie, czy korzystają z aktualnej wersji pakietu. Zalecanym sposobem określania wersji pakietu jest stosowanie trzech liczb pierwsza.druga.trzecia, np. 0.9.1. Zmiana trzeciej liczby służy do pokazania, że zaszła niewielka zmiana w kodzie, zazwyczaj wiążąca się z naprawą małego błędu, np. 0.9.2. Druga liczba jest zmieniana podczas wydania nowej wersji pakietu, która zawiera większe zmiany w kodzie, jak naprawy poważnych błędów, czy dodanie nowych możliwości, np. 0.10.0. Zmiana pierwszej liczby sugeruje poważne zmiany w kodzie, które ale też sugeruje pewną stabilizację działania, np. 1.0.0.

Authors@R: określa kolejne osoby zaangażowane w budowę tego pakietu. W powyższym przykładzie mamy wymienioną jedną osobę "Imie" "Nazwisko", której adres mailowy to "imie.nazwisko@example.com". Dodatkowo ta osoba posiada dwie role przy tworzeniu tego pakietu "cre" oraz "aut". Pierwsza rola, "cre", informuje że ta osoba jest twórcą i konserwatorem tego pakietu. Ona jest odpowiedzialna za pracę pakietu. Druga rola, "aut", jest nadawana osom, które wniosły bardzo duży wkład w kod zawarty w pakiecie. Inne często używane role to "ctb" określająca osoby, które wniosły mniejszy wkład w kod (np. drobne zmiany) oraz "cph" określająca osoby czy instytucje będące posiadaczami praw autorskich (np. firma zatrudniająca autora kodu albo autor biblioteki, która została wewnętrznie użyta).57 Dodanie kolejnych osób odbywa się poprzez łączenie ich funkcją c().

Authors@R: c(
    person("Imie", "Nazwisko", role = c("cre", "aut"), email = "email1@example.com"),
    person("Imie2", "Nazwisko2", role = "aut", email = "email2@example.com")
)

Licencja (License:) określa warunki korzystania z pakietu przez inne osoby. W bardzo dużym skrócie licencje oprogramowania można podzielić na licencje otwarte (open-source) oraz zamknięte (proprietary). Najpopularniejsze licencje otwarte używane w pakietach R to licencja CC0, MIT oraz GPL. Pierwsza z nich, CC0 oznacza przekazanie zawartości pakietu do domeny publicznej i najczęściej stosowana jest do pakietów zawierających tylko zbiory danych. Licencja MIT daje nieograniczone prawo do używania, modyfikowania i rozpowszechniania kodu, pod warunkiem zachowania informacji o autorze. Dodanie licencji MIT do pakietu R można wykonać podając swoje imię i nazwisko w funkcji usethis::use_mit_license("Imie Nazwisko"). W ten sposób informacja o tej licencji zostanie dodana do pliku DESCRIPTION (License: MIT + file LICENSE) oraz zostaną utworzone specjalne pliki z treścią licencji. Trzecia z licencji otwartych, GPL (ang. GNU General Public License) pozwala użytkownikom na uruchamianie, dostosowywanie, rozpowszechnianie i udoskonalanie kodu. Ważną cechą tej licencji jest wymaganie, że wszelkie prace oparte o kod w licencji GPL również muszą mieć licencję GPL Oprogramowanie zamknięte może również przyjmować wiele form (np. freeware czy też oprogramowanie komercyjne). Określenie pakietu jako oprogramowania zamkniętego odbywa się poprzez dodanie informacji, że licencja znajduje się w pliku LICENSE (License: file LICENSE), a następnie stworzenie pliku tekstowego o tej nazwie zawierającego odpowiednią modyfikację poniższego tekstu:

Proprietary 

Do not distribute outside of NAZWA MOJEJ FIRMY.

Plik DESCRIPTION należy regularnie uaktualniać, np. zmieniać numer wersji po naniesionych zmianach w kodzie, czy dodawać nowych autorów, jeżeli tacy się pojawili.

15.4 Rozwijanie pakietu

Rozwój pakietu R może opierać się na kilku poniższych krokach:

  1. Tworzenie/modyfikowanie kodu
  2. Używanie funkcji devtools::load_all(), która dodaje nowe/zmodyfikowane funkcje do R
  3. Sprawdzenie czy funkcja działa zgodnie z oczekiwaniami na kilku przykładach
  4. Dodanie testów jednostkowych (sekcja 15.10) na podstawie stworzonych przykładów
  5. Uaktualnienie dokumentacji tworzonego/modyfkowanego kodu
  6. Wygenerowanie plików z dokumentacją używając devtools::document()
  7. Sprawdzenie czy pakiet nie posiada żadnych problemów używając devtools::check()
  8. Modyfikacja wersji oprogramowania w pliku DESCRIPTION
  9. Powtórzenie powyższych czynności

15.5 Tworzenie i dokumentacja funkcji

W sekcji 3.8 stworzyliśmy nową funkcję konwersja_temp() przeliczającą temperaturę ze stopni Fahrenheita na stopnie Celsjusza.

konwersja_temp = function(temperatura_f){
    (temperatura_f - 32) / 1.8
}

Umieszczenie tej funkcji w nowym pakiecie R odbywa się poprzez zapisanie tego kodu jako skrypt R (np. konwersja_temp.R) w folderze R/.

Funkcje zawarte w pakietach muszą także posiadać odpowiednią dokumentację, zawierającą, między innymi, tytuł funkcji, opis jej działania, wyjaśnienie kolejnych argumentów funkcji, oraz przykłady jej działania. Linie obejmujące dokumentację funkcji rozpoczynają się od znaków #', a tworzenie dokumentacji funkcji odbywa się poprzez wypełnianie treści dla kolejnych znaczników (np. @example określa występowanie przykładu).

Przykładowy plik R/konwersja_temp.R może wyglądać następująco:

#' Konwersja temperatur
#'
#' @description Funkcja sluzaca do konwersji temperatury 
#'   ze stopni Fahrenheita do stopni Celsjusza.
#'
#' @param temperatura_f wektor zawierajacy wartosci temperatury 
#'   w stopniach Fahrenheita
#'
#' @return wektor numeryczny
#' @export
#'
#' @examples
#' konwersja_temp(75)
#' konwersja_temp(110)
#' konwersja_temp(0)
#' konwersja_temp(c(0, 75, 110))
konwersja_temp = function(temperatura_f){
  (temperatura_f - 32) / 1.8
}

Pierwsza linia w tym pliku określa tytuł danej funkcji. Kolejny element rozpoczynający się od znacznika @description zawiera krótki opis tego, co funkcja robi. Następnie zazwyczaj wypisane są wszystkie argumenty danej funkcji używając kolejnych znaczników @param. Znacznik @return pozwala na przekazanie informacji o tym co jest zwracane jako efekt działania funkcji. Przedostatnim znacznikiem w powyższym przypadku jest @export. Oznacza on, że ta funkcja będzie widoczna dla każdego użytkownika tego pakietu po użyciu library(mojpakiet). Bez tego znacznika funkcja byłaby tylko widoczna wewnątrz pakietu. Ostatni znacznik, @examples, wypisuje kolejne przykłady działania funkcji.

Wybór More -> Document w panelu “Build” (inaczej wywołanie funkcji devtools::document() lub użycie skrótu CTRL+SHIFT+D) spowoduje zbudowanie pliku dokumentacji w folderze man, np. man/konwersja_temp.Rd. Pliki dokumentacji będą zawsze tworzone w ten sposób - nie należy ich modyfikować ręcznie. Zbudowanie pliku dokumentacji pozwala teraz na jej podejrzenie poprzez wywołanie pliku pomocy naszej funkcji:

?konwersja_temp

15.6 Zależności

Istnieje jedna ważna różnica pomiędzy tworzeniem funkcji w skryptach a tworzeniem jej wewnątrz pakietu - w pakietach nie można używać dołączania pakietów za pomocą funkcji library(). Zamiast tego możliwe jest definiowanie każdej zewnętrznej funkcji używając operatora ::.58

Dodatkowo każda zależność z zewnętrznym pakietem musi być określona w pliku DESCRIPTION. Jest to możliwe używając wpisów Imports: oraz Suggests:, przykładowo:59

Imports:
  stringr,
  readr
Suggests:
  readxl

Imports: określa pakiety, które muszą być zainstalowane, aby tworzony pakiet mógł zadziałać. Jeżeli wymienione tutaj pakiety nie będą znajdować się na komputerze użytkownika to zostaną one automatycznie doinstalowane podczas instalacji naszego pakietu. Suggests: wymienia pakiety, które pomagają w użytkowaniu naszego pakietu, np. takie które zawierają testowe dane. Wymienione tutaj pakiety nie będą automatycznie doinstalowane podczas instalacji naszego pakietu.

15.7 Sprawdzanie pakietu

W momencie, gdy pakiet posiada już swoje podstawowe elementy, tj. pierwsze udokumentowane funkcje oraz uzupełniony opis wraz z zależnościami warto sprawdzić czy te wszystkie elementy pakietu dobrze współgrają ze sobą. Można to zrobić używając funkcji devtools::check() (inaczej wybór Check w panelu “Build” RStudio lub skrót CTRL+SHIFT+E). W efekcie tego wywołania zostanie uruchomiony szereg sprawdzeń i testów dotyczących pakietu, jego funkcji czy opisu. Na końcu zwrócone zostanie wypisanie liczby błędów (error), ostrzeżeń (warnings) i notatek (notes), poprzedzone wymienieniem każdego ich wystąpienia. Błędy oznaczają, że z jakiegoś powodu pakietu nie można zbudować, ostrzeżenia natomiast sugerują sytuację w której jakieś ważne elementy funkcji mogą wymagać poprawy. Notatki natomiast wskazują na kwestie, które użytkownik może, ale nie musi poprawić.

15.8 Instalowanie pakietu

Sprawdzony pakiet, który nie zwraca błędów można zainstalować na własnym komputerze używając funkcji devtools::install() (inaczej wybór Install and restart w panelu “Build” RStudio lub skrót CTRL+SHIFT+B). W przypadku, gdy kod źródłowy tego pakietu znajduje się na platformie GitHub, inni użytkownicy mogą go zainstalować za pomocą funkcji remotes::install_github("nazwa_uzytkownika_github/nazwa_pakietu") (Hester et al. 2020).

15.9 Dokumentacja pakietu

Po wykonaniu poprzednich kroków posiadamy działający pakiet, którego funkcje posiadają odpowiednią dokumentację. Teraz konieczne jest stworzenie dokumentacji pakietu - ma ona na celu poinformować potencjalnych użytkowników do czego pakiet służy, jak go zainstalować, czy też pokazać przykłady jego użycia. Pakiety mogą być dokumentowane używając kilku różnych rodzajów plików, np. za pomocą pliku README.Rmd, tzw. winiety (ang. vignette), czy pliku NEWS.md. Każdy z nich ma swój cel.

Plik README.Rmd można stworzyć za pomocą funkcji usethis::use_readme_rmd(). W efekcie będzie się on znajdować się w głównym folderze pakietu. Ten plik powinien zawierać:60

  1. Nazwę pakietu
  2. Opis do czego pakiet służy
  3. Instrukcje jak go zainstalować
  4. Prosty przykład użycia
  5. Odnośniki do podobnych prac, programów, czy artykułów naukowych

Winiety mają na celu pokazanie bardziej złożonego przykładu użycia pakietu. Nową winietę można stworzyć za pomocą funkcji usethis::use_vignette("nazwa-winiety"). W tym momencie zostanie stworzony nowy plik nazwa-winiety.Rmd w folderze vignettes. Teraz możliwe jest jego edytowanie i dodawanie nowej treści. Pakiety mogą posiadać wiele różnych winiet, zawierających coraz bardziej zaawansowane przykłady lub też opis różnych grup funkcji z pakietu.

Zarówno plik README.Rmd, jak i winieta wymaga użycia odpowiedniej składni - używany jest tam tzw. język znaczników RMarkdown. Języki znaczników opierają się o założenie, że pewne znaki w pliku tekstowym mają specjalne znaczenie, które po przetworzeniu pliku wyświetla je w odpowiedni sposób. Przykładowo jedna gwiazdka przed tekstem i jedna po tekście oznacza pochylony tekst (*pochylony tekst*), a dwie gwiazdki przed i po oznaczają pogrubiony tekst (**pogrubiony tekst**). Innym przykładem są nagłówki określane poprzez jeden lub więcej symboli kratki.

# Nagłówek

## Nagłówek drugiego poziomu (mniejsza czcionka)

Zestawienie pokazujące podstawy składni RMarkdown jest wbudowane w RStudio i można je wyświetlić za pomocą Help -> Markdown Quick Reference.

Pliki RMarkdown mogą być przetworzone (ang. render) do wielu różnych formatów plików, między innymi html, pdf, czy word w zależności od określonych opcji w nagłówku pliku. To przetworzenie może odbyć się używając ikony “Knit” w RStudio lub funkcji rmarkdown::render().

Elementem dokumentowania pakietu jest również informowanie o tym jakie nowe zmiany zaszły wraz z kolejnymi wersjami pakietu. W pakietach R może mieć to miejsce używając pliku NEWS.md tworzonego poprzez usethis::use_news_md(). Taki plik może zawierać informacje o nowych funkcjach, zmianach istniejących funkcji, naprawionych błędach, itd. Przykład szablonu pliku NEWS.md można znaleźć pod adresem https://ropensci.github.io/dev_guide/newstemplate.html.

15.10 Wbudowane testy

Sekcja 11.1 pokazywała w jaki sposób tworzyć testy jednostkowe dla funkcji, w celu sprawdzenia czy ich działanie jest zgodne z naszymi oczekiwaniami. Takie testy można również wbudować wewnątrz pakietu - w efekcie, gdy naniesiemy w nim jakieś zmiany możemy sprawdzić czy otrzymujemy takie same wyniki.

Pierwszym krokiem do używania wbudowanych testów jest ustawienie odpowiedniej infrastruktury używając funkcji use_testthat(). Powoduje ona dodanie pakietu testthat do wpisu Suggests:, stworzenie folderów tests/ i tests/testthat/ oraz pliku tests/testthat.R.

use_testthat()
#> ✔ Adding 'testthat' to Suggests field in DESCRIPTION
#> ✔ Creating 'tests/testthat/'
#> ✔ Writing 'tests/testthat.R'

Teraz możliwe jest napisanie testów jednostkowych. Zazwyczaj polega to na stworzeniu oddzielnego pliku dla każdej funkcji z naszego pakietu. Przykładowo, nasz pakiet zawiera funkcję powierzchnia(), dlatego też do jego testowania możemy stworzyć nowy plik tests/testthat/test-powierzchnia.R. Wewnątrz tego pliku należy sprawdzać kolejne aspekty działania kodu używając funkcji test_that(), gdzie należy podać (1) opis tego co jest sprawdzane i (2) testy wewnątrz nawiasów klamrowych (zobacz sekcję 11.1). Przykładowy plik tests/testthat/test-powierzchnia.R może wyglądać w ten sposób:

nowy_p = nowy_prostokat(0, 0, 6, 5)

test_that("struktura wyniku jest poprawna", {
  expect_length(powierzchnia(nowy_p), 1)
})

test_that("wartosc wyniku jest poprawna", {
  expect_equal(powierzchnia(nowy_p), 30)
})

test_that("wystepuja odpowiednie bledy", {
  expect_error(nowy_prostokat(3, 5, 2, "a"))
})

Po napisaniu testów można sprawdzić czy wszystkie z nich dają odpowiedni wynik używając devtools::test()61. W efekcie wyświetlone zostaną wszystkie testy i zostanie wskazane, które z nich się nie powiodły i należy je poprawić.

15.11 Publikowanie pakietów

Nowo utworzony pakiet w R można od razu umieścić na wybranym serwisie internetowym wspierającym kontrolę wersji takim jak GitHub, GitLab, czy BitBucket (rozdział 14), gdzie nazwa repozytorium będzie identyczna jak nazwa pakietu. Można to zrobić poprzez zainicjowanie repozytorium Git używając usethis::use_git(), a następnie wysłanie pakietu do repozytorium GitHub poprzez usethis::use_github()62. Dodatkowo, gdy napisaliśmy plik README.md użytkownicy mogą dowiedzieć się do czego ten pakiet służy, jak go zainstalować i użyć w podstawowy sposób. Teraz konieczna jest promocja tego pakietu w sytuacji, gdy chcemy zainteresować inne osoby jego użyciem. Taka promocja może odbywać się poprzez ogłoszenie stworzenia tego pakietu na Twitterze używając hasztagu #rstats, czy też napisaniu wpisu na blogu opisującego ten pakiet.

Dodatkowo w R istnieje możliwość prostego stworzenia stron internetowych dla wybranego pakietu używając pakietu pkgdown (Wickham and Hesselberth 2020). Przykład takiej strony można zobaczyć pod adresem https://pkgdown.r-lib.org/index.html. Stworzenie strony pakietu wymaga jedynie wywołania funkcji pkgdown::build_site() wewnątrz pakietu R. W efekcie zostanie utworzony folder docs/ zawierający stronę internetową reprezentującą pakiet i jego dokumentację. W przypadku, gdy pakiet znajduje się na GitHubie możliwe jest wyświetlenie tej strony pod adresem https://<nazwauzytkownika>.github.io/<nazwapakietu>/. Aby ta strona była dostępna w internecie należy na platformie GitHub wejść w zakładkę settings, następnie znaleźć część określoną jako GitHub Pages, i określić Source jako “master branch /docs folder”.

15.12 Zadania

  1. Stwórz szkielet nowego pakietu R nazywającego się konwerter.

  2. Napisz funkcję mil_do_km() służącą do odległości z mili lądowych na kilometry i zapisz ją jako R/mil_do_km.R.

  3. Uzupełnij dokumentację funkcji mil_do_km() zawierającą tytuł funkcji, opis funkcji, opis jej parametrów, format danych wyjściowych oraz kilka przykładów.

  4. Uzupełnij opis pakietu (plik DESCRIPTION) poprzez podanie jego nazwy, tytułu, wersji, autora, opisu i licencji. Zastanów się nad z każdą z tych opcji. Jak powinny one wyglądać, aby potencjalny użytkownik zrozumiał do czego służy ten pakiet?

  5. Sprawdź czy pakiet działa używając funkcji devtools::check(). Postaraj się naprawić wszystkie komunikaty błędów, ostrzeżeń i notatek jeżeli się pojawią. Zainstaluj pakiet konwerter.

  6. Stwórz nowe repozytorium w serwisie GitHub nazywające się konwerter. Połącz projekt RStudio zawierający pakiet konwerter z tym repozytorium w serwisie GitHub (14.4.2). Prześlij wszystkie pliki na zdalne repozytorium. Sprawdź czy widzisz wszystkie pliki w repozytorium GitHub.

  7. Stwórz nowy plik README.Rmd i dodaj do niego informacje o nazwie pakietu, jego zastosowaniu oraz w jaki sposób można go zainstalować. Dodaj również jeden przykład użycia tego pakietu. Przetwórz uzupełniony plik README.Rmd na README.md używając ikony “Knit” w RStudio lub funkcji rmarkdown::render(). Wyślij te dwa nowe pliki do zdalnego repozytorium. Czy widzisz jakąś zmianę w repozytorium GitHub?

  8. Dodaj infrastrukturę do testów jednostkowych używając funkcji use_testthat(), a następnie stwórz nowy plik tests/testthat/test-mil_do_km.R. Wewnątrz tego pliku dodaj kilka testów jednostkowych sprawdzających, czy wynik działania funkcji -mil_do_km() jest zgodny z oczekiwaniami. Sprawdź czy wszystkie z testów dają odpowiedni wynik używając devtools::test().

  9. Stwórz stronę internetową pakietu konwerter używając funkcji build_site() z pakietu pkgdown. Aktywuj tę stronę internetową wewnątrz zakładki setting na stronie repozytorium konwerter na GitHub. Sprawdź czy strona wyświetla się zgodnie z oczekiwaniami.

  10. Dodaj do tego pakietu drugą funkcję konwersja_temp(), która przyjmuje trzy argumenty - x, z, na. Pierwszy argument x to wektor numeryczny oznaczający temperaturę w dowolnej jednostce. Drugi argument z przyjmuje wartość tekstową określającą w jakiej jednostce jest obiekt x, może to być "Celsjusz", "Fahrenheit", lub "Kelvin". Trzeci argument z przyjmuje wartość tekstową określającą w jakiej jednostce ma być wynik działania tej funkcji, może to być "Celsjusz", "Fahrenheit", lub "Kelvin". Funkcja konwersja_temp() przyjmuje temperaturę (x) w podanej jednostce (z) i przelicza ją do innej wybranej skali (do).

  11. Sprawdź na kilku przykładach czy ta funkcja działa zgodnie z oczekiwaniami. Następnie dodaj dokumentację do funkcji konwersja_temp().

  12. Napisz kilka testów jednostkowych do funkcji konwersja_temp(). Sprawdź czy dają one poprawny wynik. Sprawdź cały pakiet używając devtools::check() i zainstaluj go poprzez devtools::install().

  13. Zaktualizuj opis pakietu (np. zmień wersję pakietu). Przebuduj stronę internetową pakietu i prześlij wszystkie zmiany na zdalne repozytorium.

  14. Stwórz nową winietę do pakietu konwerter nazywającą się wprowadzenie. Dodaj do niej krótki opis tego co robi ten pakiet, a następnie przedstaw przykład użycia funkcji mil_do_km() oraz funkcji konwersja_temp().

Bibliografia

Ganz, Carl, Gábor Csárdi, Jim Hester, Molly Lewis, and Rachael Tatman. 2019. Available: Check If the Title of a Package Is Available, Appropriate and Interesting. https://CRAN.R-project.org/package=available.

Hester, Jim, Gábor Csárdi, Hadley Wickham, Winston Chang, Martin Morgan, and Dan Tenenbaum. 2020. Remotes: R Package Installation from Remote Repositories, Including ’Github’. https://CRAN.R-project.org/package=remotes.

R Core Team. 2019. Writing R Extensions. R Foundation for Statistical Computing.

rOpenSci, Brooke Anderson, Scott Chamberlain, Anna Krystalli, Lincoln Mullen, Karthik Ram, Noam Ross, Maëlle Salmon, and Melina Vidoni. 2019. “rOpenSci Packages: Development, Maintenance, and Peer Review,” January. https://doi.org/10.5281/zenodo.2554759.

Wickham, Hadley. 2015. R Packages: Organize, Test, Document, and Share Your Code. " O’Reilly Media, Inc.".

Wickham, Hadley, and Jennifer Bryan. 2020. Usethis: Automate Package and Project Setup. https://CRAN.R-project.org/package=usethis.

Wickham, Hadley, and Jay Hesselberth. 2020. Pkgdown: Make Static Html Documentation for a Package. https://CRAN.R-project.org/package=pkgdown.

  1. Funkcja również create_packages() sama tworzy nowy folder, jeżeli on wcześniej nie istniał.↩︎

  2. Tytuły pakietów można znaleźć, np. w panelu “Packages” w RStudio.↩︎

  3. Pełną listę dostępnych ról można znaleźć pod adresem http://www.loc.gov/marc/relators/relaterm.html.↩︎

  4. Istnieją również inne możliwości, np. użycie znaczników @import lub @importFrom.↩︎

  5. Istnieją również inne wpisy, takie jak Depends:, LinkingTo:, czy Enhances:.↩︎

  6. Dodatkowe elementy to oznaki (ang. badges) pokazujące, np. status pakietu, liczbę jego pobrań i wiele innych.↩︎

  7. Testy są też automatycznie uruchamiane podczas sprawdzania pakietu (15.7)↩︎

  8. Wymaga to jednak wygenerowania tokena - opis jak to zrobić można znaleźć pod adresem https://debruine.github.io/tutorials/packages.html#github-access-token↩︎