Powtarzalne eksperymenty i raportowanie

• Powtarzalne eksperymenty
• knitr
  • Markdown
  • bloki kodu
  • lokalne ustawienia
  • globalne ustawienia
  • cache

• Twórcy algorytmów muszą włożyć dodatkowy wysiłek by oprócz artykułu opublikować kod
• Czytelnicy tych artykułów muszą z kolei samemu łączyć kod z opisem
• Dane, kod, opis nie są ze sobą powiązane
• Ciężko odtworzyć eksperymenty innych autorów
• Problemy te dotyczą prac naukowych jak i raportów w firmach

• Zdecydować, że analiza będzie powtarzalna
• Korzystać z repozytorium
• Wykorzystać oprogramowanie, gdzie można zaprogramować kolejne kroki
• Nie zapisywać wyników końcowych
• Korzystać z otwartych formatów danych

• Pomysł autorstwa Donalda Knutha
• Artykuł jako strumień tekstu i kodu
• Potrzebny język programowania i język do dokumentacji
• Kod podzielony na fragmenty
• Opis tłumaczący co się po kolei dzieje
• Z artykułu można wyciągnąć tylko kod albo zostawić tylko opis
• Przykłady: Sweave i knitr

• Paczka R stworzona przez Yihui Xie
• Wspiera Markdown, LaTeX i HTML jako języki do dokumentacji
• Efekty mogą być eksportowane do plików HTML, PDF lub Word
• Zintegrowane w RStudio

• Podręczników
• Krótkich lub średnio długich dokumentów technicznych
• Tutoriali
• Raportów
• Opisów transformacji i wstępnego przetwarzania danych

• Bardzo długich artykułów naukowych
• Skomplikowanych i długotrwałych obliczeń
• Dokumentów, które wymagają precyzyjnego składu/formatowania

Najłatwiej korzystać z knitra wykorzystując Markdown jako język do dokumentacji.

Markdown to prosty język (bez)znacznikowy:

• bardzo czytelny już w formie tekstowej,
• łatwo konwertowalny do htmla,
• wykorzystywany do tworzenia dokumentacji na Githubie, wspierany przez Wordpressa, LeanPub, czy Redmine

• Bloki kodu zaczynają się od ```{r} i kończy ```
• Domyślnie kod w bloku jest wyświetlany w dokumencie wynikowym
• Kod może być też wywoływany bez tworzenia bloku wewnątrz opisu za pomocą `r 2+2`
• Bloki kodu mogą mieć nazwy co okazuje się bardzo przydatne przy debugowaniu

```{r wczytywanieDanych}
# Kod R
```

• Kod i opis w dokumencie RMarkdown (.Rmd)
• knitr tworzy dokument Markdown (.md)
• knitr zamienia dokument Markdown na format docelowy (domyślnie html)
• .Rmd -> .md -> .html
• Można w ustawieniach wymusić pozostawienie pliku .md (przydatne do wyświetlania wyników na GitHubie)

Najlepiej wykorzystać funkcję i knitr::kable lub xtable::xtable. Wówczas blok może potrzebować atrybutu results='asis'.

df <- data.frame(a = rnorm(26), b = LETTERS)
knitr::kable(summary(df))

• Czasami chcemy zmienić wartości domyślne atrybutów każdego bloku kodu
• Na przykład możemy chcieć wyłączyć wyświetlanie kodu w pliku wynikowym
• W tym celu należy w jednym z pierwszych bloków kodu wpisać:

opts_chunk$set(atrybut=wartość,
               atrybut=wartość, ...)

• results: as-is, hide, markup
• echo: TRUE, FALSE
• eval: TRUE, FALSE
• engine: r, python, awk, ruby, perl, dot…
• error, warning, message: TRUE, FALSE
• tidy: TRUE, FALSE
• fig.height, fig.width: wysokość i szerokość wykresów w calach (domyślnie 7)

-> Pełna lista tutaj <-

• Domyślnie kod jest od nowa uruchamiany przy każdym wywołaniu knit
• Gdy obliczenia w bloku trwają długo, warto zapamiętać wynik obliczeń
• Atrybut cache=TRUE pozwala zachować wynik wykonania kodu w bloku
• Cache tworzy folder w wynikami, który można w razie potrzeby wyczyścić

• Jeśli zbiór danych się zmieni, to trzeba jeszcze raz wszystko przebudować
• knitr domyślnie nie sprawdza zależności między blokami
• Niektóre bloki kodu mogą być w praktyce “niecacheowalne”

Pływający spis treści

---
title: "Float, float, float your boat"
output:
  html_document:
    toc: true
    toc_float: true
---

Od najnowszych wersji RStudio oprócz raportów typu html można robić raporty typu notebook.

• domyślne cache'owanie
• odpalanie kodu blokami w RStudio
• eksport do HTML'a pozwala na dynamiczne pokazywania i ukrywanie kodu

Interaktywne tabele z biblioteką DT

library(DT)
prettyTable <- function(table_df, round_columns=numeric(), round_digits=2) {
    DT::datatable(table_df, style="bootstrap", filter = "top", rownames = FALSE, extensions = "Buttons", options = list(dom = 'Bfrtip', buttons = c('copy', 'csv', 'excel', 'pdf', 'print'))) %>%
    formatRound(round_columns, round_digits)
}

• Powtarzalne eksperymenty
• knitr
  • Markdown
  • bloki kodu
  • ustawienia lokalne
  • ustawienia globalne
  • cache

Pobierz zbiór danych tb, zawierający informacje o liczbie zachorowań na gruźlice w poszczególnych krajach w kolejnych latach.

devtools::install_github("rstudio/EDAWR")
library(EDAWR)
head(tb)

Przygotuj raport, który:

1. Wczytuje dane (ładuje odpowiednie biblioteki)
2. Cache'uje blok wczytujący dane
3. Prezentuje krótkie podsumowanie danych w zbiorze
4. Prezentuje liczbę zachorowań z podziałem na płeć
5. Prezentuje na wykresie liniowym sumaryczną liczbę zachorowań wśród dzieci, dorosłych i osób starszych w kolejnych latach
6. Prezentuje wykresy jak w punkcie 5, ale osobno dla każdego kraju