Doğrulama sistemi

Sorun

Bir kütüphane "Ateşman okunabilirlik formülünü uyguluyorum" diyebilir. Siz bunu nasıl kontrol edersiniz? Kaynağı bulup formülü okuyarak ve kodu inceleyerek. Bu, kullanıcıdan beklenmeyecek kadar uzun bir iş.

Bu kütüphane farklı bir şey yapar: kaynağın yayımladığı sayıyı alır, aynı girdiyi kendi koduna verir, ikisini yan yana basar.

Sonuç: doğrulama raporu (English).

Doğrulamanın iki katmanı

1. Formül eşdeğerliği

Künyesi olan bütün özniteliklerin formülü kaynağıyla karşılaştırılarak kontrol edildi; kaynak çoğunlukla birincil, 15 künyede ikincildir (as cited in). Her künye, formülün kaynakta geçtiği sayfayı ve numarasını gösterir (örneğin p.327, eq. (5)). Testler formülü ve sınır durumlarını sınar. Künyesi olmayan 11 öznitelik saf tanımdır; karşılaştırılacak bir kaynakları yoktur.

2. Kaynak sayısı doğrulaması

Birinci katmanın üstüne eklenen ek bir kontroldür: kaynağın yayımladığı bir sayı bulunur ve bizim çıktımızla karşılaştırılır. 151 adayın 48'i bu katmanda doğrulanmıştır. Bu sayfanın geri kalanı bu katmanı anlatır.

İkinci katman birincinin koşulu değildir. 🔍 açık işaretli bir özniteliğin formülü şüpheli değildir; karşılaştırılacak yayımlanmış bir sayı bulunamamıştır.

Önce: her öznitelik doğrulanamaz

Bu ayrım raporun en önemli parçası. 208 özniteliğin bir kısmı, tanımı gereği doğrulama adayı bile değildir:

	Neden aday değil
⚪ kaynak yok	Saf tanım. punct_dash_ratio "tire / bütün noktalama işaretleri" demektir; aranacak bir literatür sayısı yoktur.
⚫ etiket şeması	Bir ölçü değil, dış bir şemanın kategorisini sayıyor. pos_noun_ratio → UD, zeyrek_case_loc_ratio → Zeyrek. Şema kategori tanımlar, ölçüm yayımlamaz — de Marneffe'in makalesi "case_loc_ratio = 0,07" diye bir sayı basmaz, basamaz.
🔧 türev	Formül bir kaynaktan, uygulaması bizden. sent_len_entropy Shannon'ın entropisidir ama tümce uzunluklarına uygulanması bizim; long_sent_ratio'nun eşiği kendi kalibrasyonumuzdan gelir. Bu ölçüleri kimse yayımlamadı — kendi kalibrasyonumuza karşı sınamak kendi cevabımıza bakmak olurdu.

Türkçe tarafında 82 satır bu üçünden biri. Geriye 151 doğrulama adayı kalıyor. Gerçek payda budur.

Aday satırların dört durumu

	Anlamı
✅ birebir	Kaynağın yayımladığı sayıyla tolerans içinde aynı. Küçük bir farkın nedeni biliniyorsa satırın altında not olarak yazılır.
🟡 belgelenmiş sapma	Fark toleransın dışında ve nedeni yazılı — kaynağın ara değeri yuvarlaması, kaynağın sayılarının elle üretilmiş olması gibi.
🔍 açık	Kaynak formülü veriyor ama uygulanmış bir örnek vermiyor. Doğrulanabilir, henüz doğrulanmadı.
❌ uyuşmazlık	Açıklanmamış fark. Yayın kapısı: bir tane bile varsa sürüm çıkmaz.

Bugünkü durum: 151 adayın 48'i doğrulanmış (46 ✅ + 2 🟡), 103'ü 🔍 açık.

Tolerans yayımlanan değerin %1'i (göreli). Kaynaklar ara değerleri yuvarlayarak bastığı için mutlak eşitlik beklenmez.

Toleransı aşan fark otomatik olarak ❌ değildir. Belirleyici olan farkın büyüklüğü değil, nedeninin bilinip bilinmediğidir. Nedeni ölçülmüş ve yazılmışsa satır 🟡 olur; yazılmamışsa ❌ olur ve sürüm çıkmaz.

Bu bir kaçış kapısı değil. Gerekçe "herhalde yuvarlamadır" cinsinden bir tahmin olamaz; farkın nereden geldiğini gösteren bir ölçüm olmak zorundadır. Aşağıdaki Kincaid örneği bunun nasıl göründüğünü anlatıyor.

