Związek między R Markdown, Knitr, Pandoc i Bookdown

90

Jaki jest związek między funkcjonalnością R Markdown, Knitr, Pandoc i Bookdown?

W szczególności, jaki jest „podział pracy” między tymi pakietami przy konwertowaniu dokumentów znaczników z wbudowanym kodem R (np. .RnwLub .Rmd) na końcowe wyniki (np. .pdfLub .html)? A jeśli Knitr jest używany do przetwarzania RMarkdown, co robi rmarkdownpakiet i czym różni się od markdown package?

RobinL
źródło

Odpowiedzi:

134

Pandoc

Pandoc to konwerter dokumentów. Może konwertować z wielu różnych formatach znaczników do wielu innych formatów, takich jak .doc, .pdfetc.

Pandoc to narzędzie wiersza poleceń bez GUI. Jest to niezależne oprogramowanie, niezależne od R. Jednak jest dostarczane w pakiecie z R Studio, ponieważ rmarkdownpolega na nim do konwersji dokumentów.

Pandoc nie tylko konwertuje dokumenty, ale także dodaje funkcje do podstawowego języka markdown, aby umożliwić obsługę bardziej złożonych wyników.

R Markdown

R Markdown opiera się na przecenie:

Markdown (język znaczników)

Markdown to lekki język znaczników ze składnią formatowania zwykłego tekstu, zaprojektowaną tak, aby można go było konwertować na HTML i wiele innych formatów. Plik markdown to zwykły plik tekstowy, który zwykle ma rozszerzenie .md.

Podobnie jak inne języki znaczników, takie jak HTML i Latex, jest całkowicie niezależny od języka R.

Nie ma jasno określonego standardu Markdown. Doprowadziło to do fragmentacji, ponieważ różni dostawcy piszą własne warianty języka, aby poprawić błędy lub dodać brakujące funkcje.

Markdown (pakiet R)

markdownjest pakietem R, który konwertuje .Rmdpliki do formatu HTML. Jest poprzednikiem rmarkdown, który oferuje znacznie większą funkcjonalność. Nie jest już zalecane do użytku.

R Markdown (język znaczników)

R Markdown jest rozszerzeniem składni przecen. Pliki R Markdown to zwykłe pliki tekstowe, które zwykle mają rozszerzenie .Rmd. Są one napisane przy użyciu rozszerzenia składni markdown, które umożliwia osadzenie w nich kodu R w sposób, który można później wykonać.

Ponieważ oczekuje się, że zostaną przetworzone przez rmarkdownpakiet, możliwe jest użycie składni markdown Pandoc jako części pliku przeceny R. Jest to rozszerzenie oryginalnej składni przecen, która zapewnia dodatkowe funkcje, takie jak surowy HTML / Latex i tabele.

R Markdown (pakiet)

Pakiet R rmarkdownto biblioteka, która przetwarza i konwertuje .Rmdpliki do wielu różnych formatów.

Podstawową funkcją jest rmarkdown::renderktóry stoi na barkach pandoc . Ta funkcja 'renderuje plik wejściowy do określonego formatu wyjściowego za pomocą pandoc. Jeśli wejście wymaga dziania, knitr::knitjest wywoływane przed pandoc.

Celem pakietu RMarkdown jest po prostu zapewnienie rozsądnie dobrych ustawień domyślnych i przyjaznego dla języka R interfejsu do dostosowywania opcji Pandoc. .

Metadane YAML widoczne na górze plików RMarkdown służą w szczególności do przekazywania opcji rmarkdown::renderdo kierowania procesem kompilacji.

Zauważ, że RMarkdown zajmuje się tylko składnią przecen. Jeśli chcesz przekonwertować plik .Rhtmllub .Rnwplik, powinieneś użyć wbudowanych funkcji wygody Knitr, takich jak knitr::knit2htmliknitr:knit2pdf

Knitr

Knitr pobiera zwykły dokument tekstowy z osadzonym kodem, wykonuje kod i „łączy” wyniki z powrotem w dokumencie.

Na przykład konwertuje

