Otomatik raporlama

Öğrenme çıktıları

• Hatırlama — Okuryazar programlamayı, dinamik belgeyi, şablonu, parametreli raporu, gizli durumu ve belge derlemeyi tanımlar.
• Anlama — Rapordaki sayıların, tabloların ve grafiklerin analiz koduyla aynı belgede üretilmesinin, elle kopyalamaya göre hangi hataları önlediğini ve not defterlerinin hangi yeni hatalara açık olduğunu açıklar.
• Uygulama — Python'da bir şablonla, hesaplanan sayıları ve grafikleri içeren bir raporu birkaç il için döngüyle üretir; Quarto ve R Markdown ile parametreli bir raporun nasıl derlendiğini açıklar.
• Değerlendirme — Nuijten ve arkadaşlarının raporlama hataları bulgusunu ve Pimentel ve arkadaşlarının not defterleri çalışmasını kullanarak bir raporlama iş akışının güvenilirliğini değerlendirir.

Sezgi

Açılış

Bir araştırmacı, bir ay önce bitirdiği analizin raporunu gözden geçiriyor. Metinde eğitimin getirisinin yüzde 8,4 olduğu yazıyor; tabloda ise 0,086 görünüyor. Hangisi doğru? Analiz tekrar çalıştırılmış, tablo güncellenmiş, ama metindeki sayı eski kalmış olabilir. Ya da tersi. Grafiğin altındaki notta ise hâlâ geçen ayki veri tarihi yazıyor.

Bu tür tutarsızlıklar, analiz ile raporun ayrı yerlerde yaşamasından doğar. Kod bir yerde çalışır, sonuçlar ekrana yazılır, araştırmacı onları bir kelime işlemciye elle kopyalar. Her kopyalama bir hata fırsatıdır ve analiz her değiştiğinde, raporun hangi kısımlarının güncellenmesi gerektiğini hatırlamak araştırmacıya kalır.

Otomatik raporlama, bu ayrılığı ortadan kaldırmayı amaçlar: raporun metni, tabloları, grafikleri ve metnin içindeki sayılar, analiz koduyla birlikte tek bir belgeden üretilir. Veri değiştiğinde rapor tek komutla yeniden üretilir ve metindeki her sayı, onu hesaplayan kodun güncel çıktısıdır. Bu ders, bu yaklaşımın kökenini, araçlarını ve yeni tuzaklarını ele alıyor.

Hikâye — Programları okunacak metinler olarak yazmak

1984'te bilgisayar bilimci Donald Knuth, The Computer Journal'da «Literate Programming», yani «Okuryazar Programlama» başlıklı bir makale yayımladı. Makalenin özetine göre Knuth ve çalışma arkadaşları, birkaç yıldır WEB adını verdikleri bir programlama dili ve belgeleme sistemiyle deneyler yapıyordu; makale, WEB'i örneklerle sunuyor ve bu yeni sistemin öncekilerden neden daha iyi göründüğünü tartışıyordu. Knuth'un fikri, bir programı öncelikle bilgisayara verilecek talimatlar olarak değil, insanların okuyacağı bir metin olarak yazmaktı: açıklamalar ve kod aynı belgede, açıklamanın akışına göre dizilecek, bilgisayar ise bu belgeden hem çalışacak kodu hem de okunacak belgeyi çıkaracaktı.

Bu fikir, istatistikçiler arasında yeni bir biçim aldı. 2002'de Friedrich Leisch, Compstat konferansında «Sweave: Dynamic Generation of Statistical Reports Using Literate Data Analysis», yani «Sweave: Okuryazar Veri Analiziyle İstatistiksel Raporların Dinamik Üretimi» başlıklı bir bildiri sundu. Sweave, R kodunu bir LaTeX belgesinin içine yerleştirmeyi ve belge derlenirken kodu çalıştırıp çıktılarını belgeye eklemeyi sağlıyordu. Böylece bir istatistik raporu, sayıları elle kopyalanmış bir belge değil, her derlemede yeniden hesaplanan bir belge oluyordu.

