Bagaimana saya memastikan bahwa hasil simulasi saya dan hasil di kertas saya selalu sinkron?

34

Di salah satu makalah saya, saya mencantumkan beberapa hasil numerik di samping beberapa angka. Yang ingin saya lakukan adalah memastikan bahwa hasil numerik dalam makalah saya selalu setuju dengan kode. Saat ini, saya hanya langsung menyalin hasil numerik dari hasil simulasi saya ke dalam kertas, yang sangat sederhana dan berteknologi rendah, tetapi rawan kesalahan, karena saya bisa salah menyalin hasil, atau lupa untuk menyinkronkan hasil kertas dengan output kode.

Apakah ada cara yang baik untuk menjaga hasil numerik yang saya kutip di koran saya sinkron dengan hasil yang dihasilkan oleh kode saya? (Di sini, saya berasumsi bahwa mengeksekusi kode itu mudah dan praktis dilakukan setiap kali saya ingin memperbarui makalah saya.) Hasil numerik ini tidak selalu cocok untuk bentuk tabel. Kadang-kadang, saya memiliki tabel dalam naskah, tetapi lebih umum, saya memiliki parameter simulasi terdaftar sebagai angka dalam persamaan . Contohnya akan seperti:

y=(y1,,yn)

di mana saya ingin mengganti elemen kondisi awal dengan parameter aktual yang saya gunakan dalam simulasi yang secara numerik mengintegrasikan sistem persamaan diferensial biasa. Menggunakan tabel untuk data satu kali saja seperti contoh ini sepertinya terlalu banyak menghabiskan waktu dan lebih banyak tinta daripada yang diperlukan.y

Saya berasumsi bahwa angka-angka adalah kasus yang lebih mudah: setiap kali dokumen "dibangun" (dari sumber LaTeX, Markdown, RST, dll.), Mulailah proses pembuatan dengan mengeksekusi kode. Namun, jika orang memiliki saran yang lebih baik untuk menjaga angka yang dihasilkan oleh simulasi saya sinkron dengan kertas saya, saya akan senang mendengarnya.

Geoff Oxberry
sumber

Jawaban:

14

Seperti yang dikemukakan beberapa komentar, pendekatan ini telah lama dikembangkan di komunitas R dengan membangun Sweavedan baru-baru ini knitr,. Jelas pendekatan ini memiliki kelemahan yaitu spesifik bahasa pada saat ini, tetapi keuntungan yang secara teratur digunakan dalam makalah akademik.

Penggunaan Sweave dalam publikasi nyata

  • The Journal of biostatistik mendorong pengajuan tersebut, dan menempatkan surat Kitemark "R" pada makalah akademik di mana editor reproduciblity telah mampu menjalankan kode dan data dan mendapatkan hasil ini.
  • Intinya semua publikasi di R-Journal dibangun di atas Sweave.

Tentu saja lebih umum pengguna Sweave / knitr mengirimkan hanya hasil akhir ke sebagian besar jurnal, dengan keyakinan pribadi bahwa metode memang mereproduksi hasil. Demikian juga sweave sering digunakan untuk membuat slide untuk pembicaraan profesional, dll.

Fitur yang berguna