İki kanıt türü

Bu ayrım önemli ve raporda ayrı sütunda durur.

Uçtan uca, kaynağın kendi metnini boru hattından geçirir. Yani tokenizasyon, heceleme ve tümce bölme de sınanır. En güçlü kanıttır: bir sayı tutuyorsa yalnız formül değil, ona giden bütün adımlar doğrudur.

Formül, fonksiyona girdileri doğrudan verir — örneğin "hece/sözcük 2,2 ve sözcük/tümce 4". Formülü ve katsayıları doğrular, boru hattını doğrulamaz. Kaynak bir metin yayımlamamışsa elde olan budur.

Neden 103 satır hâlâ 🔍 açık

Kaynak formülü yayımlamış ama o formülü bir metne uygulayıp sonucu basmamış. Bu, nicel dilbilim literatüründe olağandır. Yule (1944) K'yı tanımlar, bir romanda K'nın kaç çıktığını basmaz. Böyle bir sayı olmayınca karşılaştıracak bir şey de olmaz.

Bu satırlar test edilmiyor demek değildir. Formül ve sınır durumları kendi test dosyalarında sınanır. Rapor yalnız kaynağın sayısıyla karşılaştırmayı takip eder.

Hangi grupların doğrulandığı türle ilgili, tesadüf değil:

Grup	✅	🟡	🔍
frequency_structure	22	0	2
readability	13	1	2
lexical	6	1	33
phonetic	0	0	12

Okunabilirlik formülleri pratik araçlardır — yazarları formülü örnek metinle birlikte yayımlar, çünkü amaç başkasının uygulayabilmesidir. Sözcüksel zenginlik ölçüleri ise matematiksel tanımlardır; yazarı formülü verir, örneği okuyucuya bırakır.

🔍 nasıl ✅ olur

Kaynağın yayımladığı bir sayı bulunması gerekir. Üç örnek:

QUITA kılavuzu — tek seferde on dört öznitelik. Kılavuz on dört göstergeyi iki örnek metin üzerinde baştan sona hesaplayıp sonucu basıyor, üstelik o metinlerin sıklık dağılımını da yayımlıyor (§15.3). Dağılım bu göstergelerin tek girdisi olduğu için karşılaştırma doğrudan yapılabiliyor:

	QUITA	bizim
repeat_rate Text 2	0,02147	0,02147
gini_coef Text 1	0,3045	0,30449
curve_length Text 2	134,2787	134,27870
entropy Text 1	6,438043 bit = 4,462511 nat	4,462512

QUITA entropiyi bit cinsinden basıyor. Bu kütüphanedeki bütün logaritmalar doğal logaritma olduğu için yayımlanan değer karşılaştırmadan önce nata çevriliyor (× ln 2).