Sonraki yıllarda aynı fikir yaygınlaştı. R dünyasında knitr paketi ve R Markdown, LaTeX yerine daha sade bir biçimlendirme diliyle aynı işi yapmayı sağladı. Python dünyasında Jupyter not defterleri, kodu, açıklayıcı metni ve çıktıları hücreler hâlinde bir arada tutan etkileşimli bir ortam sundu. Bugün Quarto, hem Python hem R kodu içeren belgeleri aynı araçla HTML, PDF ya da Word biçimine derleyebiliyor.

Bu yolculuğun ortak ilkesi, Knuth'un kırk yıl önceki önerisiyle aynıdır: açıklama ile hesaplama birbirinden ayrılmamalıdır. Ama araçlar yaygınlaştıkça, yeni sorunlar da görünür oldu. Etkileşimli not defterlerinde hücreler herhangi bir sırayla çalıştırılabildiği için, bir belgenin ekranda gösterdiği sonuçlar, onu baştan sona çalıştıran birinin elde edeceği sonuçlarla aynı olmayabilir. Kanıt bölümü bu iki yüzü birlikte ele alıyor.

Kavram

Hikâyedeki yaklaşımın adı şudur.

Bu yaklaşımın veri analizindeki ürünü şudur.

Aynı biçimde birçok rapor üretmek için şu yapı kullanılır.

Şablonun bir adım ötesi şudur.

Etkileşimli ortamların özgü bir sorunu şudur.

Son olarak, bir dinamik belgenin son biçimine dönüşmesinin adı şudur.

Veri ve kanıt

Bu bulgu psikolojiden gelse de, gösterdiği sorun her alanın sorunudur: sonuçların analiz ortamından metne elle aktarılması, sistematik hatalara açıktır. Makalelerin yarısında bir tutarsızlık bulunması, araştırmacıların dikkatsizliğinden çok, iş akışının kendisinin hataya açık olduğunu gösterir. Test istatistiği bir yerde, p değeri başka bir yerde yazılıyor ve biri güncellendiğinde öbürü unutuluyorsa, tutarsızlık kaçınılmazdır. Dinamik belgeler, sayıları doğrudan koddan çekerek bu tür hataların önemli bir kısmını ortadan kaldırır.

İki çalışma, dinamik belgelerin iki yüzünü gösterir. Nuijten ve arkadaşlarının bulgusu, elle aktarımın sorunlarını; Pimentel ve arkadaşlarının çalışması ise dinamik belgelerin kendi başına yeterli olmadığını ortaya koyar. Bir not defteri, hücrelerin çalıştırılma sırası kaydedilmediğinde ya da gizli durum biriktiğinde, elle yazılmış bir rapor kadar yanıltıcı olabilir. Çözüm, aracı değiştirmek değil, belgeyi her seferinde temiz bir oturumda baştan sona çalıştırmayı alışkanlık hâline getirmektir.

Neden önemli?

Merkez bankalarının enflasyon raporları, bakanlıkların bülten ve istatistik kurumlarının haber bültenleri, her dönem aynı yapıda, yeni verilerle yeniden üretilir. Bu raporların sayıları elle güncellendiğinde, zaman içinde tutarsızlıklar birikir. Otomatik raporlama, bu işi hem hızlandırır hem de her sayının kaynağını izlenebilir kılar.

Araştırmada ise dinamik belgeler, bir sonucun hangi kodla, hangi veriyle ve hangi seçimlerle üretildiğini, sonucun kendisiyle birlikte saklar. Bir hakem ya da bir okur bir sayıyı sorguladığında, cevap belgenin içindedir. Bu, kursun sonraki dersinde ele alacağımız tekrarlanabilir araştırmanın en somut araçlarından biridir.

Türkiye'de il ya da sektör düzeyinde düzenli rapor üreten kurumlar için parametreli raporlar özellikle kullanışlıdır: aynı analiz, 81 il ya da onlarca sektör için tek bir belgeden, her birinin kendi verileriyle üretilebilir. Ama bu raporların Türkçe biçim kurallarına, örneğin ondalık ayraç olarak virgül kullanımına uyması ve Türkçe karakterlerin doğru işlenmesi, kodun içinde açıkça sağlanmalıdır.