Agar bermanfaat dalam praktik, sistem seperti itu harus memiliki fitur tertentu. Dengan sejumlah besar pengguna, banyak dari ini dikembangkan dengan baik di knitr. Beberapa highlight:

  • Caching. Menulis dalam format seperti penurunan harga atau lateks yang harus dikompilasi untuk melihat hasilnya membuat ini termasuk kode tidak mungkin ketika hasilnya tidak dapat di-cache. Caching pintar knitrsebenarnya membuat debug intensif kode jauh lebih mudah daripada bekerja di murni R, karena tidak perlu untuk menjalankan kembali potongan yang sukses.

  • Tampilkan kode tampilan. Dalam publikasi formal, seseorang mungkin tidak ingin kode yang mendasarinya terlihat pada output. Sementara itu, seringkali berharga untuk menunjukkan kode (diformat dengan baik, sintaksis yang disorot) yang menghasilkan hasil dalam format output ketika Anda ingin pembaca melihat apa yang Anda ketikkan.

  • Masyarakat. Mungkin keuntungan yang paling menarik dari pendekatan ini dibandingkan solusi buatan sendiri adalah jumlah orang yang akrab dengan model dan berusaha untuk memperbaikinya.

  • Banyak contoh bagus dari fitur lain dapat ditemukan di demo halaman web rajutan , termasuk alat untuk "penerbitan ringan" atau berbagi di web. Banyak fitur ini membantu membuat pendekatan ini lebih kompatibel dengan alur kerja umum seseorang, daripada hanya melakukan sesuatu ketika menulis naskah.

Catatan kaki historis.

Meskipun berakar pada "pemrograman melek huruf" Knuth, seperti namanya, penekanannya sangat berbeda, karena pemrograman melek huruf berfokus pada menghubungkan kode perangkat lunak dan dokumentasi (dalam komunitas R peran yang dimainkan Roxygen, yang menelusuri akarnya ke cabang berbeda dari "pohon pemrograman melek huruf").

Melampaui

Pada prinsipnya kita mungkin bertanya lebih banyak dari dokumen dinamis, seperti kemampuan pembaca untuk mengubah input dan melihat output tanpa harus mengedit dan mengkompilasi ulang seluruh dokumen, misalnya, menggunakan platform online interaktif. XDynDocs mungkin merupakan langkah ke arah ini.

Pendekatan lain

  • Mungkin ingin mengawasi dexy.it
  • Dalam pendekatan yang sedikit berbeda: Semakin banyak kode host makalah ekonomi yang terkait dengan publikasi di http://www.runmycode.org/ , yang akan menjalankan kembali analisis di cloud, dan memungkinkan parameter input khusus atau data input khusus.
cboettig
sumber
Carl, saya telah mengikuti situs web Anda untuk sementara waktu, dan pendekatan Anda dengan rajutan adalah salah satu inspirasi untuk pertanyaan saya. Saya juga sudah mengikuti dexy untuk sementara waktu karena Zed Shaw menggunakannya untuk membangun sumber bukunya How To Learn Python the Hard Way (lihat git repo ). Apa yang saya sukai dari dexy sebagai lawan dari pendekatan pemrograman terpelajar lainnya adalah bahwa kode dan teks secara longgar digabungkan, memungkinkan penggunaan debugger secara bijaksana.
Geoff Oxberry
Geoff, keren, terima kasih atas komentarnya! Anna Nelson juga sangat percaya akan decoupling. Pengguna R dapat menyelesaikan decoupling di knitr dengan eksternalisasi kode , atau spin()fungsi baru . Secara pribadi saya pikir keluhan Greg Wilson tentang pemrograman melek cukup lumayan. Saya memiliki pengalaman mengerikan yang sama dengan yang ia gambarkan dengan noweb, tetapi debugging yang berbelit-belit tidak ada dalam alat modern. Untuk CI yang melek huruf, gunakan doxygen. Knitr adalah sesuatu yang lebih mudah di-debug daripada R berkat caching dan penanganan lingkungan.
cboettig
20

Apa yang Anda minta adalah tantangan besar Elsivier dari "Kertas Eksekusi" . Sementara banyak pendekatan telah dicoba, tidak ada yang semenarik yang disarankan penulis. Berikut adalah beberapa contoh teknik yang digunakan.

Proyek Madagaskar mengambil pendekatan Anda, di dalam skrip make memiliki simulasi menjalankan yang menghasilkan angka dan kertas secara bersamaan.

IPython Notebook menyediakan dokumen yang dapat dieksekusi saat Anda membaca dan menghasilkan gambar dengan isi hati Anda. (Saya pernah melihat plugin kata, Mathematica, dan banyak solusi lain yang digunakan dengan cara yang sama)

