(Acest articol a fost publicat pentru prima dată pe Rsarcinași cu amabilitate a contribuit la R-bloggeri). (Puteți raporta problema legată de conținutul acestei pagini aici)
Doriți să vă distribuiți conținutul pe R-bloggeri? dați clic aici dacă aveți un blog, sau aici dacă nu aveți.
Puteți citi postarea originală în formatul său original pe site-ul web Rtask de ThinkR aici: Dincolo de funcții: Cum să îmbogățiți un pachet R cu date
În calitate de dezvoltatori de pachete, ne concentrăm adesea pe funcții personalizate, documentația acestora și testarea unitară. Pentru a oferi o experiență de utilizator mai completă, poate fi util să includeți date în pachet. Iată tot ce trebuie să știi!
Dacă nu sunteți familiarizat cu testarea unitară, vă recomandăm să citiți articolul nostru pe acest subiect: : https://rtask.thinkr.fr/expectations-verified-dive-into-the-world-of-unit-tests-with-expect_/
La scurt timp? Iată esenta
În acest articol, vă prezentăm diferitele modalități de a încorpora date într-un pachet R. Acoperim cele trei directoare utilizate pentru stocarea datelor și explicăm cum să le accesați, indiferent dacă sunteți un utilizator de pachet sau un dezvoltator. În cele din urmă, discutăm despre cele mai bune practici pentru documentarea acestor date.
De ce să includeți date într-un pachet?
Includerea datelor într-un pachet poate fi utilă din mai multe motive:
- Simplificarea utilizării pachetelor: Datele incluse în pachet sunt direct accesibile utilizatorilor.
- Facilitarea reproductibilității: Datele permit utilizatorilor să reproducă exemplele furnizate în documentație.
- Îmbunătățirea testării unitare: Datele incluse pot fi folosite pentru testarea funcțiilor pachetului.
- Partajarea informațiilor: Distribuirea de documentație, articole științifice, mostre de cod etc.
Aici, „date” ar trebui interpretate în sens larg. Include date tabelare utilizate de obicei în R (de exemplu, fișiere CSV sau XLSX sau data.frame obiecte), dar și imagini, fișiere de configurare, articole, mostre de cod etc.
Directoare de date într-un pachet R
Există trei directoare într-un pachet R utilizate pentru stocarea datelor: data-raw/, data/și inst/fiecare având un scop specific și găzduind publicuri diferite (dezvoltatori vs. utilizatori).
The data-raw/ şi data/ pereche
Scopul aici este de a pune la dispoziția utilizatorilor pachetului datele, care pot fi folosite de funcțiile pachetului sau incluse în exemplele de documentație. Aceste date vor fi reprezentate ca R obiecte (de exemplu, data.framelistă etc.).
The inst/ Director
Acest director vă permite să stocați fișiere fără restricții de format: fișiere tabulare, scripturi eșantion de cod, caiete în format Rmd/Qmd, documentație PDF etc. Nu există limite.
Folosind data-raw/ + data/
Caz de utilizare: Doriți să puneți la dispoziție utilizatorilor pachetului date care pot fi utilizate de funcțiile pachetului. Scopul este de a oferi acces nativ din funcțiile pachetului. Probabil că sunteți familiarizat cu seturile de date preîncărcate în R, cum ar fi mtcars sau iris; aceasta urmează același principiu.
data-raw/
The data-raw/ folderul este folosit pentru a stoca scripturi pentru pregătirea datelor. Fișierele din acest folder nu sunt incluse în pachetul final instalat pe computerul utilizatorului, dar conțin codul necesar pentru a genera seturile de date care vor fi ulterior incluse în pachet.
data/
Odată pregătit în data-raw/datele sunt stocate în data/ pliant. Fișierele din acest folder sunt incluse în pachetul final și sunt accesibile utilizatorilor. Fișierele sunt stocate în .rda format și sunt încărcate atunci când un utilizator rulează library(mypackage).
Exemplu
1 -Creează data-raw/ folder folosind comanda usethis::use_data_raw("my_dataset_demo"). Această comandă creează un my_dataset_demo.R dosar în data-raw/ pliant.
2- Pregătiți setul de date în my_dataset_demo.R fişier:
# Create a sample of the "starwars" dataset from the dplyr package
# See https://github.com/tidyverse/dplyr/tree/main/data-raw and https://github.com/tidyverse/dplyr/tree/main/data
library(dplyr)
library(readr)
starwars_raw <- read_csv("data-raw/starwars.csv")
starwars_sample <- starwars_raw |>
sample_n(size = 10)
usethis::use_data(starwars_sample, overwrite = TRUE)
3- După rularea comenzii usethis::use_data(starwars_sample, overwrite = TRUE)veți vedea un fișier numit starwars_sample.rda în data/ pliant.
4- Mai este ceva de făcut: acum trebuie să documentăm setul de date. Pentru aceasta, vom folosi {checkhelper} pachet.
Aceasta creează o doc_starwars_sample.R fișierul din pachet R/ pliant. Acest fișier conține documentația setului de date. Puteți edita acest fișier pentru a adăuga mai multe informații despre setul de date.
#' starwars_sample
#'
#' Description.
#'
#' @format A data frame with 10 rows and 14 variables:
#' describe{
#' item{ name }{ character name }
#' item{ height }{ numeric }
#' item{ mass }{ numeric }
#' item{ hair_color }{ character }
#' item{ skin_color }{ character }
#' item{ eye_color }{ character }
#' item{ birth_year }{ numeric }
#' item{ sex }{ character }
#' item{ gender }{ character }
#' item{ homeworld }{ character }
#' item{ species }{ character }
#' item{ films }{ character }
#' item{ vehicles }{ character }
#' item{ starships }{ character }
#' }
#' @source Source
"starwars_sample"
Deși structura generală a fișierului ar trebui păstrată, puteți edita descrierea, formatul și informațiile sursă după cum este necesar.
În cele din urmă, generați documentația LaTeX utilizând comanda devtools::document() sau attachment::att_amend_desc().
Odată ce pachetul dvs. este instalat cu (remotes::install_local()) și încărcat, puteți accesa setul de date folosind comanda data("starwars_sample").
Folosind inst/
Caz de utilizare: Doriți să stocați fișiere destinate utilizării numai în testele unitare sau să partajați documentație suplimentară (de exemplu, un articol științific).
Exemplu
1- Creați inst/ folder la rădăcina pachetului: dir.create(here::here("inst")).
2- Puneți fișierele dorite în folder.
3- Instalați pachetul: remotes::install_local().
4- Fișierele sunt acum accesibile folosind o funcție specială: system.file()care indică rădăcina lui inst/ director. De exemplu, pentru a accesa un fișier numit article.pdf în inst/ folder, ai folosi system.file("article.pdf", package = "mypackage"). Dacă fișierul se află într-un subdosar numit „doc”, ați folosi system.file("doc", "article.pdf", package = "mypackage").
Nota: system.file() nu citește un fișier; returnează doar calea fișierului.
Concluzie
Acum știți totul despre încorporarea datelor într-un pachet R. Ați învățat cum să stocați date în data-raw/, data/și inst/ directoare și faceți-l accesibil din funcțiile pachetului. De asemenea, ați învățat cum să documentați aceste date pentru a le face utilizabile pentru utilizatorii pachetelor.
Indiferent dacă datele sunt destinate utilizatorilor sau dezvoltatorilor, acum aveți toate instrumentele pentru a vă îmbogăți pachetul R cu date.
Pentru a merge mai departe
Pentru cei care doresc să meargă mai departe și să stăpânească arta creării de pachete robuste, inclusiv cele mai bune practici pentru testarea unitară, consultați formarea noastră
Această postare este mai bine prezentată pe site-ul său original ThinkR aici: Dincolo de funcții: Cum să îmbogățești un pachet R cu date
