1. Şablonların Ortak Düzeni
Kaynak: pro/kod/sablon.py (ayrıştırma, form değerleri, doğrulama), pro/kod/yurutucu.py (çalıştırma), pro/kod/r_yardim.R (R yardımcısı), pro/mq/cikti.py (Python mq nesnesi), pro/kod/aktarim.py (veri aktarımı), pro/gui/kod_panel.py (Kod paneli, tohum alanı)
Bu bölüm, sonraki her bölümün dayandığı ortak düzeni bir kez anlatır: şablon dosyasının yapısı, parametre formunun nasıl kurulup denetlendiği, verinin ve parametrelerin koda nasıl ulaştığı, çıktının nasıl toplandığı. Şablon bölümleri bu konuları yinelemez, buraya gönderme yapar.
1.1 Şablon dosyası
Bir şablon tek bir .R ya da .py dosyasıdır. Dosyanın başında yorum satırlarına gömülü bir TOML üstbilgisi, ardından çalıştırılacak kod bulunur (sablon.py:1–66). Üstbilgi # /// mq-sablon satırıyla açılır, # /// ile kapanır.
| Üstbilgi alanı | Anlamı |
|---|---|
kimlik, surum |
Şablonun kalıcı adı ve sürümü; çalıştırma kaydında kimlik@surum biçiminde tutulur. |
dil, kategori |
r ya da python; kütüphanedeki klasör. |
baslik, aciklama |
Türkçe, İngilizce ve İspanyolca metin; formun başlığı ve açıklaması. |
ornek_veri, ornek_param |
_ornek/ altındaki veri dosyası ve "Örnek veriyi aç" düğmesinin forma yazdığı değerler. |
[[param]] |
Formdaki her alan için bir blok (aşağıda). |
Şablonun yanında aynı adlı, yalnız karşılaştırma için gösterilen eşdeğer bir yan dosya ve yorum çevirisi dosyası (*.ceviri.json) bulunabilir; bunlar çalıştırılmaz ve bu kitabın konusu değildir.
1.2 Parametre formu ve denetimi
Her [[param]] bloğu formda bir alan kurar. Alan, bolum değerine göre Değişkenler, Model, Seçenekler, Gelişmiş ya da Çıktı sekmesine yerleşir (sablon.py:88).
Tür (tur) |
Formdaki karşılığı | P'deki değer |
|---|---|---|
sayisal_sutun |
Sayısal sütun listesi | sütun adı (metin) |
kategorik_sutun, sutun |
Tüm sütunlar | sütun adı |
sutunlar |
İşaretleme listesi (en_az_sayi, sayisal) |
sütun adları listesi |
tamsayi, ondalik |
Sayı kutusu (en_az, en_cok) |
tamsayı / ondalık |
secim |
Açılır liste (secenekler) |
seçilen deger |
metin |
Metin kutusu (en çok 2000 karakter) | metin |
onay |
Onay kutusu | mantıksal |
Varsayılanlar (sablon.py:795–828): üstbilgideki varsayilan kullanılır; sütun alanında varsayılan yoksa uygun ilk sütun (sayısal alan için ilk sayısal sütun) önerilir. Denetim (sablon.py:831–931): çalıştırmadan önce her değer türüne, aralığına ve veride bulunup bulunmadığına göre denetlenir; bir hata varsa çalıştırma başlamaz ve çevrilmiş ileti gösterilir. Aynı denetim yürütücüde bir kez daha yapılır (yurutucu.py:321–339, 366–369). Bu denetim yalnız biçimseldir; yöntemin istediği koşullar (en az kaç düzey, pozitif doz vb.) şablonun kendi mq_hata / mq.hata satırlarında denetlenir ve her bölümün "Şablonun girdileri" kısmında listelenir.
sayisal_sutun alanı ve sayisal = true olan sutunlar alanı sayısal roldür: listede yalnız pandas türü sayısal olan sütunlar görünür ve metin türündeki bir sütun bu role atanırsa çalıştırma "sayısal bir sütun değil" iletisiyle başlamaz. Sayısal role atanan sütunun koda nasıl ulaştığı 1.3'te anlatılır.
1.3 Veri ve parametrelerin koda ulaşması
R şablonları ayrı bir süreçte, Rscript --no-init-file calistir.R <iş klasörü> komutuyla çalışır (yurutucu.py:74–84). calistir.R, r_yardim.R'nin iş klasörüne kopyasıdır. Etkin veri düz metin olarak aktarılır ve R tarafında sütun türleriyle yeniden kurulur (r_yardim.R:96–124); parametreler P listesine (73–94), veri df'ye (689) yazılır. Çalıştırmanın tohumu mq_tohum değişkenine konur (311–313) ve kullanıcı kodundan önce set.seed(mq_tohum) çağrılır (688).
Python şablonları gömülü işçide çalışır; ad alanında df (pandas veri çerçevesi), P (sözlük), np, pd ve mq hazırdır (isci.py:283–299). Kullanıcı kendi Python yorumlayıcısını seçmişse aynı ad alanı harici_mq.py ile kurulur. Tohum mq.seed özelliğindedir; random ve numpy.random üreteçleri kullanıcı kodundan önce bu tohumla kurulur (isci.py:301–304).
Sayısal rol aktarımı. Veri sekmesinde türü "kategorik" olan bir sütun R'ye factor olarak gider. Aynı sütun şablonda sayısal bir role atanmışsa bu istenen şey değildir: as.numeric(factor) değerleri değil düzeylerin sıra numaralarını döndürür (notları 1, 3 ve 9 olan bir sütun 1, 2 ve 3 olur). Bu nedenle yalnız sayısal rollere atanmış sütun, Veri sekmesindeki türü ne olursa olsun R'ye ve harici Python'a sayı olarak aktarılır (sablon.py:765–792, is_tanimi.py:185–195, aktarim.py:141–151). Aynı sütun aynı çalıştırmada sayısal olmayan bir sütun rolüne de (kategorik_sutun, sutun, sayisal koşulu taşımayan sutunlar) atanmışsa Veri sekmesindeki türü korunur; hem sayısal hem kategorik değişken kabul eden listelerde kullanıcının tür seçimi geçerlidir. Gömülü Python'da df pandas türünü taşıdığından bu ayrım yoktur. mq_turler / mq.turler her durumda Veri sekmesindeki türü gösterir.
Tohum. Kod panelinin araç çubuğunda isteğe bağlı bir Tohum alanı vardır (kod_panel.py:223–233). Alan boşsa her çalıştırmaya 1 ile 2^{31}-2 arasında yeni bir tohum atanır (betik_adimi.py:50–52); alana 0 ile 2 147 483 647 arasında bir tam sayı yazılmışsa o tohum kullanılır, geçersiz bir değer çalıştırmayı başlatmaz (kod_panel.py:552–572, betik_adimi.py:58–70). Kullanılan tohum çalıştırma başlarken konsola (kod_panel.py:591), sonuç kartının künyesine "Tohum: …" satırı olarak (kart.py:101–103) ve betik adımına yazılır. Aynı veri, aynı kod ve aynı tohumla sonuç yinelenir: künyedeki tohum alana girilerek ya da kayıtlı betik yeniden oynatılarak. Şablonun kendi formunda ayrıca bir tohum alanı varsa ya da şablon tohumu kodda sabitliyorsa bu, ilgili bölümde belirtilir.
Kategorik düzeylerin sırası
Veri sekmesi sütun türlerini yüklemede belirler (core/data_loader.py:801–802). "Kategorik" sayılan bir sütunun düzeyleri R'ye MerQuR+'ın düzey sırası kuralıyla aktarılır (aktarim.py:78–83, core/cat_order.py): kullanıcı bir sıra tanımladıysa o sıra; etiketlerin hepsi sayıysa sayısal sıra; aksi hâlde verideki ilk görülme sırası. Alfabetik sıra kendiliğinden kullanılmaz. R tarafında factor(..., levels = …) bu sırayla kurulur (r_yardim.R:119) ve şablondaki factor() çağrısı sırayı değiştirmez. Bu nedenle "ilk düzey", "referans düzey" ya da "katsayıları düzey sırasıyla girin" diyen her seçenek, verinin satır sırasına bağlıdır. Sıra bölümlerde örnek veriyle birlikte açıkça yazılır. Sayı değerli bir sütun kategorik yapıldığında düzey adları sayının yalın yazımıdır: tam sayı değerli ondalıklı sütunda (boş hücre içerdiği için ondalıklı okunan kimlik ya da kod sütunu) 570, 570.0 değil (aktarim.py:52–59).
Bu kural yalnız türü "kategorik" olan sütunlar içindir. Veri sekmesinin ikili saydığı iki düzeyli metin sütunu R'ye metin olarak gider (aktarim.py:62–91); şablondaki factor() çağrısı böyle bir sütunun düzeylerini alfabetik sıralar ve alfabetik ilk düzey başvuru olur (evet/hayır sütununda evet, no/yes sütununda no). Aynı veride üç düzeyli bir sütunun başvurusu ilk görülen düzey, iki düzeyli metin sütununun başvurusu alfabetik ilk düzeydir. Şablonlar başvuru düzeyini mq_duzey_notu() ile çıktıya yazabilir (1.5).
1.4 Çıktı işlevleri
| R | Python | Ne yapar |
|---|---|---|
mq_tablo() |
mq.tablo() |
Sonuçlar sekmesine adlandırılmış tablo; tam hassasiyetle saklanır. R'de en çok 12 tablo, 5000 satır, 200 sütun (r_yardim.R:29–31, 216–229). |
mq_metin(), print |
mq.metin(), print |
Konsol metni. |
mq_sekil() |
mq.sekil() |
Açık grafiği başlığıyla kaydeder. |
mq_hata() |
mq.hata() |
Çalıştırmayı durdurur, yalnız iletiyi gösterir. |
mq_sayi() |
mq.sayi() |
Arayüz diline göre sayı metni (Türkçede ondalık virgül). |
1.5 Dönüşüm yardımcıları
Şablonların veri sütunlarını okurken kullandığı ortak yardımcılar aşağıdadır. İletileri arayüz diline göre kendileri üretir.
| R | Python | Ne yapar |
|---|---|---|
mq_sayisal(x, ad) |
mq.sayisal(x, ad) |
Sütunun sayı değerleri (r_yardim.R:331–352, cikti.py:238–265). Sayısal sütun olduğu gibi döner; kategorik ya da metin sütunda etiketin sayı karşılığı alınır (düzey sıra numarası değil). Boş hücre, NA ve NaN eksik sayılır. Sayıya çevrilemeyen bir değer varsa çalıştırma, sütun adını ve örnek değerleri veren iletiyle durur. |
mq_kimlik(x) |
mq.kimlik(x) |
Kimlik sütununu tek biçimli metne çevirir (r_yardim.R:359–376, cikti.py:293–305): sayıda bilimsel gösterim ve .0 eki yoktur (100000, 1e+05 değil), metinde baş ve son boşluk kırpılır, boş metin eksiktir, 570.0 yazımı 570 olur. Aynı kimlik tam sayı, ondalıklı, kategorik ya da metin türündeki sütunlarda aynı metni verir; soy kütüğünde birey, baba ve ana sütunları bu yolla eşleşir. Baştaki sıfırlar (007) korunur. |
mq_tohum |
mq.seed |
Çalıştırmanın tohumu (1.3). |
mq_genotip(v, ad, ayirici) |
— | Genetik şablonlarının ortak genotip ayrıştırıcısı (r_yardim.R:474–531); kuralı aşağıdadır. |
mq_genotip_notu() |
— | Okuma sırasında eksik sayılan genotiplerin dökümünü konsola yazar (r_yardim.R:423–464): kaç lokusta kaç genotipin boş hücre ya da eksik kodu yüzünden eksik sayıldığı; genotiplerinin yarısından çoğu eksik kodu taşıyan lokuslar ayrıca adlarıyla uyarılır. |
mq_duzey_notu(x, ad) |
— | Bir etken sütununun düzey sırasını ve başvuru (ilk) düzeyini tek satırla yazar (r_yardim.R:535–550): "mined: düzey sırası alfabetik (no, yes); ilk düzey başvurudur." Hesabı değiştirmez. |
Genotip okuma kuralı. Bir lokus sütunu ya sayısaldır ya metindir. Sayısal sütunda yalnız 0, 1 ve 2 kabul edilir (B alelinin sayısı; A/A, A/B, B/B). Metin sütunda genotip alel1/alel2 biçimindedir (ayırıcı formdan seçilir). Eksik genotip boş hücredir ya da şu kodlardan biridir: NA, na, 0, 00, 000, ?, -, ., -9 (r_yardim.R:389, 473). Ayırıcılı yazımda iki alelin ikisi de eksik kodu olmalıdır (0/0, -9/-9). Alellerinden yalnız biri eksik kodu olan bir genotip (0/1, A/?) görülürse çalıştırma durur ve lokusu, genotip sayısını ve örnek genotipi veren bir ileti gösterir. Gerekçe: "0" bazı veri biçimlerinde eksik kodu, bazılarında (alelleri 0 ve 1 diye adlandıran kodlama) gerçek bir alelin adıdır; ikisi veriden kesin ayırt edilemez ve yanlış seçim genotiplerin büyük bölümünü sessizce atar. Alellerinden biri gerçekten "0" adını taşıyan veri, alel başka bir adla yeniden kodlanarak (0 → A, 1 → B) çözümlenir; sayısal 0/1/2 sütunu bu kuralın dışındadır. Ayırıcı içermeyen ya da ikiden çok alel taşıyan genotip ve bütün genotipleri eksik olan lokus da çalıştırmayı durdurur.
Tablolar tam hassasiyetle saklanır; metin satırları ise mq_sayi ile yuvarlanmış yazılır. Bu kitaptaki doğrulama tablolarında MerQuR+ sütunu her zaman şablonun tablosundan okunmuştur. Her çalıştırmada yüklenen paketler, sürümleri ve atıfları ayrıca kaydedilir (yazılım kaydı).
1.6 Bu kitapta doğrulama
Her bölümde şablon, örnek verisinde ve örnek ayarında MerQuR+'ın kod yürütücüsüyle (KodYurutucu.calistir) çalıştırılmış, sütun türleri veri sekmesinin algıladığı biçimde verilmiştir. Ardından aynı büyüklükler iki bağımsız yoldan yeniden hesaplanmıştır: (1) Python'da, şablonun çağırdığı ana fonksiyon kullanılmadan, formülün doğrudan uygulamasıyla; (2) R'de, başka bir paketle ya da açık formülle. Ölçüt, en büyük mutlak farkın 10^{-6}'yı (değer 1'den büyükse göreli farkın 10^{-6}'yı) aşmamasıdır. Yinelemeli kestirimde fark, yöntemlerin yakınsama toleransından gelir ve tabloda görünür.