Model

Çözümlü örnek — Metindeki sayıyı koddan üretmek

Otomatik raporlamanın en küçük birimi, metindeki tek bir sayıdır. Bir ilin son yıldaki işsizlik oranını ve bir önceki yıla göre değişimini, elle yazmak yerine koddan cümleye yerleştirelim.

• son = d["issizlik"].iloc[-1]
• fark = son - d["issizlik"].iloc[-2]
• cumle = f"İşsizlik oranı yüzde {son:.1f} oldu; bir önceki yıla göre {abs(fark):.1f} puan {'arttı' if fark > 0 else 'azaldı'}."

f ile başlayan metin, süslü parantez içindeki ifadelerin değerini metnin içine yerleştirir; :.1f, sayıyı tek ondalık basamakla yazar. Cümledeki fiil bile, farkın işaretine göre koddan seçilir: fark pozitifse «arttı», negatifse «azaldı». Veri güncellendiğinde cümle kendiliğinden doğru kalır; önceki ayın «arttı» kelimesi yanlışlıkla bu aya taşınmaz.

Bu satırlar bir il için çalıştırıldığında, cümle «yüzde 10.1» biçiminde çıktı. Python, ondalık ayraç olarak noktayı kullanır; Türkçe bir raporda ise virgül beklenir. Bunu açıkça düzeltmek gerekir.

• Python: f"{son:.1f}".replace(".", ",")
• R: formatC(son, format = "f", digits = 1, decimal.mark = ",")

Python'daki satır 10,1 verir. Bu tür biçim kurallarını tek bir yardımcı fonksiyonda toplayıp raporun her yerinde onu kullanmak, bir sayının bir yerde noktayla, başka bir yerde virgülle yazılmasını önler. Sayılar varsayımdır.

Çözümlü örnek — Bir şablonla rapor

Bir raporun sabit metnini ve değişken kısımlarını ayırmak için şablon kullanılır. Python'da jinja2 paketi, yer tutucuları çift süslü parantezle gösteren bir şablon dili sunar.

• from jinja2 import Template
• sablon = Template("<h1>{{ il }} işsizlik raporu</h1><p>{{ son_yil }} yılında işsizlik oranı yüzde {{ son }} oldu.</p>")
• html = sablon.render(il="Ankara", son_yil=2024, son="10,1")

render, yer tutucuları verilen değerlerle doldurur ve bir HTML metni üretir; bu metin bir dosyaya yazıldığında tarayıcıda açılabilen bir rapor olur. Şablonun içinde koşullar ve döngüler de kullanılabilir: örneğin bir tablo satırlarını verideki her yıl için tekrarlamak ya da bir uyarı paragrafını yalnızca işsizlik belirli bir eşiği aştığında göstermek.

Şablonun üstünlüğü, raporun biçimi ile içeriğini ayırmasıdır. Kurum raporun görünümünü değiştirmek istediğinde yalnızca şablon değişir, analiz kodu değişmez; veri değiştiğinde ise yalnızca analiz yeniden çalışır, şablon aynı kalır. Bu dersteki örnek jinja2'nin 3.1 sürümüyle çalıştırıldı. Sayılar varsayımdır.

Çözümlü örnek — Grafik ve dosya adları

Rapora bir grafik eklemek için grafik önce bir dosyaya kaydedilir, sonra şablonda bu dosyaya bağlantı verilir.

• fig.savefig(f"{dosya_adi}.png", bbox_inches="tight")
• plt.close(fig)

plt.close, döngü içinde çok sayıda grafik üretilirken belleğin dolmasını önler; her grafik kaydedildikten sonra kapatılır. Bu satırlar üç il için çalıştırıldığında, İzmir'in grafiği İzmir.png adıyla kaydedildi. Dosya adındaki Türkçe büyük İ harfi, bazı işletim sistemlerinde, sunucularda ya da e-posta eklerinde sorun çıkarabilir; bir internet adresinde ise özel biçimde kodlanması gerekir.

