Pakiety R. Zarządzanie, testowanie, dokumentacja i udostępnianie kodu Międzyrzec Podlaski

W języku R podstawową jednostką współdzielonego kodu jest pakiet. Ma on ściśle określoną strukturę i można go łatwo udostępniać innym. Obecnie programiści R mogą korzystać z ponad 19 tysięcy przeróżnych pakietów. Poza prostym pobieraniem i używaniem pakietów opracowanych przez kogoś innego programistom R przydaje się umiejętność ich samodzielnego tworzenia. Oto doskonały podręcznik tworzenia pakietów dla początkujących i zaawansowanych użytkowników! Maoelle Salmon Oto znakomity przewodnik po budowaniu pakietów R. Pokazuje, jak dokładnie wygląda proces tworzenia pakietu i z czego wynika jego struktura. Omawia poszczególne komponenty i metadane pakietu R, wyjaśnia także, na czym polega korzystanie z zależności i jakie są zasady eksportowania funkcji z pakietu. Wyczerpujące wyjaśnienie zagadnień testowania kodu za pomocą pakietu testthat uwzględnia również techniki przydatne w trudniejszych przypadkach. Książka zawiera ponadto omówienie systemu dokumentowania zawartości pakietu, a w końcowych rozdziałach przedstawia praktyki stosowane podczas jego tworzenia, takie jak korzystanie z kontroli wersji i przekazywanie go do repozytorium CRAN. W książce: z czego się składa pakiet R praca z pakietem devtools w środowisku RStudio tworzenie testów jednostkowych za pomocą pakietu testthat przygotowywanie estetycznej i funkcjonalnej dokumentacji przy użyciu pakietu pkgdown korzystanie z nowoczesnych platform hostingowych dla kodu źródłowego dobre praktyki podczas pracy z pakietami R Ułatwisz wielokrotne korzystanie z kodu R ... sobie lub innym użytkownikom. Sam Lau, autor książki Learning Data Science Spis treści: Przedmowa Część I. Rozpoczęcie pracy1. Cała gra Wczytywanie pakietu devtools i związanych z nim narzędzi Przykładowy pakiet: regexcite Podgląd gotowego produktu create_package() use_git() Tworzenie pierwszej funkcji use_r() load_all() Przekazanie funkcji strsplit1() do repozytorium check() Edycja pliku DESCRIPTION use_mit_license() document() Zmiany w pliku NAMESPACE Ponowne wywołanie check() install() use_testthat() use_package() use_github() use_readme_rmd() Koniec pracy: check() i install() Podsumowanie 2. Konfiguracja systemu devtools, usethis i Ty Osobista konfiguracja podstawowa Zestaw narzędzi do tworzenia pakietów R Windows macOS Linux Weryfikacja poprawności systemu 3. Stan i struktura pakietu Stany pakietu Kod źródłowy pakietu Pakiet umieszczony w paczce .Rbuildignore Pakiet binarny Pakiet zainstalowany Pakiet w pamięci Biblioteki pakietu 4. Podstawy sposobu pracy Tworzenie pakietu Analiza istniejącego środowiska Nadanie nazwy pakietowi Tworzenie pakietu Dlaczego należy korzystać z wywołania create_package()? Projekty RStudio Zalety używania projektów RStudio Tworzenie Projektu RStudio Co tworzy Projekt RStudio? Uruchamianie Projektu RStudio Projekt RStudio kontra aktywny projekt usethis Bieżący katalog roboczy i dyscyplina związana ze ścieżkami dostępu Funkcja load_all() Zalety funkcji load_all() Inne sposoby wywołania load_all() check() i R CMD check Sposób pracy Pod maską polecenia R CMD check 5. Zawartość pakietu Alfa - działający skrypt Bravo - lepsza wersja działającego skryptu Charlie - oddzielny plik z funkcjami pomocniczymi Delta - nieudana próba utworzenia pakietu Echo - działający pakiet Foxtrot - kompilacja kontra uruchomienie Golf - efekty uboczne Rozważania końcowe Skrypt kontra pakiet Wyszukiwanie w pakiecie Pakiet kodu jest inny Część II. Komponenty pakietu6. Kod w języku R Umieszczanie funkcji w plikach Szybsze informacje zwrotne dzięki użyciu wywołania load_all() Styl tworzenia kodu Kiedy kod jest wykonywany? Przykład: ścieżka dostępu zwrócona przez system.file() Przykład: dostępne kolory Przykład: alias dla funkcji Szanowanie środowiska R Zarządzanie stanem za pomocą pakietu withr Przywracanie stanu za pomocą wywołania base::on.exit() Odizolowanie efektów ubocznych Gdy potrzebujesz efektów ubocznych Nieustanne sprawdzanie poprawności 7. Dane Dane wyeksportowane Zachowanie pierwotnej historii danych pakietu Dokumentowanie zbiorów danych Znaki inne niż ASCII w danych Dane wewnętrzne Plik danych niezmodyfikowanych Ścieżki dostępu plików Funkcje pomocnicze pkg_example() Stan wewnętrzny Trwałe dane użytkownika ROZDZIAŁ 8 8. Inne komponenty Inne katalogi Zainstalowane pliki Plik CITATION w pakiecie Narzędzia konfiguracji CZĘŚĆ III Część III. Metadane pakietu9. Plik DESCRIPTION Plik DESCRIPTION Pola Title i Description - na czym polega działanie pakietu? Pole Authors - kim jesteś? Adres URL i zgłaszanie błędów Pole License Pola Imports, Suggests i Friends Wersja minimalna Pola Depends i LinkingTo Problem z wersją R Inne pola Pola niestandardowe 10. Zależności - nastawienie i kontekst Kiedy należy skorzystać z zależności? Zależności nie są takie same Postaw na podejście holistyczne, zrównoważone i ilościowe Przemyślenia dotyczące zależności ściśle związanych z tidyverse Imports czy Suggests? Przestrzeń nazw Uzasadnienie Plik NAMESPACE Ścieżka wyszukiwania Wyszukiwanie funkcji dla kodu użytkownika Wyszukiwanie funkcji w pakiecie Dołączanie kontra wczytywanie Imports czy Depends? 11. Zależności - praktyka Niejasności związane z importowaniem Konwencje zastosowane w tym rozdziale Sposób pracy z plikiem NAMESPACE Pakiet został wymieniony w polu Imports Kod w katalogu R W kodzie testu W przykładach i w ulotkach Pakiet jest wymieniony w polu Suggests W kodzie zdefiniowanym w plikach katalogu R W kodzie testowym W przykładach i w ulotkach Pakiet został wymieniony w polu Depends W kodzie zdefiniowanym w plikach katalogu R oraz w kodzie testowym W przykładach i w ulotkach Pakiet jest zależnością niestandardową Zależność od programistycznej wersji pakietu Pole Config/Needs/* Eksportowanie Co należy wyeksportować? Ponowne eksportowanie Operacje importowania i eksportowania powiązane z systemem S3 12. Licencje Szersza perspektywa Kod, który tworzysz Pliki kluczy Więcej licencji dla kodu Licencje dla danych Ponowne licencjonowanie Kod przekazany Tobie Kod dołączony do pakietu Zgodność licencji Jak dołączyć kod? Kod używany przez Ciebie Część IV. Testowanie13. Podstawy testowania Dlaczego warto podjąć wysiłek związany z testowaniem? Wprowadzenie do pakietu testthat Struktura testów i praca z nimi Konfiguracja początkowa Tworzenie testu Uruchamianie testów Organizacja testu Oczekiwania Sprawdzanie równości Sprawdzanie pod kątem błędów Testy migawek Skróty dla innych często spotykanych wzorców 14. Projektowanie zbioru testów Co należy testować? Pokrycie testami Ogólne reguły dotyczące testowania Testy samowystarczalne Testy odizolowane Planowanie niepowodzenia testu Powtarzanie jest w porządku Eliminowanie tarć między testowaniem interaktywnym i zautomatyzowanym Pliki związane z testowaniem Zniknąć z pola widzenia - pliki w katalogu R tests/testthat.R Pliki pomocnicze testthat Pliki konfiguracyjne testthat Pliki ignorowane przez testthat Przechowywanie danych testowych Gdzie będą zapisywane pliki podczas testów? 15. Zaawansowane techniki testowania Przygotowywanie warunków początkowych testów Tworzenie useful_thing za pomocą funkcji pomocniczej Tworzenie (i usuwanie) lokalnego elementu useful_thing Trwałe przechowywanie konkretnego elementu useful_thing Budowanie własnych narzędzi testowania Funkcja pomocnicza zdefiniowana w teście Oczekiwania niestandardowe Kiedy testowanie staje się trudne? Pomijanie testu Imitacje Klucze tajne użytkownika Uwagi specjalne dotyczące pakietów repozytorium CRAN Pomijanie testu Szybkość działania Odtwarzalność Testy niepewne Higiena związana z procesem i systemem plików Część V. Dokumentacja16. Dokumentacja funkcji Podstawy pracy z roxygen2 Sposób pracy z dokumentacją Komentarze, bloki i tagi roxygen2 Najważniejsze funkcjonalności składni Markdown Tytuł, opis, szczegóły Tytuł Opis Szczegóły Argumenty Wiele argumentów Dziedziczenie argumentów Wartość zwrotna Przykłady Treść Pozostawienie środowiska w jego początkowej postaci Błędy Zależności i wykonywanie warunkowe Łączenie przykładów i tekstu Wielokrotne wykorzystywanie dokumentacji Wiele funkcji w jednym temacie Dokumentacja dziedziczona Dokumenty potomne Temat pomocy dla pakietu 17. Ulotki Sposób pracy podczas tworzenia ulotki Metadane Rada dotycząca tworzenia ulotek Diagramy Łącza Ścieżki dostępu plików Ile ulotek? Publikacje naukowe Uwagi szczególne dotyczące kodu ulotki Artykuł zamiast ulotki Jak są tworzone i sprawdzane ulotki? Polecenie R CMD build i ulotki Polecenie R CMD check i ulotki 18. Inne pliki Markdown Plik README Pliki README.Rmd i README.md Plik NEWS 19. Witryna internetowa Tworzenie witryny internetowej Wdrożenie Co dalej? Logo Indeks Wygenerowane przykłady Łącza Ułożenie indeksu Ulotki i artykuły Łącza Ułożenie indeksu Artykuły niebędące ulotkami Tryb programistyczny Część VI. Obsługa techniczna i dystrybucja20. Praktyki dotyczące tworzenia oprogramowania Git i GitHub Praktyka standardowa Ciągła integracja Akcje GitHuba Wykonywanie polecenia R CMD check za pomocą akcji GitHuba Inne zastosowania dla akcji GitHuba 21. Cykl życiowy Ewolucja pakietu Numer wersji pakietu Konwencje numerów wersji pakietów tidyverse Zachowanie wstecznej zgodności i przełomowe zmiany Wersja główna, wersja mniejsza i wersja poprawki Mechanizm wersji pakietu Wady i zalety zmiany określanej jako przełomowa Etapy cyklu życiowego i narzędzia wspomagające Etapy cyklu życiowego i plakietki Uznanie funkcji za przestarzałą Uznanie argumentu za przestarzały Komponent pomocniczy podczas uznawania za przestarzałe Zmiana w zależności Zastępowanie funkcji 22. Przekazanie pakietu do repozytorium CRAN Określenie typu wydania Początkowe wydanie poprzez repozytorium CRAN - kwestie specjalne Polityki stosowane w repozytorium CRAN Monitorowanie pod kątem zmian Dokładne sprawdzenie wyniku wykonania polecenia R CMD check Operacje sprawdzenia w repozytorium CRAN i powiązane z nimi usługi Sprawdzanie zależności odwrotnych Zależności odwrotne i przełomowe zmiany Uaktualnienie komentarzy dla repozytorium CRAN Proces przekazania pakietu do repozytorium CRAN Tryby niepowodzenia Świętowanie sukcesu