Yirmi sekiz karşılaştırmanın yirmi yedisi tolerans içinde (en büyük göreli fark %0,1'in altında; çoğunda sapma sıfır). Kalan bir tanesinde sapma 0,009, yani yayımlanan değerin %1,5'i; %1 toleransın dışında kaldığı için satır 🟡 ve nedeni belli: ttr Text 2 için kaynak 0,590 basmış, ama kendi verdiği sayıları bölünce 121 ÷ 202 = 0,599 çıkıyor. Yayımlanmış sayıda basım hatası var; bizim değerimiz aritmetik olarak doğru olan.

mtld — Bu ölçü metni tarayıp TTR 0,72'nin altına her düştüğünde bir "faktör" sayar; artan kısım kesirli bir faktör olarak eklenir. McCarthy & Jarvis (2010) s.385 tam da o kesri örnekliyor: ".887 forms 40,4% of the range between 1.00 and the full factor of .720." Aynı diziyi üretim kodundan geçirdik, kesirli faktör 0,4043 çıktı — kaynağın bastığı %40,4 ile aynı.

coleman_liau — Makale ölçüyü iki adımda tanımlıyor: önce metnin cloze yüzdesi kestiriliyor, sonra o yüzde sınıf düzeyine çevriliyor. Uygulamada bu iki adım tek formülde birleştirilir; literatürde standart olan kullanım da budur. İki adımı ayrı ayrı yürütmekle tek formülü kullanmanın aynı sonucu verdiğini ölçtük: 7,7041 ve 7,7046. Aradaki 0,0005 kaynağın ara değeri yuvarlamasından geliyor.

🟡 nasıl görünür — Kincaid örneği

İngilizce raporda iki okunabilirlik özniteliği, ari ve flesch_kincaid_grade, 🟡 durumunda. ari Türkçe şemada da var ve aynı karşılaştırmayla orada da 🟡; flesch_kincaid_grade yalnız İngilizcede var. Üç soruyla anlatılabilir.

Ne karşılaştırıldı? Bu iki ölçünün kaynağı 1975 tarihli bir ABD Donanması teknik raporu. Rapor yalnız formülü vermiyor: ekinde eğitim malzemesinden alınmış 18 gerçek metin parçası, tablolarında da o 18 parça için kendi hesapladığı ARI ve FKGL değerleri var. Yani kaynak hem girdiyi hem cevabı basmış — doğrulama için elde olabilecek en iyi malzeme. 18 parçanın hepsini boru hattımızdan geçirdik.

Sapma ne kadar? Parça başına mutlak farkların ortalaması 0,54 ARI puanı. Raporda görünen −0,537 başka bir sayıdır: kaynağın Tablo 1'de bastığı ortalama (12,3) ile bizim 18 parçalık ortalamamız arasındaki fark. Yayımlanan değere oranı yaklaşık %4,4 (0,537 ÷ 12,3); %1 toleransın çok üstünde, yani ✅ olamıyor.

Neden ❌ değil? Çünkü sapmanın nereden geldiğini tahmin etmedik, ölçtük. ARI'nin girdisi "sözcük başına vuruş" (boşluk dışı her karakter: harf, rakam ve noktalama), ve 1975'te bu sayım elle yapılıyordu: daktiloya takılı mekanik bir sayaçla. Farkın oradan gelip gelmediğini şöyle sınadık: kaynağın bastığı sayıyı verecek vuruş miktarı bizimkinin kaç katı olmalıydı? 18 parçanın 17'sinde cevap 0,996–1,041 katı — yani parça başına birkaç karakter. Elle sayımda beklenen büyüklük bu.

Kaynak parça başlıklarını saymamış: başlıkları saymak 18 parçanın hepsinde sonucu kötüleştiriyor. FKGL'nin sapması ise tek bir parçadan geliyor (12 numaralı parça).

Parça bazında bütün sayılar — vuruş ve sözcük sayıları dâhil — raporun sonundaki ek tabloda duruyor, farkın hangi girdiden geldiği görülebilsin diye.

İşte 🟡'nin anlamı bu: fark var, ölçtük, nereden geldiğini biliyoruz.

Rapor testlerden üretilir

docs/dogrulama-raporu.md elle yazılmaz. scripts/generate_verification_report.py üretir ve tests/test_kaynak_esligi.py aynı karşılaştırma tablosunu okur. Yani rapor ile testler ayrışamaz; rapor bayatsa test düşer.

Kapsam listesi de kayıt defterinden gelir — bir öznitelik eklenip rapora girmemesi mümkün değil.

⚪ ve 🔧 için tanımı biz veriyoruz

Bu iki durumda ölçünün tanımını yöntem bölümünüz için sıfırdan yazmanız gerekmiyor. Kayıt defteri her öznitelik için alıntılanabilir bir tanım tutuyor:

tlf.describe_feature("sent_len_entropy")["formula"]

'Shannon entropy (nats) of the distribution of words per sentence'

Örnek olarak beşi:

Öznitelik	Tanım	Kaynağa ait olan
punct_entropy	on noktalama türünün dağılımının Shannon entropisi (nat)	entropi formülü — Shannon (1948)
sent_len_entropy	tümce başına sözcük dağılımının Shannon entropisi (nat)	entropi formülü — Shannon (1948)
short_sent_ratio	short_sent_threshold sözcükten az tümce / tümce	eşik değeri — eşik kalibrasyonu
long_sent_ratio	long_sent_threshold sözcükten çok tümce / tümce	eşik değeri — eşik kalibrasyonu
polysyllabic_word_ratio	3+ heceli sözcük / hecelenebilir sözcük	çok heceli tanımı — McLaughlin (1969) s.641

Formülün kaynağını verin, ama ölçüyü o kaynağın ölçüsü gibi göstermeyin.

• ✗ "Shannon (1948) sent_len_entropy ölçüsü"
• ✓ "Shannon (1948) entropisinin tümce uzunluğu dağılımına uygulanması (turkish-linguistic-features'ın tanımı)"

Birinci yazım okuyucuya, kaynakta aranınca bulunacak bir ölçü olduğunu ima ediyor. Shannon entropiyi tanımladı, tümce uzunluklarına uygulamadı.