Güvenli bir yol, dosya adlarını Türkçe karakterlerden arındırılmış küçük harflerle üretmektir. Python'da ı ve İ harflerini önce elle dönüştürüp, ardından unicodedata modülüyle aksanları ayıklayan küçük bir fonksiyon, İzmir'i izmir, Muğla'yı mugla, Çanakkale'yi canakkale olarak verir. Raporun içinde il adı yine doğru Türkçe yazımıyla görünür; yalnızca dosya adı sadeleşir. Önceki derslerde gördüğümüz Türkçe harf dönüşümü tuzağı, burada da geçerlidir: Python'un varsayılan küçük harf dönüşümü İ harfini doğru çevirmez. Sayılar varsayımdır.

Çözümlü örnek — Döngüyle çok sayıda rapor

Aynı raporu üç il için üretelim. Veri çerçevesindeki her il için veriyi süzer, sayıları hesaplar, grafiği çizer ve şablonu doldururuz.

• for il in veri["il"].unique():
• d = veri[veri["il"] == il].sort_values("yil")
• html = sablon.render(il=il, son=bicimle(d["issizlik"].iloc[-1]))
• open(f"{sade_ad(il)}.html", "w", encoding="utf-8").write(html)

Bu döngü çalıştırıldığında, klasörde üç il için birer HTML ve birer PNG dosyası oluştu. Ankara'nın raporu, 2024'te işsizlik oranının yüzde 10,1 olduğunu ve bir önceki yıla göre 0,6 puan azaldığını söylüyordu; rapor, üretildiği tarihi de otomatik olarak yazıyordu. 81 il için aynı döngü, hiçbir değişiklik yapılmadan 81 rapor üretir.

encoding="utf-8", Türkçe karakterlerin dosyaya doğru yazılmasını sağlar; bu parametre verilmezse, bazı işletim sistemlerinde varsayılan kodlama farklı olduğu için Türkçe harfler bozuk görünebilir. Döngüyle üretilen raporlarda bir ilin verisi eksikse, örneğin son yılın değeri yoksa, betik ya hata vermeli ya da raporda bunu açıkça belirtmelidir; önceki derslerde gördüğümüz doğrulama denetimleri, döngünün başına eklenmelidir. Sayılar varsayımdır.

Çözümlü örnek — Quarto ile parametreli rapor

Quarto, bir belgeyi hem metin hem kod içeren tek bir dosya olarak yazmayı ve farklı biçimlere derlemeyi sağlar. Python kullanan bir Quarto belgesinde, parametreler bir kod hücresiyle tanımlanır ve bu hücre parametreler etiketiyle işaretlenir. Quarto'nun belgelerine göre bu, Papermill adlı aracın kullandığı sözdizimiyle aynıdır.

• Parametre hücresi: #| tags: [parameters] satırından sonra il = "Ankara"
• Derleme: quarto render rapor.qmd -P il:Konya
• Biçim seçme: quarto render rapor.qmd --to pdf

Belge varsayılan olarak Ankara için derlenir; -P il:Konya ile derlendiğinde, Quarto parametre hücresinden sonra yeni değeri içeren bir hücre ekler ve bütün belge Konya için yeniden çalıştırılır. Belgede biçim belirtilmemişse çıktı HTML olur; --to ile PDF ya da Word seçilebilir. Çok sayıda parametre, bir YAML dosyasında tanımlanıp --execute-params ile de verilebilir.

Quarto belgesi derlenirken kod, temiz bir oturumda baştan sona çalıştırılır. Bu, etkileşimli not defterlerindeki gizli durum sorununa karşı doğal bir güvencedir: belgedeki sonuç, belgenin kendisinden üretilmiştir, oturumda kalmış bir değerden değil. Bu satırlar yazılırken Quarto yerel ortamda kurulu değildi; komutlar Quarto'nun resmî belgelerinden alındı.

