Quarto dan R Markdown

Topik ini membahas dokumen analisis literat (literate programming) berformat .qmd yang menggabungkan narasi, kode R, dan hasilnya dalam satu berkas. Pembahasan mencakup struktur dokumen Quarto, cara merendernya menjadi laporan HTML melalui perintah quarto render, dan hubungannya dengan R Markdown. Setelah membacanya, satu berkas analisis dapat ditulis sekaligus dipertahankan sebagai dokumen yang siap dibagikan.

Analisis literat: narasi, kode, dan hasil#

Analisis yang ditulis sebagai skrip biasa menyisakan dua artefak terpisah, yaitu berkas kode dan hasil eksekusinya yang tersebar di konsol. Gaya analisis literat menyatukan keduanya: narasi penjelasan dan potongan kode (chunk) disusun bergantian dalam satu dokumen, dan pada saat dokumen dirender, setiap kode dijalankan ulang lalu hasilnya disisipkan tepat di posisinya. Dokumen yang dihasilkan berisi angka, tabel, dan grafik yang benar-benar berasal dari kode di dalamnya, bukan dari penyalinan manual. Gaya ini berbeda dari alur salin-tempel, yaitu menjalankan kode lalu menyalin hasilnya ke dokumen pengolah kata, yang mudah memisahkan angka dari kode sumbernya ketika data berubah.

Sifat ini membawa jaminan reprodusibilitas. Merender ulang dokumen menjalankan seluruh kode dari awal pada berkas sumber yang sama, sehingga laporan terbaru selalu konsisten dengan datanya. Apabila data berubah, cukup render ulang, dan seluruh angka pada narasi hasil perhitungan ikut diperbarui tanpa disunting satu per satu.

Pembaca laporan tidak membutuhkan R sama sekali, karena berkas HTML yang dirender sudah memuat segalanya dalam bentuk jadi. Sebaliknya, siapa pun yang memiliki berkas sumber .qmd beserta datanya dapat membangkitkan kembali laporan yang identik. Dua sifat itulah yang membuat format ini cocok untuk laporan berkala maupun lampiran publikasi.

Struktur dokumen .qmd#

Dokumen Quarto terdiri atas tiga bagian, yaitu kepala YAML (YAML header) yang memuat metadata, bagian prosa biasa, dan chunk kode berpagar ```{r}. Berkas berikut adalah dokumen contoh yang utuh dan siap dirender:

---
title: "Rekap Nilai Ujian"
format: html
---

Rata-rata nilai ujian lima siswa dihitung dari vektor berikut.

```{r}
nilai <- c(85, 90, 78, 92, 88)
mean(nilai)
```

Kepala YAML diapit tiga tanda pisah dan menetapkan title serta format keluarannya, dalam hal ini html. Bagian prosa ditulis sebagai Markdown biasa dan menjelaskan konteks analisisnya. Chunk ```{r} memuat kode R yang dieksekusi saat dokumen dirender, dan keluaran eksekusinya menjadi bagian dari dokumen akhir. Opsi perilaku chunk seperti #| echo: false untuk menyembunyikan kode atau #| eval: false untuk melewati eksekusinya dituliskan pada baris khusus di awal chunk.

Pemisahan tiga bagian tersebut membuat dokumen sumber mudah dirawat. Narasi dapat disunting tanpa menyentuh kode, sedangkan kode dapat diubah tanpa mencari tempat hasilnya harus diganti. Kepala YAML juga bisa dilengkapi sesuai kebutuhan, misalnya menambahkan nama penulis atau mengganti format keluaran yang didukung Quarto.

Ekstensi .qmd adalah singkatan dari Quarto Markdown, yaitu Markdown biasa yang diperluas dengan kepala YAML dan chunk komputasi. Berkasnya berformat teks biasa, sehingga dapat dibuka dengan editor apa pun dan dibandingkan baris demi baris oleh sistem kendali versi. Satu dokumen .qmd yang dirawat baik memiliki umur panjang, karena narasinya tetap terbaca sekalipun hasil komputasinya dibangkitkan ulang bertahun-tahun kemudian.

Merender dokumen#

Dokumen dirender dengan perintah quarto render yang dijalankan dari direktori tempat berkasnya berada. Render menjalankan seluruh chunk melalui knitr, lalu meneruskan hasilnya ke pandoc untuk dibentuk menjadi dokumen akhir:

