E-book details

Pakiety R. Zarządzanie, testowanie, dokumentacja i udostępnianie kodu. Wydanie II

Pakiety R. Zarządzanie, testowanie, dokumentacja i udostępnianie kodu. Wydanie II

Hadley Wickham, Jennifer Bryan

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
  • Title: Pakiety R. Zarządzanie, testowanie, dokumentacja i udostępnianie kodu. Wydanie II
  • Author: Hadley Wickham, Jennifer Bryan
  • Original title: R Packages: Organize, Test, Document, and Share Your Code, 2nd Edition
  • Translation: Robert Górczyński
  • ISBN: 978-83-289-1047-8, 9788328910478
  • Date of issue: 2024-05-21
  • Format: Ebook
  • Item ID: pakir2
  • Publisher: Helion