Jak zabalit kolegům data do balíčku v R

Je fajn mít veřejně přístupná data, která mohou všichni libovolně třídit, tříbit, tepat a vizualizovat. Někdy jsou data sice dostupná, ale nejsou veřejná nebo není jejich získání úplně snadné nebo přímočaré. Pokud pracujete v R, můžete svým kolegům data zabalit do balíčku a distribuovat třeba přes git.

V případě jednoduchých dat je to práce na pár minut během přestávky na kávu. Nuže, začněme!

Příprava

Je výhodné použít balíček devtools, který obsahuje hromadu užitečných funkcí pro tvorbu nových balíčků. Nainstalujeme jej ve spuštěném prostředí R (ať už máte GUI, RStudio nebo terminál) jednoduchým příkazem:

install.packages("devtools")

a během instalace se kromě jiného stáhne i balíček usethis, který nám ohromně usnadní život.

Vytvoříme nový balíček

Pro účely článku vytvořím balíček v0te, který bude obsahovat data z hlasování Organizace spojených národů mezi lety 1946–2019 ze stránek Harvard Dataverse.

Balíček vytvořím jednoduchým příkazem:

usethis::create_package("v0te")

Tímto se založí nový adresář v0te, který obsahuje základní strukturu balíčku pro prostředí R.

Popíšeme balíček

Dále můžeme editovat soubor DESCRIPTION, který obsahuje jakási základní metadata balíčku, tedy jméno, verzi, autora a případné závislosti na jiných balíčcích v R.

Můj soubor DESCRIPTION bude vypadat takto:

Package: v0te
Title: United Nations General Assembly Voting Data
Version: 0.1.0
Authors@R:
    person(given = "Petr",
           family = "Kajzar",
           role = c("aut", "cre"),
           email = "author@example.org")
Description: The package contains UN General Assembly Voting Data. It is a
    dataset of roll-call votes in the UN General Assembly from 1946.
License: MIT
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.1
Depends:
    R (>= 2.10)

Přidáme data

Přichází čas, kdy můžeme přidat data. Jak jsem psal výše, použiju data hlasování Organizace spojených národů z Harvard Dataverse. Vytvořím soubor s daty pomocí příkazu:

usethis::use_data_raw("v0te")

který zadám do konzole R. Ten mi založí adresář data-raw  a v něm soubor  v0te.R. Pokud používáte grafické rozhraní, rovnou se otevře editace tohoto souboru. Pokud ne, otevřete jej a můžeme vložit kód, kterým si připravíme data.

V mém případě bude soubor data-raw/v0te.R vypadat takto:

# nactu data ze stranek Harvard Dataverse
load(url("https://dataverse.harvard.edu/api/access/datafile/:persistentId?persistentId=doi:10.7910/DVN/LEJUQZ/MLNAHB"))

# vyberu jen promenne s ID hlasovani, rokem, zemi a hlasem
votes <- subset(completeVotes, select = c("resid", "year", "Countryname", "vote"))

# prejmenuji promenne, at jsou konzistentni
colnames(votes) <- c("resid", "year", "country", "vote")

# hlas zeme je ve forme cisla, prevedu jej na factor a urovne pojmenuji citelneji
votes$vote <- as.factor(votes$vote)
levels(votes$vote) <- c("yes", "abstain", "no", "absent", "not member")

# vytvorim soubor s ulozenymi data pro balicek
usethis::use_data(votes, overwrite = TRUE)

Klíčový je řádek na konci skriptu s funkcí usethis::use_data() , která zpracuje data ze skriptu a uloží je ve formě .rda souboru do adresáře data. Jakmile máte skript připravený, hned jej spusťte – buď výběrem kódu a stisknutím Ctrl+R (pokud pracujete v R GUI nebo tlačítkem „Run“ v RStudiu. Tím se data uloží. A samozřejmě uložte si doubor samotný, ať jej máte nachystaný na příště, až budete chtít data aktualizovat.

Zkontrolujte, že máte data automaticky uložená v adresáři data, a můžeme postoupit dále.

Dokumetace

Každý balíček si zaslouží aspoň stručnou dokumentaci. Pomůže nám s tím následující příkaz, který vložte do konzole R:

usethis::use_package_doc()

Tímto příkazem se založí adresář R se souborem v0te-package.R, který se vám v případě grafického rozhraní hned otevře k editaci. To, čím je předvyplněn, nechám beze změny, a doplním komentářový blok ve formátu roxygen2 následovaný nezakomentovaným názvem datasetu v uvozovkách, jak jsem si jej připravil dříve (tj. votes). Můj soubor R/v0te-package.R tedy vypadá takto:

#' @keywords internal
"_PACKAGE"

# The following block is used by usethis to automatically manage
# roxygen namespace tags. Modify with care!
## usethis namespace: start
## usethis namespace: end
NULL

#' United Nations General Assembly Voting Data
#'
#' This is a dataset of roll-call votes in the UN General Assembly from 1946.
#'
#' @format A data frame with 4 variables:
#' \describe{
#'   \item{resid}{roll-call vote id}
#'   \item{year}{year of vote}
#'   \item{country}{country name}
#'   \item{vote}{yes/no/abstain/absent/not a member}
#' }
#' @source \url{https://doi.org/10.7910/DVN/LEJUQZ}
"votes"

Soubor uložím a následně v konzoli spustím příkaz:

devtools::document()

Ten se postará o vygenerování nezbytné dokumentace k balíčku.

Konečné úpravy a kontrola

Nakonec můžu vložit nějakou svobodnou licenci, např. MIT pomocí příkazu:

usethis::use_mit_license("Jméno Příjmení")

Balíček nechám zkontrolovat, zdali obsahuje vše, co má, spuštěním:

devtools::check()

Pokud nám eRko nevyhodilo žádnou chybu ani upozornění, zkusíme si balíček načíst lokálně:

devtools::load_all()

A necháme si vypsat obsah datasetu votes:

str(votes)
#> tibble [1,216,585 x 4] (S3: tbl_df/tbl/data.frame)
#>  $ resid  : num [1:1216585] 1001 1001 1001 1001 1001 ...
#>  $ year   : num [1:1216585] 1946 1946 1946 1946 1946 ...
#>  $ country: chr [1:1216585] "United States of America" "Canada" "Bahamas" "Cuba" ...
#>  $ vote   : Factor w/ 5 levels "yes","abstain",..: 1 3 5 1 1 1 5 5 5 5 ...

To vypadá dobře, můžete dataset nahrát někam na git (GitHub, GitLab, Bitbucket, vlastní) a kolegové si jej v případě potřeby jen jednoduše natáhnou do svého prostředí R. Pokud si také nainstalují balíček devtools, jako my na začátku, tak si balíček načtou ve svém prostředí R např. takto:

# instalace balicku z gitu
remotes::install_git("git://gitlab.com/uzivatel/v0te.git")

# nacteni balicku
library(v0te)

# muzu pracovat s datasetem
str(votes)

A kolegové mají ohromnou radost, protože mají data k dispozici jako balíček a nemusí si je stahovat a předchroustávat sami. Mohou se vrhnout na ono třídění, tříbení a další radosti datových vědců a analytiků.