KAL
Menu

Parameter dan Rendering

Laporan terparameterisasi yang dapat dirender ulang untuk data berbeda.

Daftar isi

Topik ini membahas laporan terparameterisasi, yaitu dokumen Quarto yang variabelnya dideklarasikan pada kepala YAML sehingga isi laporan berubah mengikuti nilai yang diberikan saat render. Pembahasan mencakup penulisan parameter params, aksesnya dari dalam chunk, render ulang dengan opsi -P, dan perbandingan hasil dua render dengan parameter berbeda. Mekanisme parameter ini berasal dari laporan terparameterisasi R Markdown dan dipakai Quarto dengan cara yang sama. Setelah membacanya, satu templat laporan dapat melayani banyak kelompok data tanpa disunting ulang.

Parameter pada kepala YAML#

Parameter dideklarasikan pada kunci params di kepala YAML. Setiap parameter diberi nama dan nilai bawaan, dan seluruhnya tersedia di dalam chunk sebagai elemen objek params, misalnya params$kelas untuk parameter bernama kelas. Nilai bawaan inilah yang dipakai apabila render tidak menyebut parameter apa pun. Berkas berikut adalah laporan kecil yang menerima parameter kelas lalu menampilkan rata-rata ujian kelas tersebut:

qmd laporan-parameter.qmd 
---
title: "Rekap Nilai per Kelas"
format: html
params:
  kelas: "7A"
---

Laporan ini menampilkan rata-rata nilai ujian untuk kelas yang ditentukan oleh parameter `kelas`.

```{r}
nilai <- data.frame(
  siswa = c("Ali", "Budi", "Citra", "Dewi"),
  kelas = c("7A", "7A", "7B", "7B"),
  ujian = c(85, 78, 92, 88)
)
pilihan <- nilai[nilai$kelas == params$kelas, ]
cat("Kelas:", params$kelas, "\n")
cat("Rata-rata:", mean(pilihan$ujian), "\n")
```

Chunk di atas mengambil subset baris yang kolom kelas-nya sama dengan params$kelas, lalu mencetak nama kelas dan rata-ratanya. Karena pemilihan baris bergantung pada parameter, dokumen yang sama menghasilkan rekap yang berbeda untuk setiap nilai parameter yang diberikan. Merender dokumen dengan nilai bawaannya dilakukan dengan perintah biasa, dan opsi -o menentukan nama berkas keluarannya:

bash 
# render dengan parameter bawaan, yaitu kelas 7A
quarto render laporan-parameter.qmd --to html -o rekap-7a.html
text Keluaran 
processing file: laporan-parameter.qmd
1/3
2/3 [unnamed-chunk-1]
3/3
output file: laporan-parameter.knit.md

pandoc -o rekap-7a.html
  to: 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 per Kelas

Output created: rekap-7a.html

Keluarannya memperlihatkan eksekusi chunk oleh knitr lalu pembentukan HTML oleh pandoc, dan nama kelas 7A pada hasil eksekusi berasal dari nilai bawaan parameter. Parameter tidak terbatas satu dan tidak harus berupa teks. Nilai numerik, logika, atau tanggal dapat dideklarasikan dengan cara yang sama, misalnya batas_lulus: 75, dan seluruhnya terbaca dari objek params dalam satu pemanggilan render. Nilai bawaan sebaiknya dipilih sebagai variasi yang paling sering dipakai, karena render tanpa -P memakai nilai bawaan itu secara langsung.

Merender ulang dengan -P#

Opsi -P memberikan nilai parameter baru pada saat render, dengan bentuk -P nama:nilai. Nilai yang diberikan menggantikan nilai bawaan hanya untuk render tersebut, sehingga berkas sumber tidak pernah berubah. Nama parameternya harus sama dengan yang dideklarasikan di YAML, dan parameter yang lebih dari satu dituliskan dengan pasangan -P tambahan. Render berikut meminta parameter kelas bernilai 7B, dan seluruh chunk dieksekusi ulang dengan nilai tersebut:

bash 
# render ulang dengan parameter kelas 7B
quarto render laporan-parameter.qmd --to html -P kelas:7B -o rekap-7b.html
text Keluaran 
processing file: laporan-parameter.qmd
1/3
2/3 [unnamed-chunk-1]
3/3
output file: laporan-parameter.knit.md