Çözümlü örnek — R Markdown ile aynı iş

R Markdown ve R kullanan Quarto belgelerinde parametreler, belgenin başındaki ayar bölümünde params alanıyla tanımlanır ve belgenin içinde params listesiyle kullanılır.

• Ayar bölümü: params: altında il: "Ankara"
• Kodda kullanım: params$il
• Derleme: rmarkdown::render("rapor.Rmd", params = list(il = "Konya"))

R Markdown'ın başvuru kitabına göre parametreli bir rapor üç yolla derlenebilir: RStudio'daki derleme düğmesiyle, params argümanını alan rmarkdown::render fonksiyonuyla ya da parametre değerlerinin girildiği etkileşimli bir arayüzle. 81 il için rapor üretmek istendiğinde, rmarkdown::render bir döngü içinde her il için çağrılır ve output_file argümanıyla her raporun dosya adı ayrıca verilir.

İki araç arasındaki seçim, çoğu zaman kurumun kullandığı dile ve alışkanlıklara bağlıdır; ilke aynıdır. Belgenin metni, kodu ve parametreleri tek dosyada durur; derleme komutu, aynı dosyadan istenen sayıda rapor üretir. Bu satırlar, R bu dersin hazırlandığı makinede bulunmadığından çalıştırılmadı; paketin başvuru kitabından aktarıldı.

Çözümlü örnek — Gizli durumu görmek

Etkileşimli bir not defterinde şu sırayı düşünelim. Birinci hücrede enflasyon oranı 40 olarak tanımlanıyor. İkinci hücrede reel faiz, faizden enflasyon çıkarılarak hesaplanıyor. Araştırmacı birinci hücreyi değiştirip enflasyonu 30 yapıyor, ama ikinci hücreyi yeniden çalıştırmıyor. Ekranda reel faiz hâlâ eski enflasyonla hesaplanmış değeri gösteriyor.

Daha sinsi bir durumda, araştırmacı bir yardımcı değişkeni tanımlayan bir hücreyi siliyor; ama değişken bellekte kaldığı için, onu kullanan sonraki hücreler çalışmaya devam ediyor. Not defteri kaydedilip bir başkasına gönderildiğinde, o kişi dosyayı açıp baştan çalıştırdığında bir hata alır: değişken hiçbir yerde tanımlı değildir.

Pimentel ve arkadaşlarının 1,4 milyon not defteri üzerindeki çalışması, bu tür sorunların not defterlerinin tekrarlanabilirliğini etkileyen özellikler arasında olduğunu gösteriyor. Basit önlem, bir not defterini paylaşmadan ya da ondan bir sonuç raporlamadan önce, çekirdeği yeniden başlatıp bütün hücreleri baştan sona çalıştırmaktır. Quarto ve R Markdown gibi derleme araçları bunu her derlemede kendiliğinden yapar. Sayılar varsayımdır.

Çözümlü örnek — Tabloyu koddan üretmek

Raporlardaki tablolar da elle kopyalanmamalıdır. pandas kütüphanesinde bir veri çerçevesi, to_html yöntemiyle doğrudan bir HTML tablosuna dönüşür ve şablona yerleştirilebilir.

• tablo = d.to_html(index=False, decimal=",")
• tablo = d.to_html(index=False, float_format=lambda x: f"{x:.1f}".replace(".", ","))

Birinci satır, üç yıllık işsizlik verisini 10,4, 10,7 ve 10,1 olarak, yani virgülle yazdı. Ama bu satırı yazarken bir tuzağa düşüldü: basamak sayısını sabitlemek için float_format argümanı da eklendiğinde, tablo yeniden 10.4 biçimine döndü. pandas, float_format verildiğinde sayıyı bu fonksiyonla biçimlendirir ve decimal argümanını dikkate almaz. İkinci satır, virgülü biçimlendirme fonksiyonunun içine taşıyarak sorunu çözer.

