Ölçüm mimarisi

Mişko’nun gevşek sonuç JSON’u değil, kararlı ölçüm kontratları tutması gerekir. Her paradigma, CV servisinin çalışmalar ve laboratuvarlar arasında karşılaştırılabilir sonuç üretebilmesi için parametrelerini, bölgelerini, metriklerini, olay tiplerini (CV detect spec’leri ile) ve kalite gereksinimlerini önceden tanımlamalıdır.

Mimari ilke

Her sonuç dört katmandan geçer:

Katman	Amaç
ParadigmSpec	Parametreler, bölgeler, metrikler, olay tipleri (CV detect spec’leri ile) ve sonuç şeması için kod sahipli kontrat.
Apparatus	Lab sahipli fiziksel düzenek tanımı: geometri, malzeme, yüzey ve cm cinsinden bölgeler.
Calibration	Sabit düzenek veya tek test oturumu için pikselden cm’ye eşleme.
MetricDefinition	Her metrik anahtarının birim, formül, normalizasyon ve QC bağımlılığını tanımlayan kod sahipli sözlük.

CV hayvanı takip eder. Bilimsel kontratı Mişko tanımlar.

Paradigma spec sayfaları

Her paradigma için şu bölümleri içeren bir detay sayfası gerekir:

• Kimlik: key, ad, kategori, trial türleri.
• Apparatus parametreleri: birimli fiziksel değerler, validasyon, varsayılanlar ve min/max değerler.
• Oturum parametreleri: trial süresi, başlangıç pozisyonu, trial indeksi, protokol varyantı.
• Bölgeler: zone key’leri, geometri tipi, koordinat sistemi ve türetme kuralı.
• Metrikler: zorunlu ve opsiyonel metrik key’leri, birimler, tanımlar ve normalizasyon.
• Olay tipleri: bir koşunun toplayabileceği olaylar, payload’ları ve her biri için CV detect spec’i.
• QC gereksinimleri: takip güveni, düşen kareler, kalibrasyon hatası, occlusion, ışık ve kontrast.
• Artefaktlar: video, trajectory, heatmap, kalibrasyon görseli ve debug overlay URL’leri.

interface ParadigmSpec {
  key: "MWM" | "OPEN_FIELD" | "EPM" | "ROTAROD";
  name: string;
  category: "learning_memory" | "anxiety" | "motor" | "social";
  trialTypes: TrialTypeDef[];
  apparatusParameters: FieldDef[];
  sessionParameters: FieldDef[];
  zones(config: ApparatusConfig): ZoneDef[];
  metrics: MetricDefinition[];
  eventTypes: EventTypeDef[];
  qc: QualityRequirement[];
}

Geçti/kaldı verdikti yok

Bir lab test sonucu veridir, verdikt değil. Mişko davranışsal bir passed bayrağı hesaplamaz ve bir kabul kriteri katmanı yoktur. Bir değerin “iyi” olup olmadığı yorumdur, kayıt sistemine değil analiz katmanına aittir. Yalnızca QC (takip güvenilirliği) bir geçti/kaldı anlamı taşır, o da davranışla değil veri kalitesiyle ilgilidir.

Olay tipleri ve CV tespiti

Bir koşu olaylar toplar; metrikler bu olaylardan türetilir (bkz. docs/METRIC_ENGINE.md). Aynı olay akışı bugün manuel girişle, ileride ise CV servisiyle üretilir, yani olay katmanı Mişko ile bilgisayarlı görü arasındaki kontrattır.

Her olay tipi, CV servisinin onu trajectory ve bölgelerden nasıl türettiğini tanımlayan bir detect spec’i bildirir:

interface EventTypeDef {
  type: string;                       // örn. "zone_enter", "immobile", "fall"
  label: string;
  payload?: Record<string, "number" | "text" | "zone">;
  detect: DetectSpec;
}

type DetectSpec =
  | { kind: "zone_transition"; edge: "enter" | "exit"; zone?: string }
  | { kind: "zone_first_enter"; zone: string }
  | { kind: "speed_below"; threshold_cm_s: number; min_duration_s?: number }
  | { kind: "custom" };               // özel bir dedektör/model gerektirir

Jenerik türler (zone_transition, zone_first_enter, speed_below) veri-güdümlüdür: yalnızca bunları kullanan bir paradigma yeni CV kodu gerektirmez, olay tiplerini bildirmek yeterlidir. custom, özel bir dedektör gerektiren bir olayı işaretler (örn. bir rotarod düşüşü, bir sosyal etkileşim). Olay tipleri paradigma detay API’sinde sunulur (GET /api/paradigms/:key -> eventTypes).

Lokalizasyon

Paradigma ve metrik sözlüğü bilimsel kontrattır ve spec kaynağında yalnızca Türkçe tutulur (varsayılan dil). Salt-okunur inceleme API’si serbest-metin etiketleri ve tanımları, GET /api/paradigms, GET /api/paradigms/:key ve GET /api/paradigms/metrics uçlarındaki opsiyonel ?lang= parametresiyle lokalize eder. Desteklenen değerler tr (varsayılan) ve en’dir; bilinmeyen veya eksik bir değer tr’ye, çevirisi olmayan bir etiket veya tanım ise Türkçe kaynağına geri düşer. Backend tek kaynak olarak kalır (katalog backend/src/config/i18n.js içinde), böylece CV servisi ve frontend aynı sözlüğü kaymadan paylaşır. Küçük sabit enum’lar (zone tipi/rolü, tür) ise frontend UI sözlüğü tarafından çevrilir.

Ölçüm sözlüğü

Metrik sözlüğü, iki servisin aynı ismi farklı hesaplar için kullanmasını engeller.

