Hubungan antara R Markdown, Knitr, Pandoc, dan Bookdown

90

Apa hubungan antara fungsionalitas R Markdown, Knitr, Pandoc, dan Bookdown?

Secara khusus apa yang dimaksud dengan 'pembagian kerja' antara paket-paket ini dalam mengonversi dokumen markup dengan kode R yang disematkan (misalnya .Rnwatau .Rmd) menjadi keluaran akhir (misalnya .pdfatau .html)? Dan jika Knitr digunakan untuk memproses RMarkdown, apa yang dilakukan rmarkdownpaket dan apa bedanya dengan markdown package?

RobinL
sumber

Jawaban:

135

Pandoc

Pandoc adalah pengubah dokumen. Itu dapat mengonversi dari sejumlah format markup yang berbeda ke banyak format lain, seperti .doc, .pdfdll.

Pandoc adalah alat baris perintah tanpa GUI. Ini adalah perangkat lunak independen, terpisah dari R. Namun, ini dibundel dengan R Studio karena rmarkdownbergantung padanya untuk konversi dokumen.

Pandoc tidak hanya mengonversi dokumen, tetapi juga menambahkan fungsionalitas di atas bahasa penurunan harga dasar untuk memungkinkannya mendukung keluaran yang lebih kompleks.

R penurunan harga

R Markdown didasarkan pada penurunan harga:

Markdown (bahasa markup)

Markdown adalah bahasa markup ringan dengan sintaks pemformatan teks biasa yang dirancang agar dapat dikonversi ke HTML dan banyak format lainnya. File penurunan harga adalah file teks biasa yang biasanya diberi ekstensi .md.

Seperti bahasa markup lainnya seperti HTML dan Latex, ini sepenuhnya independen dari R.

Tidak ada standar penurunan harga yang didefinisikan dengan jelas. Hal ini menyebabkan fragmentasi karena vendor yang berbeda menulis varian bahasa mereka sendiri untuk memperbaiki kekurangan atau menambahkan fitur yang hilang.

Penurunan harga (paket R)

markdownadalah paket R yang mengubah .Rmdfile menjadi HTML. Ini adalah pendahulu rmarkdown, yang menawarkan lebih banyak fungsionalitas. Ini tidak lagi direkomendasikan untuk digunakan.

R Markdown (bahasa markup)

R Markdown adalah perpanjangan dari sintaks penurunan harga. File penurunan harga adalah file teks biasa yang biasanya memiliki ekstensi file .Rmd. Mereka ditulis menggunakan ekstensi sintaks penurunan harga yang memungkinkan kode R untuk disematkan di dalamnya dengan cara yang nantinya dapat dieksekusi.

Karena mereka diharapkan untuk diproses oleh rmarkdownpaket, dimungkinkan untuk menggunakan sintaks penurunan harga Pandoc sebagai bagian dari file penurunan harga R. Ini adalah ekstensi dari sintaks penurunan harga asli yang menyediakan fungsionalitas tambahan seperti HTML / Lateks mentah dan tabel.

R Markdown (paket)

Paket R rmarkdownadalah pustaka yang memproses dan mengonversi .Rmdfile ke dalam beberapa format berbeda.

Fungsi intinya adalah rmarkdown::renderyang berdiri di atas bahu pandoc . Fungsi ini membuat file masukan ke format keluaran yang ditentukan menggunakan pandoc. Jika input membutuhkan rajutan maka knitr::knitdipanggil sebelum pandoc.

Tujuan paket RMarkdown hanyalah untuk memberikan default yang cukup baik dan antarmuka R-friendly untuk menyesuaikan opsi Pandoc. .

Metadata YAML yang terlihat di bagian atas file RMarkdown secara khusus untuk meneruskan opsi rmarkdown::render, untuk memandu proses build.

Perhatikan bahwa RMarkdown hanya berurusan dengan sintaks penurunan harga. Jika Anda ingin mengonversi file .Rhtmlatau .Rnw, Anda harus menggunakan fungsi praktis yang ada di dalamnya Knitr, seperti knitr::knit2htmldanknitr:knit2pdf

Knitr

Knitr mengambil dokumen teks biasa dengan kode yang disematkan, mengeksekusi kode dan 'merajut' hasilnya kembali ke dalam dokumen.