Bu küçük olay, otomatik raporlamanın genel bir dersini taşır. Bir biçimlendirme seçeneğinin çalıştığını varsaymak yerine, üretilen çıktıya bir kez bakmak gerekir; bir kez doğru üretilen tablo, sonraki her derlemede doğru kalır. R tarafında aynı işi, knitr paketinin kable fonksiyonu görür. Sayılar varsayımdır.

Çözümlü örnek — Raporu damgalamak

Bir rapor okunduğunda, hangi veriyle ve ne zaman üretildiği anlaşılabilmelidir. Aynı betik farklı günlerde farklı veriyle çalışabildiği için, raporun sonuna üç bilgi yazmak iyi bir alışkanlıktır: derleme tarihi, verinin çekildiği tarih ve veri dosyasının parmak izi.

• import hashlib
• from datetime import date
• tarih = date.today().isoformat()
• iz = hashlib.sha256(open("veri.csv", "rb").read()).hexdigest()[:12]

hashlib modülünün sha256 fonksiyonu, bir dosyanın içeriğinden kısa bir özet üretir. Dosyada tek bir rakam değişse bile bu özet tamamen farklı olur. Üç yıllık küçük bir örnek veri için bu dersteki özet 564b82303c22 ile başladı. Raporun altında bu on iki karakter yazılıysa, iki okur ellerindeki raporların aynı veriden üretilip üretilmediğini tek bakışta anlayabilir.

Resmî istatistikler geriye dönük olarak düzeltildiğinde, bu damga daha da önemli hâle gelir. Geçen ay yayımlanan rapordaki işsizlik oranı ile bu ayki rapordaki aynı yılın oranı farklıysa, damga farkın hesaplamadan değil veri revizyonundan kaynaklandığını gösterir. Veri sürümünü kayıt altına almak, bir sonraki derste göreceğimiz tekrarlanabilir araştırmanın da temel adımlarından biridir. Sayılar varsayımdır.

Modelin sınırları

Otomatik raporlama, raporun sayılarını koda bağlar, ama kodun kendisindeki hataları önlemez: yanlış bir formül, her derlemede aynı yanlış sonucu tutarlı biçimde üretir. Bu yüzden önceki derslerde gördüğümüz doğrulama denetimleri ve sonuçların bilinen değerlerle karşılaştırılması, otomatik bir raporun da parçası olmalıdır.

Parametreli raporların kendine özgü bir riski de vardır. 81 il için aynı şablon çalıştırıldığında, nüfusu küçük bir ilde örneklem hatası büyük olduğu için yıldan yıla 1 puanlık bir oynama gürültüden ibaret olabilir; oysa şablon, bu değişimi büyük bir ilinkiyle aynı cümleyle «arttı» diye yazar. Bu yüzden şablona, tahminin güven aralığını ya da örneklem büyüklüğünü de yazdıran, gerekirse değişimin istatistiksel olarak ayırt edilemediğini belirten bir kural eklemek gerekir. Toplu üretilen raporlar ayrıca kimse tarafından tek tek okunmadan yayımlanma eğilimindedir; en az birkaç tanesini her dönem baştan sona okumak, şablondaki hataları erken yakalar. Seçilecek raporlar her dönem değiştirilmeli; özellikle verisi eksik, çok küçük ya da bir önceki döneme göre olağandışı değişmiş iller öncelikle okunmalıdır.

Dinamik belgeler ayrıca yorumu otomatikleştirmez. Bu dersteki gibi bir cümle, farkın işaretine göre «arttı» ya da «azaldı» yazabilir; ama bir değişimin anlamlı olup olmadığına, neden olduğuna ya da ne anlama geldiğine karar vermek, raporu yazan iktisatçının işidir. Python örnekleri jinja2 ve matplotlib ile çalıştırılarak sınandı; Quarto ve R Markdown komutları, bu ortamda kurulu olmadıkları için resmî belgelerine göre yazıldı.

Uygulama

Özet kartı