VisTrails menggunakan pendekatan arsitektur berorientasi layanan dan menyediakan manajer "takdir" atau "alur kerja". Pada dasarnya Anda mendaftarkan kait ke kode kemudian merancang alur kerja atau percobaan yang mereproduksi pekerjaan Anda. Ini telah digunakan pada banyak jenis kode, bahkan cluster HPC. Dengan pendekatan ini, Anda akan memiliki cara untuk memutar ulang percobaan.

Ada banyak solusi jenis ini di luar sana, tetapi mereka adalah tiga yang saya terkesan. Ini masalah yang sulit dan saya percaya kita benar-benar bahkan tidak dekat untuk mengatasi. Kami bahkan tidak bisa membuat orang merilis kode mereka dengan makalah mereka, bagaimana kami bisa mengharapkan mereka mereproduksi hasil = P

aterrel
sumber
Dalam nada yang sama ada sweave , yang bukan sesuatu yang saya gunakan tetapi menarik dalam konsep.
dmckee
Proyek Madagaskar sepertinya bisa menarik ketika saya mendengarkan ceramah oleh salah satu penulisnya. Saya belum benar-benar mencoba menggunakannya.
Ken
@ dmckee: Saya tahu orang-orang yang telah sukses dengan sweave dan rajutan . Saya curiga pendekatan pemrograman melek untuk alasan yang sama yang Greg Wilson berikan pada Software Carpentry : kertas dan kode terlalu erat digabungkan, yang membuatnya sulit untuk menjalankan debugger pada kode (dan bisa menghalangi pemeriksaan) teks).
Geoff Oxberry
Saya menggunakan Sweave untuk tujuan ini, ia bekerja dengan sangat baik dan kompatibel dengan Lyx. Mode-Org bahkan lebih baik dan mendukung sebagian besar bahasa yang umum.
David LeBauer
13

Saya belum banyak berhasil menggunakan solusi orang lain untuk masalah ini. Saya biasanya hanya menginginkan sesuatu yang sederhana yang bekerja untuk saya dan menyelesaikan pekerjaan. Untuk tujuan ini, saya biasanya mencoba menulis satu skrip python yang bertugas menjalankan semua hasil, parsing output, serta membangun angka / tabel.

Saya menulis kode saya untuk menghasilkan file data yang berisi hasil dalam beberapa format teks. Anda dapat menghindari menjalankan kembali hasil ini dalam skrip Anda dengan terlebih dahulu menguji keberadaan file output (misalnya dengan python menggunakan os.path.isfile ()). Jika Anda ingin menjalankan kembali hasil Anda, cukup hapus file data. Jika file data ada, maka saya menjalankan parser dari file-file ini. Untuk ini, modul python untuk ekspresi reguler sangat berguna (kembali).

Kemudian dari hasil parsing saya membuat angka atau tabel. Untuk tabel dalam lateks Anda dapat menulis kode untuk menghasilkan tabel menjadi file terpisah (saya menggunakan ekstensi .tbl) dan kemudian memasukkan ini ke dalam file lateks Anda. Kuncinya bagi saya adalah dengan menggunakan 1 skrip python. Jika saya memiliki banyak, maka saya kemudian bertanya-tanya mana yang mana dan apa yang mereka lakukan. Jika deskripsi ini terlalu kabur, saya dapat mengirimkan beberapa contoh kepada Anda.