Misalnya, itu mengubah

Fungsi inti adalah knitr::knitdan secara default ini akan melihat dokumen masukan dan mencoba menebak jenisnya - Rnw, Rmd dll.

Fungsi inti ini melakukan tiga peran: - Parser sumber, yang melihat dokumen masukan dan mendeteksi bagian mana yang merupakan kode yang ingin dievaluasi oleh pengguna. - Penilai kode, yang mengevaluasi kode ini - Penyaji keluaran, yang menulis hasil evaluasi kembali ke dokumen dalam format yang dapat diinterpretasikan oleh jenis keluaran mentah. Misalnya, jika file input adalah .Rmd, render output menandai output evaluasi kode dalam .mdformat.

Mengonversi antar format dokumen

Knitr tidak mengkonversi antara format dokumen - seperti mengubah a .mdmenjadi .html. Namun, ia menyediakan beberapa fungsi kemudahan untuk membantu Anda menggunakan pustaka lain untuk melakukan ini. Jika Anda menggunakan rmarkdownpaket tersebut, Anda harus mengabaikan fungsionalitas ini karena telah digantikan oleh rmarkdown::render.

Contohnya adalah knitr:knit2pdfyang akan: 'Merajut dokumen input Rnw atau Rrst, dan mengkompilasi ke PDF menggunakan texi2pdf atau rst2pdf'.

Sumber kebingungan potensial adalah knitr::knit2html, yang "merupakan fungsi praktis untuk merajut sumber penurunan harga input dan memanggil markdown::markdownToHTMLuntuk mengonversi hasilnya ke HTML." Ini sekarang fungsionalitas lama karena markdownpaket telah digantikan oleh rmarkdownpaket. Lihat catatan ini .

Bookdown

Paket bookdown dibangun di atas R Markdown, dan mewarisi kesederhanaan sintaks Markdown, serta kemungkinan beberapa jenis format output (PDF / HTML / Word /…).

Ini menawarkan fitur-fitur seperti output HTML multi-halaman, penomoran dan referensi silang angka / tabel / bagian / persamaan, memasukkan bagian / lampiran, dan mengimpor gaya GitBook ( https://www.gitbook.com ) untuk membuat HTML yang elegan dan menarik halaman buku.

RobinL
sumber
2
Saya menemukan ini sangat membingungkan jadi saya telah melakukan yang terbaik di sini. Harap edit atau tambahkan jawaban yang berbeda jika ada yang salah ...
RobinL
6
satu aspek yang menurut saya membingungkan adalah dokumentasi parameter yang diteruskan ke setiap langkah dari toolchain. Hampir tidak ada bantuan interaktif (seperti pelengkapan otomatis) dan orang harus menebak parameter apa yang harus dipanggil di header yaml, atau melalui knitr_opts(saya selalu lupa apa namanya), atau melalui argumen pandoc khusus, atau melalui file ubi tambahan, atau kustom template pandoc ... Terkadang terasa agak sulit, terutama saat Anda menambahkan LaTeX ke rantai.
baptiste
3
@baptiste Saya setuju sepenuhnya. Dan inilah alasan mengapa saya lebih suka dokumen RNW dengan LaTeX telanjang. Tidak ada pandoclangkah menengah , lebih sedikit sihir, lebih sedikit kebingungan. Kurva pembelajaran LaTeX yang sangat curam. Menurut pendapat saya, Rmarkdown sangat bagus bila Anda puas dengan barang bawaan yang sederhana. Tetapi begitu Anda harus menyesuaikannya, kerumitan meningkat dengan cepat.
CL.
3
Ini adalah penjelasan terbaik yang saya temukan untuk semua ini. Ini sangat membingungkan bagi pemula atau bahkan mereka yang memiliki pengalaman bertahun-tahun di R dan lateks secara terpisah seperti saya. Posting yang bagus.
StatsStudent
2
@StatsStudent Saya rasa versi cheat sheet rstudio sebelumnya memiliki diagram yang cukup membantu untuk memahami berbagai langkah dalam membuat output dari rmarkdown. Mungkin jawaban di sini bisa dilakukan dengan diagram?
Mark Neal