1. Okuryazar programlama, Knuth'un 1984'te önerdiği, açıklama ile kodu tek belgede birleştiren yaklaşımdır; Leisch'in 2002'deki Sweave'i bu fikri istatistik raporlarına taşıdı ve bugünkü R Markdown, Jupyter ve Quarto araçları bu çizginin devamıdır.
2. Dinamik belgede metindeki sayılar, tablolar ve grafikler koddan üretilir; veri değiştiğinde rapor tek komutla yenilenir ve fiil seçimi gibi küçük ayrıntılar bile hesaplanan değere bağlanabilir.
3. Şablon, raporun biçimini içeriğinden ayırır; parametreli rapor, aynı belgeyi il, dönem ya da senaryo gibi girdilerle çoğaltır. Türkçe raporda ondalık virgül ve Türkçe karakterler kodda açıkça ele alınmalıdır.
4. Nuijten ve arkadaşları, psikoloji makalelerinin yarısında test istatistiğiyle tutarsız en az bir p değeri buldu; sonuçları elle aktarmak sistematik hatalara açıktır.
5. Not defterleri gizli durum biriktirebilir; Pimentel ve arkadaşlarının 1,4 milyon not defteri üzerindeki çalışması, tekrarlanabilirliği bozan uygulamaları inceledi. Temiz oturumda baştan derleme ve rapora veri damgası eklemek temel önlemlerdir.

Kavram sözlüğü

Kendini sına

1. (Çıktı 1) Dinamik belge ile şablon arasındaki farkı açıkla. Parametreli bir rapor bu iki kavramı nasıl birleştirir?
2. (Çıktı 2) Bir raporda, metindeki bir sayı ile tablodaki aynı sayının farklı çıkması hangi iş akışında olur? Dinamik belge bu hatayı nasıl önler ve hangi hatayı önleyemez?
3. (Çıktı 2) Bir not defterinde, birinci hücrede faiz 45, ikinci hücrede enflasyon 38 olarak tanımlanıyor; üçüncü hücre reel faizi faizden enflasyonu çıkararak hesaplıyor ve 7 gösteriyor. Araştırmacı ardından ikinci hücreyi değiştirip enflasyonu 33 yapıyor ve yalnızca bu hücreyi çalıştırıyor. Ekranda üçüncü hücrenin çıktısı ne gösterir, belge baştan derlendiğinde ne gösterir?
4. (Çıktı 3) Bir ilin son iki yıllık işsizlik oranları 11,3 ve 11,8'dir. Python'da, farkın işaretine göre fiili seçen ve sayıları Türkçe ondalık ayraçla yazan bir cümle üreten satırları yaz. Cümle ne der?
5. (Çıktı 3) Bir Quarto belgesini Konya için PDF olarak derleyen komutu yaz. Python kullanan bir belgede il parametresi nasıl tanımlanır; R Markdown'da aynı parametre kodda nasıl okunur?
6. (Çıktı 4) Bir kurum, «raporlarımızı artık not defterlerinde hazırlıyoruz, bu yüzden hepsi tekrarlanabilir» diyor. Pimentel ve arkadaşlarının çalışmasını kullanarak bu iddiayı değerlendir ve iddiayı sınamak için ne önerirdin?

Cevaplar