Nathan Collier
sumber
1
Saya sudah melakukan hal ini untuk angka. Namun, dalam makalah yang saya tulis, tabel akan menjadi format yang tidak wajar untuk menyajikan data. Sering kali, saya benar-benar hanya ingin memasukkan kondisi awal ke ODE (jadi benar-benar, sekitar 4-6 angka, spasi dengan koma), atau seluruh matriks angka sebagai bagian dari sisi kanan sebuah persamaan. Saya suka ide Anda untuk tabel. Untuk kasus-kasus yang saya sebutkan, saya merasa bahwa memformat ulang mereka sebagai tabel akan tidak wajar, dan saya ingin memasukkan data dalam format yang lebih alami.
Geoff Oxberry
Nathan, maukah Anda memposting contoh? Saya menggunakan pendekatan yang sama, kecuali bahwa saya memasukkan file teks ke git, dan menggunakan git untuk mengelola hasilnya. Saya kemudian memiliki skrip Python untuk menghasilkan plot / tabel. Saya punya satu skrip per plot atau tabel.
Ondřej Čertík
Anda juga dapat menyalurkan output skrip shell langsung ke lateks menggunakan perintah \input{|"path-to-script.py"}. Saya pikir Anda sebaiknya meletakkan semua parameter dalam file python tunggal (atau bahasa apa pun yang menjadi favorit Anda) dan gunakan parameter baris perintah untuk mengaksesnya \input{|"path-to-script.py param-name"}. Dalam hal ini Anda dapat memasukkan file param ke skrip lain untuk menjalankan simulasi. Namun, itu membuat kompilasi lebih lambat dan memiliki beberapa poin negatif lainnya.
Helium
7

Bahkan yang lebih penting, menurut saya, adalah memastikan bahwa Anda dapat mengetahui cara untuk menghasilkan kembali semua hasil Anda dari awal dalam sebulan atau satu tahun (misalnya, ketika wasit meminta Anda untuk menambah atau memodifikasi sesuatu). Untuk tujuan itu, apa yang saya lakukan adalah memasukkan file teks dengan arah yang sangat rinci tentang cara mereproduksi semua hasil. Lebih baik jika Anda menguji ini dengan meminta orang lain (seperti penulis pendamping) mencobanya. Saya sarankan Anda juga memberikan instruksi ini (dan semua kode Anda) kepada wasit dan pembaca.

Berikut ini sebuah contoh (sebenarnya disiapkan oleh rekan penulis saya, Aron Ahmadia).

David Ketcheson
sumber
Saya telah melakukan itu sebelumnya (untuk kewarasan saya sendiri), dan untungnya, itu terbayar ketika penasihat saya meminta saya untuk menghasilkan kembali dan memeriksa kembali hasilnya. Sejak itu saya beralih ke hanya membuang kode sumber skrip yang menjalankan semuanya menjadi lampiran dari konsep saya sehingga ada di sana, saya tahu apa yang saya lakukan, dan saya bisa mengklik satu tombol untuk mendapatkan semua angka dan angka.
Geoff Oxberry
Script tidak melakukan instalasi apa pun sekarang, karena itu hanya skrip MATLAB. Dalam dokumentasi fungsi, ini mencantumkan dependensi pada paket pihak ketiga. Paket pihak ketiga tersebut, pada gilirannya, keduanya memiliki dokumentasi yang jelas tentang cara menginstalnya (dan untungnya, juga didukung secara aktif, memiliki pengembang yang hebat, dan milis aktif).
Geoff Oxberry
6

Orgmode Emacs dalam kombinasi dengan Babel mencapai itu. Babel dapat mengeksekusi cuplikan kode dari berbagai bahasa pemrograman dan skrip, misalnya, ia dapat membuka file yang berisi data simulasi dan memasukkannya ke dalam tabel dalam orgmode, yang dapat diekspor ke LaTeX (dan banyak format lainnya). Dibutuhkan waktu yang cukup lama untuk terbiasa dengan semua kombo kunci dalam orgmode, tetapi begitu itu berjalan semuanya otomatis.

Robert
sumber
Saya suka mode-org; Saya menggunakannya untuk garis besar. Saya belum menggunakannya dengan Babel. Saya harus mencobanya.
Geoff Oxberry
Berikut ini adalah ikhtisar yang sangat baik dari Jan 2012 J. Stat. Perangkat lunak jstatsoft.org/v46/i03/paper
David LeBauer
Saya menulis tutorial yang menunjukkan cara mengkonversi template LaTeX dari European Physical Journal A (EPJ A) menjadi file mode-org.
Melioratus
4