interface MetricDefinition {
  key: string;
  paradigmKeys: string[];
  unit: "cm" | "cm_s" | "s" | "count" | "ratio" | "percent" | "deg" | "rpm" | "boolean";
  valueType: "number" | "integer" | "boolean" | "object";
  required: boolean;
  definition: string;
  formula: string;
  inputs: string[];
  normalization: NormalizationDef | null;
  aggregation: "per_trial" | "per_session" | "per_subject_timepoint" | "study_summary";
  qcDependencies: string[];
}

Kanonik sonuç birimleri: pozisyon ve mesafe cm, hız cm_s, süre s, ağırlık g, açı deg, dönüş hızı rpm, oranlar ratio (0..1) veya percent, olay bayrakları boolean, sayımlar count. Apparatus parametreleri bu enum’ı yeniden kullanır ve sonuç metriklerinde hiç görünmeyen mm (küçük düzenek çapları) ile c (Celsius cinsinden su sıcaklığı) birimlerini ekler. Piksel değerleri Mişko sonuç metriklerine girmez.

Temel metrikler

Key	Birim	Tanım
duration_s	s	Geçersiz kareler kırpıldıktan sonra analiz edilen zaman penceresi.
distance_cm	cm	Apparatus koordinatlarında toplam yol uzunluğu.
mean_speed_cm_s	cm_s	Mesafenin süreye bölümü.
zone_time_s.{zoneKey}	s	Tanımlı bir bölgede geçirilen süre.
zone_entries.{zoneKey}	count	Tanımlı bölgeye debounce edilmiş giriş sayısı.
latency_to_zone_s.{zoneKey}	s	Trial başlangıcından ilk geçerli bölge girişine kadar geçen süre.
path_efficiency_ratio	ratio	Hedefe düz çizgi mesafesinin gerçek yola oranı.

Paradigma metrikleri

Paradigma	Ana metrikler
MWM	Escape latency, path length, swim speed, target quadrant time, platform crossings, thigmotaxis, mean distance to platform.
Open Field	Total distance, center time, periphery time, center entries, immobility, mean speed.
EPM	Open arm time, closed arm time, open ve closed arm entries, latency to open arm, opsiyonel risk assessment event’leri.
Rotarod	Latency to fall, rpm at fall, trial duration, fall detected, tekrarlı trial’larda learning slope.

MWM normalizasyonu

Morris Su Tankı laboratuvarlar arasında ciddi farklılık gösterir. Karşılaştırmalı sonuç için hem ham cm değerleri hem normalize değerler gerekir.

Zorunlu apparatus alanları:

{
  "tank_diameter_cm": 120,
  "tank_center_cm": { "x": 0, "y": 0 },
  "platform_diameter_cm": 10,
  "platform_center_cm": { "x": 30, "y": -30 },
  "platform_quadrant": "SE",
  "water_opacity": "opaque",
  "water_temp_c": 22,
  "surface_color": "white",
  "start_positions": ["N", "E", "S", "W"],
  "wall_annulus_width_cm": 12
}

Koordinat normalizasyonu:

radius_cm = tank_diameter_cm / 2
x_norm = x_cm / radius_cm
y_norm = y_cm / radius_cm
distance_norm = distance_cm / tank_diameter_cm
platform_distance_norm = distance_to_platform_cm / tank_diameter_cm

Lablar arası raporlar yalnızca uyumlu trial türlerini ve protokol versiyonlarını karşılaştırmalı, normalize uzaysal metrikleri tercih etmeli, lab içi tekrarlanabilirlik için ham cm değerlerini korumalı ve latency yanında swim speed’i her zaman göstermelidir.

Kalite kontrol

QC durumu (result.qc.status) yalnızca veri güvenilirliği hakkındadır. Davranışsal bir geçti/kaldı yoktur; davranışsal sonuç metrik verisinin kendisidir.

QC key	Birim	Varsayılan aksiyon
tracking_confidence_mean	ratio	0.80 altında uyar.
tracking_confidence_p05	ratio	0.50 altında inceleme ister.
dropped_frame_ratio	ratio	0.05 üstünde uyar, 0.15 üstünde fail.
calibration_error_cm_mean	cm	1.0 cm üstünde uyar.
calibration_error_cm_max	cm	2.0 cm üstünde inceleme ister.
occlusion_time_ratio	ratio	0.10 üstünde uyar.
out_of_bounds_time_ratio	ratio	0.02 üstünde fail.
lighting_warning	boolean	Manuel inceleme.
contrast_warning	boolean	Manuel inceleme.

QC durumları: PASS, WARN, REVIEW_REQUIRED, FAIL.

Sonuç şekli

Domain migration ile Test.result yapılandırılmış JSON olmalıdır.

{
  "schemaVersion": "misko.result.v1",
  "paradigmKey": "MWM",
  "protocolVersion": "mwm.v1",
  "trialType": "acquisition_hidden_platform",
  "metrics": {
    "escape_latency_s": 18.4,
    "path_length_cm": 735.2,
    "path_length_norm": 6.13,
    "mean_swim_speed_cm_s": 39.9,
    "thigmotaxis_time_ratio": 0.22
  },
  "qc": {
    "status": "PASS",
    "tracking_confidence_mean": 0.94,
    "dropped_frame_ratio": 0.01,
    "calibration_error_cm_mean": 0.42
  },
  "artifacts": {
    "videoUrl": "s3://misko/tests/t-1/video.mp4",
    "trajectoryUrl": "s3://misko/tests/t-1/trajectory.parquet",
    "heatmapUrl": "s3://misko/tests/t-1/heatmap.png"
  }
}