pandoc -o rekap-7b.html
  to: 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 per Kelas

Output created: rekap-7b.html

Keluaran render kedua serupa dengan yang pertama dan hanya berbeda pada nama berkas tujuannya. Tidak ada bagian proses yang dilewati, karena chunk-nya tetap dieksekusi ulang dari awal dengan nilai parameter baru. Perbedaan utama dengan menyunting berkas sumber lalu merender ulang adalah opsi -P menghasilkan variasi laporan tanpa menyentuh sumbernya.

Isi kedua berkas HTML yang dihasilkan dapat diperiksa dengan mencari baris rata-rata yang dicetak chunk:

bash 
# angka rata-rata pada hasil render kelas 7A
grep -o "Rata-rata: [0-9.]*" rekap-7a.html
# angka rata-rata pada hasil render kelas 7B
grep -o "Rata-rata: [0-9.]*" rekap-7b.html
text Keluaran 
Rata-rata: 81.5
Rata-rata: 90

Sumber dokumennya sama persis, tetapi rekap-7a.html memuat rata-rata 81.5 untuk kelas 7A, sedangkan rekap-7b.html memuat rata-rata 90 untuk kelas 7B. Perbedaan itu sepenuhnya berasal dari opsi -P, karena chunk dijalankan ulang dengan params$kelas yang berbeda sehingga subset barisnya ikut berbeda. Tidak ada satu baris pun kode yang disunting di antara kedua render.

Kegunaan laporan terparameterisasi#

Laporan terparameterisasi menggantikan kebiasaan menyalin skrip lalu menyunting angka atau nama kelompoknya secara manual. Satu templat rekap nilai dapat dirender per kelas dengan -P kelas:7A, -P kelas:7B, dan seterusnya, sehingga seluruh keluaran menaati perhitungan yang sama. Pola yang sama berlaku untuk rekap bulanan, yaitu parameter bulan yang memilih periode data pada setiap render. Kebiasaan ini juga menyederhanakan arsip, karena setiap render menyimpan berkas keluarannya sendiri, misalnya rekap-7a.html dan rekap-7b.html pada contoh di atas, dan isinya tidak saling menimpa. Pola ini bekerja baik dengan penjadwalan, yaitu render otomatis pada waktu tertentu untuk menghasilkan laporan periode terbaru tanpa sentuhan tangan. Karena seluruh variasi berasal dari satu templat, perbaikan pada satu tempat langsung berlaku untuk semua laporan turunannya, sehingga tidak ada salinan yang tertinggal memakai versi lama.

Kesalahan umum#

Pesan tersebut muncul saat chunk dieksekusi, bukan saat dokumen disunting, sehingga kesalahannya mudah terlewat sampai render pertama dijalankan. Dokumen yang gagal seperti ini tidak menghasilkan berkas HTML apa pun, sehingga kegagalannya tidak dapat diselamatkan sebagian. Penyebab paling umum adalah memindahkan chunk dari dokumen lain tanpa menyalin kunci params-nya. Pemeriksaan cepat sebelum render adalah mencari setiap penyebutan params$ dalam chunk lalu memastikan namanya terdaftar di YAML. Deklarasi tetap diperlukan sekalipun render selalu menyebut -P, karena nilai bawaannya yang menentukan hasil render tanpa -P. Setelah deklarasi ada, render dengan atau tanpa -P sama-sama berhasil, karena -P hanya mengganti nilai bawaan tersebut untuk render itu saja.

Ringkasan#

  • Parameter dideklarasikan pada kunci params di kepala YAML dan diakses dari chunk sebagai params$nama.
  • Opsi -P nama:nilai pada quarto render mengganti nilai parameter untuk render tersebut, dan seluruh chunk dieksekusi ulang dengan nilainya.
  • Dua render dari satu templat yang sama menghasilkan laporan berbeda hanya karena parameter yang diberikan, sebagaimana rata-rata 81.5 untuk 7A dan 90 untuk 7B.
  • params yang dipakai dalam chunk wajib dideklarasikan di YAML terlebih dahulu, jika tidak, render berhenti dengan error object 'params' not found.

Referensi#