Podstawową funkcją jest knitr::kniti domyślnie spojrzy na dokument wejściowy i spróbuje zgadnąć, jaki to jest typ - Rnw, Rmd itp.

Ta podstawowa funkcja pełni trzy role: - Analizator składni źródłowy, który sprawdza dokument wejściowy i wykrywa, które części są kodem, które użytkownik chce ocenić. - Ewaluator kodu, który ocenia ten kod - Moduł renderujący dane wyjściowe, który zapisuje wyniki oceny z powrotem do dokumentu w formacie, który jest interpretowalny przez surowy typ wyjściowy. Na przykład, jeśli plik wejściowy to plik .Rmd, renderowanie danych wyjściowych oznacza wynik oceny kodu w .mdformacie.

Konwersja między formatami dokumentów

Knitr nie konwertuje między formatami dokumentów - na przykład konwertuje plik .mddo .html. Zapewnia jednak pewne funkcje ułatwiające korzystanie z innych bibliotek w tym celu. Jeśli używasz rmarkdownpakietu, powinieneś zignorować tę funkcjonalność, ponieważ została zastąpiona przez rmarkdown::render.

Przykład knitr:knit2pdf: „Zszyje wejściowy dokument Rnw lub Rrst i skompiluje do formatu PDF przy użyciu texi2pdf lub rst2pdf”.

Potencjalnym źródłem nieporozumień jest to knitr::knit2html, że „jest wygodną funkcją związaną ze źródłem markdown::markdownToHTMLznaczników wejściowych i wywołaniem konwersji wyniku na HTML”. Jest to teraz starsza funkcjonalność, ponieważ markdownpakiet został zastąpiony przez rmarkdownpakiet. Zobacz tę notatkę .

Bookdown

Pakiet bookdown jest oparty na R Markdown i dziedziczy prostotę składni Markdown, a także możliwość wielu typów formatów wyjściowych (PDF / HTML / Word /…).

Oferuje funkcje, takie jak wielostronicowe wyjście HTML, numerowanie i odsyłacze do liczb / tabel / sekcji / równań, wstawianie części / dodatków i importowanie stylu GitBook ( https://www.gitbook.com ), aby stworzyć elegancki i atrakcyjny HTML strony książki.

RobinL
źródło
2
Wydało mi się to bardzo zagmatwane, więc zrobiłem co w mojej mocy. Edytuj lub dodaj inną odpowiedź, jeśli coś jest nie tak ...
RobinL
6
jednym z aspektów, który wydaje mi się mylący, jest dokumentacja parametrów przekazywanych do każdego kroku łańcucha narzędzi. Nie ma prawie żadnej pomocy interaktywnej (takiej jak autouzupełnianie) i trzeba zgadywać, jakie parametry powinny być wywoływane w nagłówkach yaml, lub przez knitr_opts(zawsze zapominam, jak to się nazywa), lub przez niestandardowe argumenty pandoc, lub przez dodatkowe pliki yam lub niestandardowy szablon pandoc ... Czasami wydaje się trochę dżungli, szczególnie po dodaniu LaTeX do łańcucha.
baptiste
3
@baptiste Całkowicie się zgadzam. I to jest dokładnie powód, dla którego wolę dokumenty RNW z gołym LaTeXem. Bez pandockroku pośredniego , mniej magii, mniej zamieszania. Po prostu stroma krzywa uczenia się LaTeX. Moim zdaniem Rmarkdown jest świetny, gdy jesteś zadowolony z prostych domyślnych rzeczy. Ale gdy tylko trzeba go poprawić, złożoność szybko rośnie.
CL.
3
To najlepsze wytłumaczenie tego wszystkiego, jakie znalazłem. Jest to bardzo zagmatwane dla początkujących, a nawet tych z wieloletnim doświadczeniem w R i lateksie oddzielnie, jak ja. Doskonały post.
StatsStudent
2
@StatsStudent Myślę, że poprzednia wersja ściągawki rstudio rmarkdown miała diagram, który był bardzo pomocny w zrozumieniu różnych etapów tworzenia wyjścia z rmarkdown. Może odpowiedź tutaj przydałaby się za pomocą diagramu?
Mark Neal