Pakiety R. Zarządzanie, testowanie, dokumentacja i udostępnianie kodu - ebook

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

Przedmowa

Część I. Rozpoczęcie pracy

• 1. 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 pakietu

• 6. 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 pakietu

• 9. 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. Testowanie

• 13. 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. Dokumentacja

• 16. 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 dystrybucja

• 20. 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