# merender dokumen ke HTML dengan quarto
quarto render laporan.qmd --to html

processing file: laporan.qmd
1/3
2/3 [unnamed-chunk-1]
3/3
output file: laporan.knit.md

pandoc
  to: html
  output-file: laporan.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png
  variables: {}

metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: Rekap Nilai Ujian

Output created: laporan.html

Keluarannya memperlihatkan tiga tahap: knitr memproses berkas dan mengeksekusi chunk unnamed-chunk-1, hasil antaranya ditulis ke laporan.knit.md, lalu pandoc mengubahnya menjadi laporan.html. Berkas HTML tersebut memuat narasi, kode, dan hasil mean(nilai) yang berupa 86.6 dalam posisi yang berurutan. Merender ulang dokumen yang sama menghasilkan laporan yang sama, dan itulah bentuk paling sederhana dari laporan yang dapat direproduksi.

Urutan tiga tahap pada keluaran sekaligus menjelaskan pembagian kerjanya. knitr mengeksekusi chunk dan menulis hasil antara ke berkas Markdown, kemudian pandoc membentuk berkas antara itu menjadi HTML lengkap dengan penyorotan sintaksnya. Apabila salah satu chunk melaporkan error, render berhenti pada chunk tersebut dan berkas HTML tidak terbentuk, sehingga laporan yang berhasil dirender menjamin seluruh kodenya tereksekusi tanpa kesalahan.

Render dilakukan dari terminal, sehingga berkas HTML yang dihasilkan dapat dibagikan tanpa mengirim skrip R apa pun. Setiap kali datanya berubah, satu perintah render membangun ulang seluruh laporan, termasuk angka, tabel, dan grafiknya.

Karena setiap render membangun ulang berkas keluarannya dari awal, berkas sumber dan berkas HTML tidak boleh disunting terpisah. Dokumen dianggap selesai ketika sumbernya selesai, dan HTML yang terbentuk merupakan produknya, bukan berkas yang dirawat sendiri. Pembagian peran ini menjaga laporan tetap konsisten dengan kode sumbernya dalam jangka panjang.

Hubungan dengan R Markdown#

R Markdown adalah pendahulu Quarto dengan konsep yang sama, yaitu prosa dan chunk dalam satu berkas berekstensi .Rmd yang dirender menjadi dokumen akhir. Dokumen R Markdown dirender dari dalam R dengan rmarkdown::render("laporan.Rmd"), sedangkan Quarto merender dari terminal dengan quarto render tanpa perlu membuka sesi R. Quarto berdiri di atas pandoc dan mendukung banyak bahasa komputasi, sehingga alur kerja keduanya serupa tetapi alat rendernya berbeda.

Kedua format memakai mesin eksekusi yang sama, yaitu knitr, sehingga perilaku eksekusi chunknya serupa. Penulisan opsinya pun serupa dengan sedikit perbedaan, yaitu R Markdown menuliskannya di dalam kurung kurawal pembuka chunk, sedangkan Quarto memakai baris khusus berawalan #|. Untuk dokumen yang hanya memuat kode R, keduanya menghasilkan laporan dengan karakter yang sama, dan pengetahuan tentang struktur kepala YAML beserta opsi chunk berlaku di kedua format tersebut.

Ringkasan#

• Dokumen analisis literat menyatukan narasi, kode, dan hasil eksekusinya dalam satu berkas, dan merender ulangnya menjalankan seluruh kode dari awal.
• Dokumen .qmd terdiri atas kepala YAML, prosa Markdown, dan chunk ```{r} yang dieksekusi saat render.
• Perintah quarto render laporan.qmd --to html menjalankan chunk melalui knitr lalu membentuk HTML melalui pandoc.
• R Markdown dengan berkas .Rmd dan rmarkdown::render() mengikuti konsep yang sama dengan alat dan perintah yang berbeda.

Referensi#

• Quarto — Posit — Situs resmi Quarto dengan dokumentasi format .qmd dan perintah rendernya.
• Getting Started with Quarto — Posit — Panduan resmi pertama membuat dan merender dokumen Quarto.
• rmarkdown: Dynamic Documents for R — RStudio/Posit — Dokumentasi resmi R Markdown sebagai pendahulu Quarto.