1. Dinamik belge, metni, kodu ve kodun çıktılarını birlikte içeren ve her derlemede yeniden hesaplanan belgedir; şablon ise sabit metin ile değerlerle doldurulacak yer tutuculardan oluşan bir kalıptır. Parametreli rapor, dinamik belgeyi bir şablon gibi kullanır: belgenin kodu ve metni sabittir, il ya da dönem gibi parametreler her derlemede değişir ve aynı belgeden farklı raporlar üretilir.
2. Bu hata, analiz yeniden çalıştırıldığında tablonun güncellendiği ama metindeki sayının elle yazıldığı için eski kaldığı iş akışında olur. Dinamik belgede her iki sayı da aynı koddan çekildiği için birbirinden ayrılamaz. Ama dinamik belge, kodun kendisindeki bir hatayı önlemez: yanlış bir formül, her derlemede aynı yanlış sonucu tutarlı biçimde üretir.
3. Üçüncü hücre yeniden çalıştırılmadığı için ekranda hâlâ 45 − 38 = 7 görünür; bu, belgenin artık gösterdiği enflasyon değeriyle tutarsızdır. Belge temiz bir oturumda baştan derlendiğinde reel faiz 45 − 33 = 12 olarak hesaplanır. Aradaki fark, gizli durumun somut bir örneğidir.
4. son = 11.8, fark = son − 11.3 = 0.5; cumle = f"İşsizlik oranı yüzde {son:.1f} oldu; bir önceki yıla göre {abs(fark):.1f} puan {'arttı' if fark > 0 else 'azaldı'}.".replace(".", ",") yazılırsa cümlenin sonundaki nokta da virgüle döner; bu yüzden yalnızca sayıları biçimlendiren ayrı bir fonksiyon kullanılmalıdır. Doğru kurulmuş cümle: «İşsizlik oranı yüzde 11,8 oldu; bir önceki yıla göre 0,5 puan arttı.» Fark 0'dan büyük olduğu için fiil «arttı» seçilir.
5. Komut: quarto render rapor.qmd -P il:Konya --to pdf. Python kullanan bir Quarto belgesinde parametre, parameters etiketiyle işaretlenmiş bir kod hücresinde il = "Ankara" gibi varsayılan bir değerle tanımlanır. R Markdown'da parametre, belgenin başındaki ayar bölümünde params altında tanımlanır ve kodda params$il ile okunur.
6. Not defterleri kendiliğinden tekrarlanabilir değildir. Pimentel ve arkadaşları, not defterlerinin kullanılış biçiminin beklenmedik davranışlara ve kötü kodlama alışkanlıklarına yol açabildiğini, sonuçlarının yeniden üretilmesinin zor olabileceğini tartıştı ve 1,4 milyon not defterinde tekrarlanabilirliği etkileyen özellikleri inceledi. İddiayı sınamak için her not defteri temiz bir oturumda, çekirdek yeniden başlatılarak baştan sona çalıştırılmalı ve çıktılar yayımlanan raporla karşılaştırılmalıdır; kullanılan paketlerin sürümleri ve veri dosyalarının parmak izleri de kayıt altına alınmalıdır.

İleri okuma

• Donald E. Knuth (1984). «Literate Programming». The Computer Journal 27(2). Açıklama ile kodu tek belgede birleştirme fikrinin ilk sunumu.
• Friedrich Leisch (2002). «Sweave: Dynamic Generation of Statistical Reports Using Literate Data Analysis». Compstat 2002 — Proceedings in Computational Statistics. Okuryazar programlamayı istatistik raporlarına taşıyan araç.
• Michèle B. Nuijten ve diğerleri (2016). «The Prevalence of Statistical Reporting Errors in Psychology (1985–2013)». Behavior Research Methods 48(4). Elle aktarılan sonuçlardaki tutarsızlıkların ölçülmesi.
• João Felipe Pimentel ve diğerleri (2019). «A Large-Scale Study About Quality and Reproducibility of Jupyter Notebooks». MSR 2019. Not defterlerinin tekrarlanabilirliğine dair geniş ölçekli bir inceleme.

Sonraki derse köprü

Bu derste bir raporu kendi bilgisayarımızda, tek komutla, her seferinde aynı biçimde yeniden üretmeyi öğrendik. Ama bu komut başka bir bilgisayarda, başka bir araştırmacının elinde ya da beş yıl sonra aynı sonucu verecek mi? Paketlerin sürümleri değişir, veri kaynağı revize edilir, klasör yolları başka makinede bulunmaz. Sıradaki ders tekrarlanabilir araştırmayı ele alıyor: bir analizin kodunun, verisinin ve çalışma ortamının, bir başkasının aynı sonuçları yeniden elde edebileceği biçimde nasıl paketlendiğini, sürüm denetiminin bu işteki yerini ve dergilerin istediği replikasyon paketlerinin pratikte ne sıklıkla gerçekten çalıştığını göreceğiz.