Jika menjalankan semua kode Anda murah maka Anda bisa melakukan sesuatu yang berteknologi rendah seperti berikut:

Anda bisa templat dokumen Anda dengan string yang diformat sehingga terlihat seperti ini

"we observed a %(fractional_improvement)s increase in ..."

Memiliki skrip python yang terlihat seperti ini

results = {"alpha"                  : run_alpha_computation(...),
           "fractional_improvement" : run_fi_computation(...), 
           ...}

Dan kemudian lakukan sesuatu seperti ini

for fn in filenames:
    file = open(fn);      s = file.read();       file.close()
    file = open(fn, 'w'); file.write(s%results); file.close()

Anda kemudian dapat membungkusnya dalam Makefile.

MRocklin
sumber
Pikiran pertama saya ketika saya menulis pertanyaan ini adalah solusi seperti yang Anda usulkan. Saya awalnya memikirkan sesuatu yang berteknologi rendah seperti menggunakan preprocessor makro, tetapi Python mungkin merupakan pendekatan yang lebih baik (dan tentu saja lebih mudah dibaca), maka sistem build dapat menangani regenerasi hasil secara bertahap.
Geoff Oxberry
Sungguh ini hanyalah implementasi yang sangat mendasar dari sesuatu seperti halaman server python. Ide konten yang dibuat secara otomatis telah ada di komunitas web untuk sementara waktu. Akan menyenangkan melihatnya bermigrasi ke akademia.
MRocklin
Sepakat. Jinja2 dapat digunakan untuk melakukan apa yang Anda sarankan. Sebenarnya, itulah yang dilakukan dexy , tetapi dengan sekelompok filter keren yang juga menangani penyorotan sintaks dan tugas-tugas lainnya yang rumit.
Geoff Oxberry
4

Jika Anda menggunakan LaTeX, solusi yang relatif berteknologi rendah adalah membuat kode Anda meludahkan file (atau menggunakan skrip untuk memfilter dari output kode Anda) yang berisi sejumlah baris seperti ini:

\newcommand{\myresults1}{<value>}

Kemudian Anda bisa menggunakan \inputperintah untuk menambahkan file itu ke dalam dokumen Anda, dan menggunakan perintah yang ditentukan untuk menempatkan nilai-nilai.

Aesin
sumber
2

Saya bekerja untuk Elsevier. Perusahaan saya telah mulai menggunakan kerangka kerja Collage (dikembangkan sebagai tanggapan terhadap Tantangan Besar Kertas yang Dapat Dieksekusi) dalam masalah jurnal untuk memungkinkan penulis untuk mempublikasikan potongan kode yang dapat dieksekusi dengan artikel mereka. Fitur ini memudahkan pembaca untuk mereproduksi hasil yang dilaporkan dalam artikel dan menggunakan kembali materi yang dipublikasikan untuk penelitian mereka sendiri. Collage mendukung berbagai macam perangkat lunak open-source dan proprietary; informasi lebih lanjut dapat ditemukan di video informasi di sini dan di Situs Web Collage Authoring Environment .

Hylke Koers
sumber
Tautan kedua adalah ke hal yang salah.
David Ketcheson
@Hylke Koers: Apakah Anda bermaksud menaruh tautan ini: collage.elsevier.com ?
Paul
@ Paul: Saya sudah mengedit; tautan kedua asli adalah ke Collage Google Group. Mungkin tautan yang lebih baik adalah untuk Collage sendiri, tetapi fokus saya adalah mencoba (sebagian besar) menjaga niat baik dari pos sambil menghapus bagian-bagian yang membuatnya terdengar promosi. Merasa bebas untuk mengedit posting sesuai keinginan Anda.
Geoff Oxberry