KAL
Menu

Dokumentasi EDA

Notebook yang dapat diikuti orang lain: narasi, urutan, dan keputusan yang tercatat.

Daftar isi

Notebook eksplorasi yang hanya berisi kode adalah notebook yang gagal, karena yang membedakan eksplorasi dari eksperimen pribadi adalah kemampuan orang lain mengikutinya. Topik ini menetapkan bentuk dokumentasi EDA, yaitu narasi yang menyertai setiap keputusan, urutan eksekusi yang lurus, dan templat kerangka yang dipakai sepanjang jalur ini. Setelah membacanya, notebook hasil eksplorasi dapat diserahkan kepada rekan kerja tanpa sesi penjelasan lisan.

Notebook yang lurus lebih dahulu#

Nilai dokumentasi paling dasar adalah reproduksinya, dan syaratnya satu, yaitu notebook dijalankan ulang dari sel pertama sampai terakhir tanpa kekacauan. Kebiasaan yang menopangnya sederhana, yaitu sel impor dan pemuatan data berada di atas, setiap keadaan yang bergantung pada urutan dieksplisitkan, dan tidak ada sel yang menyandarkan hasilnya pada keadaan sisa dari sesi lama.

Perintah “Restart Kernel and Run All Cells” menjadi gerbang mutlak sebelum hasil diserahkan, karena ia memaksa seluruh notebook berjalan dalam urutan yang akan ditemui pembacanya. Notebook yang gagal pada gerbang itu menyimpan keputusan yang belum selesai, dan memperbaikinya lebih dahulu jauh lebih murah daripada menjelaskan mengapa angkanya berbeda-beda.

Keadaan yang menjalar antar sel juga dibatasi secara sadar. Variabel yang dipakai lintas bagian dinamai dengan jelas dan didefinisikan sekali di atas, sedangkan pekerjaan sementara diletakkan pada sel yang berdekatan dengan narasinya, sehingga pembaca tidak perlu mencari asal sebuah angka ke belakang.

Narasi yang menjawab mengapa#

Sel kode menjawab apa yang dilakukan, sedangkan sel Markdown menjawab mengapa, dan rasionya kira-kira satu sel narasi untuk setiap dua atau tiga sel kode. Narasi yang berguna menyatakan tiga hal, yaitu pertanyaan bagian tersebut, keputusan yang diambil beserta alasannya, dan temuan yang diperolehnya.

Kamus pembersihan adalah bagian narasi yang paling bernilai, karena setiap perlakuan data hilang, duplikat, dan rentang pada modul pembersihan membawa justifikasi yang mudah hilang dari ingatan. Satu baris per perlakuan dalam bentuk “perlakuan, karena alasan” menjadikan seluruh keputusan dapat dipertanyakan secara terarah, bukan ditebak.

Angka yang dilaporkan pada narasi juga dibuat sulit salah dengan f-string yang membaca variabel, alih-alih diketik tangan ke dalam kalimat. Apabila data diperbarui dan notebook dijalankan ulang, narasinya ikut diperbarui, dan ketidakcocokan antara kalimat dan keluaran tidak pernah muncul.

Templat kerangka yang dipakai jalur ini#

Kerangka tetap membuat dua notebook dari dua orang berbeda terbaca dengan cara yang sama, dan templat berikut menjadi baku pada jalur ini.

markdown templat_notebook_eda.md 
# Templat Notebook EDA

Kerangka ini dipakai sebagai urutan judul sel Markdown pada setiap notebook
eksplorasi. Satu notebook menjawab satu pertanyaan, dan keputusan yang
diambil dinyatakan pada bagian yang tepat, bukan pada komentar kode.

## 1. Konteks dan pertanyaan

- Keputusan yang hendak didukung: ...
- Pertanyaan yang dapat diuji: ...
- Metrik keberhasilan dan pembandingnya: ...

## 2. Sumber data

- Berkas dan asalnya (dari mana, tanggal perolehan, pemiliknya): ...
- Granularitas: satu baris mewakili ...
- Satuan setiap kolom ukur: ...

## 3. Kamus pembersihan

Setiap perlakuan satu baris, dengan alasannya.

- Nilai hilang: perlakuan ... karena ...
- Duplikat: perlakuan ... karena ...
- Teks dan tanggal: perlakuan ... karena ...
- Nilai di luar rentang: perlakuan ... karena ...

## 4. Temuan

Setiap temuan bernomor, dengan angka atau grafik sebagai buktinya, dan
ditulis dalam satu kalimat.

1. ...
2. ...
3. ...

## 5. Hipotesis lanjutan

Temuan yang membutuhkan data baru atau pengujian statistik dipindahkan ke
sini, bukan ditarik kesimpulannya sekarang.

- Hipotesis: ... cara mengujinya: ...

## 6. Keputusan dan batas

- Yang dapat dinyatakan sekarang: ...
- Yang belum dapat dinyatakan dan alasannya: ...
- Asumsi yang diambil: ...

Bagian paling sering dilewati adalah yang keenam, padahal bagian itulah yang membuat notebook dipercaya. Batas yang dinyatakan, misalnya “data hanya dua hari sehingga pola mingguan belum dapat dinyatakan”, melindungi pembaca dari penggunaan berlebihan, dan asumsi yang tercatat menunjuk persis apa yang harus diperiksa ulang ketika data baru datang.

Dari notebook ke pekerjaan berikutnya#

Dokumentasi EDA juga menentukan masa depan pekerjaan itu sendiri. Notebook yang bagian temuannya bernomor memetakan langsung ke daftar hipotesis dan ke struktur laporan akhir, sedangkan notebook yang acak harus diurai ulang dari nol ketika laporan diminta.

Batas notebook juga disebut jujur, yaitu eksplorasi bukan produk akhir. Ketika analisis sudah mapan dan harus dijalankan ulang secara berkala, isinya dipindahkan ke skrip Python dengan struktur proyek sebagaimana dibahas pada modul reproduktibilitas, sedangkan notebook tetap menjadi arsip penalarannya.

Kesalahan umum#

Kesalahan pertama adalah notebook yang urutan selnya tidak lurus, dengan hasil pada sel ke-40 bergantung pada sel ke-12 yang dijalankan ulang setelahnya. Gerbang “Run All” sebelum penyerahan menangkapnya setiap kali.

Kesalahan kedua adalah narasi yang mengulang kode, misalnya “sel ini menghitung rata-rata” tanpa menyebut mengapa dan apa temuannya. Narasi yang berguna selalu membawa keputusan dan temuan, dan kode yang dibacanya sudah menyatakan caranya.

Kesalahan ketiga adalah menyimpan keluaran sel yang sudah usang, yaitu notebook yang ditampilkan dengan grafik dari data lama sementara kodenya sudah berubah. Menjalankan ulang seluruh notebook sebelum disimpan membuat keluaran yang terlihat selalu sama dengan kode yang ada.

Ringkasan#

  • Notebook yang layak diserahkan berjalan lurus dari sel pertama sampai terakhir, dan gerbangnya adalah “Restart and Run All”.
  • Narasi menjawab mengapa dengan tiga hal, yaitu pertanyaan, keputusan beserta alasannya, dan temuan bagian itu.
  • Templat enam bagian, dari konteks sampai keputusan dan batas, menjadikan notebook antar orang terbaca dengan cara yang sama.
  • Angka pada narasi dibaca dari variabel, sehingga kalimat dan keluaran tidak pernah berbeda.

Referensi#