Measurement architecture
Mişko needs stable measurement contracts, not loose result JSON. Every paradigm must define its parameters, zones, metrics, event types, and quality requirements before the CV service can produce results that are comparable across studies and laboratories.
Architecture principle
Section titled “Architecture principle”Every result passes through four layers:
| Layer | Purpose |
|---|---|
ParadigmSpec |
Code-owned contract for parameters, zones, metrics, event types (with CV detect specs), and result schema. |
Apparatus |
Lab-owned physical rig definition: geometry, material, surface, and zones in cm. |
Calibration |
Pixel-to-cm mapping for a fixed rig or a single test session. |
MetricDefinition |
Code-owned definition of each metric key, unit, formula, normalization, and QC dependency. |
CV tracks the animal. Mişko defines the scientific contract.
Paradigms are templates
Section titled “Paradigms are templates”A paradigm is a versioned template defined in code. Environments are created from it, and protocol steps refer to those environments. Every parameter has a scope that says where it is set:
| Scope | Set on | Required | Examples |
|---|---|---|---|
APPARATUS |
Environment | Yes, measured on the physical setup | arena width, tank diameter, pole length |
ANALYSIS |
Environment | No, defaults suit most setups | wall zone width, time on platform to escape, minimum total exploration |
SESSION |
Protocol step | No, defaults apply | trial cut-off, treadmill start and end speed |
Each parameter carries a label and a help text that says what to measure or what
the value changes. Names, labels, help texts, zone and event names, plain metric
descriptions and the technical definitions (metric definitions, missing-data
rules, zone geometry, event definitions) are written in every supported
language (English and Turkish) next to the definition, and the API returns them
in the language the panel asks for (Accept-Language, or ?lang=tr).
Formulas stay as written, since they are expressions rather than prose. The
published manifests are pinned in English, so a translation can never change
the contract unnoticed. The panel shows ratios as percentages and switches as
on and off.
interface ParadigmManifest { key: string; name: string; // in the response language description: string; // what the test is and what it measures category: "LEARNING_MEMORY" | "MOTOR"; trialTypes: { key: string; label: string }[]; parameters: { key: string; scope: "APPARATUS" | "ANALYSIS" | "SESSION"; label: string; help: string; unit: "cm" | "cm_s" | "s" | "count" | "ratio" | "boolean"; valueType: "number" | "integer"; min: number; max: number; default: number; }[]; zones: { key: string; label: string; role: string; geometry: string }[]; metrics: { key: string; label: string; description: string; unit: string; definition: string; formula: string; missingWhen: string }[]; qc: { key: string; operator: string; value: number; unit: string }[];}Changing a calculation, a range or a default publishes a new paradigm version. Wording and help texts can be improved without a new version.
Every paradigm is tracked
Section titled “Every paradigm is tracked”There is no manual analysis. A worker tracks the subject’s centroid in the
calibration’s centimetre frame for every paradigm, and the metric engine in
backend/internal/paradigms/domain derives every event and metric from the
samples and the zones; the worker never decides events and the API never
accepts metrics from it. A person only reviews the result (accepts or rejects
it). The jobs process queues one run per subject once the test’s video is
verified, the calibration with every required zone is valid and an enabled
worker has the paradigm version as a capability.
| Paradigm | Camera and frame | Zones | Derived events |
|---|---|---|---|
MWM |
Above the tank; tank-centred cm, x east, y north | from parameters (platform, target quadrant, wall zone) | in_platform intervals, platform_entry points |
NOVEL_OBJECT |
Above the arena; origin at a floor corner, x right, y down the image | calibrated novel_object, familiar_object |
exploration intervals labelled novel or familiar |
POLE |
Side of the pole; x horizontal, y the height above the base | calibrated pole, base |
turn_complete, base_reached, fall (points, each once) |
TREADMILL |
Side of the lane; x from the shock grid end (0) to the front | calibrated shock_grid |
shock points, exhaustion (point, once) |
Every rule threshold is an ANALYSIS parameter with a standard default, so a
lab can tune it per environment:
- Novel object. An exploration bout is a stay of the centroid in an
object’s zone lasting at least
min_bout_s(0.3 s); the zone is drawn around the object to include the exploration distance (about 2 cm). Known limit: the body centre, not the nose direction, decides, so sitting on the object counts as exploration. Novel, familiar and total exploration time are the sums of the bouts; the discrimination index is (novel - familiar) / (novel + familiar), missing belowmin_total_exploration_s. - Pole. The turn completes at the first sample on the pole
turn_descent_cm(2 cm) below the highest point so far. The base is reached at the first sample inbaseafter a sample on the pole. A fall is leaving the pole (to the base or anywhere else) between two samples at mostmax_sample_gap_sapart with a downward speed abovefall_speed_cm_s(80 cm/s); after a fall the base is not reached. Samples aftermax_trial_duration_sare ignored. - Treadmill. Every stay on the shock grid lasting
min_shock_dwell_s(0.2 s) is a shock; the first stay lastingexhaustion_dwell_s(5 s) is exhaustion. The run ends at exhaustion or, without it, at the end of the clip, censored atmax_trial_duration_s; the distance is the belt speed integrated over the run.
Missing metrics carry a reason instead of zero: NO_VALID_INTERVALS,
EVENT_NOT_OBSERVED, ZERO_DENOMINATOR, INCOMPLETE_RECORDING and
BELOW_EXPLORATION_CRITERION. There is no NOT_SCORED any more.
Every run feeds the per-subject result, which opens PENDING for human
review; only accepted results enter the report.
Zone requirements
Section titled “Zone requirements”Zones come from one of two places:
- From parameters. The water maze derives its zones from the environment’s measurements (the platform position and diameter, the wall zone width). Its calibration world points must use the frame those zones are defined in: tank-centred ((0, 0) at the tank centre, x east, y north, so the wall points are (r, 0), (0, r), (-r, 0) and (0, -r) with r = tank diameter / 2).
- Calibrated. The novel object, pole and treadmill zones carry the
apparatus geometry the video needs (objects, pole, base, shock grid). They
are drawn once as circles or polygons on the camera frame with the
environment’s calibration; a per subject override on the test video changes
them when needed (for example the novel object on the other side), and a key
may have several shapes. Shapes are stored as drawn in pixels and converted
to centimetres with the calibration’s fitted transform; they must lie inside
the frame and never change after the calibration is saved (migration
014_calibration_zones.sql). Until a valid calibration with every required zone applies, the subject staysWAITING_FOR_CALIBRATIONand is not analysed. The novel object arena’s calibration points lie in the arena (0 to width, 0 to depth); the side views of the pole and the treadmill are calibrated on theAPPARATUS_SIDEplane with at least four non-collinear points of the rig and choose their own frame.
Inferred samples
Section titled “Inferred samples”misko.trajectory.v1 has an optional inferred flag per sample. A worker may
fill a stretch of frames where the animal is hidden with samples that are
tracked with inferred: true; they count as tracked, but not in the
tracking confidence mean. No paradigm of the current catalog needs this and the
bundled worker sends no inferred samples; frames without a detection stay
lost.
No pass/fail verdict
Section titled “No pass/fail verdict”A lab test result is data, not a verdict. Mişko does not compute a behavioral
passed flag and there is no acceptance-criteria layer. Whether a value is “good”
is interpretation, which belongs to the analysis layer, not to the recording
system. Only QC (tracking reliability) has a pass/fail meaning, and that is about
data quality, not behavior.
Event types and CV detection
Section titled “Event types and CV detection”A run collects events; metrics are derived from them. The metric engine derives the event stream from the CV service’s trajectory and the calibrated zones, so the event layer is the contract between Mişko and computer vision.
Each event type declares a detect spec describing how the CV service derives it
from the trajectory and zones:
interface EventTypeDef { type: string; // e.g. "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" }; // requires a dedicated detector/modelThe generic kinds (zone_transition, zone_first_enter, speed_below) are
data-driven: a paradigm that only uses them needs no new CV code, declaring
the event types is enough. custom flags an event that needs a dedicated
detector. The published paradigms derive their events from zones and speeds in
the metric engine, so none needs one. Event types are exposed on
the paradigm detail API (GET /api/paradigms/:key -> eventTypes).
Localization
Section titled “Localization”Catalog wording lives in the paradigm definitions in
backend/internal/paradigms/domain, written in English and Turkish side by side
(T("Arena width", "Arena genişliği")). GET /api/paradigms,
GET /api/paradigms/{key} and GET /api/paradigms/{key}/versions/{version}
answer in the language of ?lang= (en or tr), otherwise of
Accept-Language, otherwise English, and set Content-Language. The panel
sends its chosen language with every request. A test fails when any name,
label, help text or metric description is missing in a language, looks like a
key, or uses an em dash. Small fixed enums (units, categories, scopes, quality
rule names) are translated by the panel’s own dictionary.
Measurement dictionary
Section titled “Measurement dictionary”The metric dictionary prevents two services from using one name for different calculations.
interface MetricDefinition { key: string; paradigmKeys: string[]; unit: "cm" | "cm_s" | "s" | "count" | "ratio" | "percent" | "deg" | "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[];}Canonical result units: positions and distances in cm, speed in cm_s,
duration in s, weight in g, angles in deg, ratios
as ratio (0..1) or percent, event flags as boolean, and counts as
count. Apparatus parameters reuse this enum and add mm (small rig diameters)
and c (water temperature in Celsius), which never appear in result metrics.
Pixel values stay out of Mişko result metrics.
Baseline metrics
Section titled “Baseline metrics”| Key | Unit | Definition |
|---|---|---|
duration_s |
s |
Analyzed time window after invalid frames are trimmed. |
distance_cm |
cm |
Total path length in apparatus coordinates. |
mean_speed_cm_s |
cm_s |
Distance divided by duration. |
zone_time_s.{zoneKey} |
s |
Time spent in a declared zone. |
zone_entries.{zoneKey} |
count |
Debounced entries into a declared zone. |
latency_to_zone_s.{zoneKey} |
s |
Time from trial start to first valid zone entry. |
path_efficiency_ratio |
ratio |
Straight-line distance to target divided by actual path length. |
Paradigm metrics
Section titled “Paradigm metrics”| Paradigm | Core metrics |
|---|---|
| MWM | Escape latency, path length, swim speed, target quadrant time, platform crossings, thigmotaxis, mean distance to platform. |
| Novel object | Novel object time, familiar object time, total exploration time, discrimination index. |
| Pole | Time to turn, total time, descent time, descent speed, fall detected. |
| Treadmill | Time to exhaustion, running time, distance run, shock count. |
MWM normalization
Section titled “MWM normalization”Morris Water Maze varies strongly across labs. A comparable result needs both raw cm values and normalized values.
Required apparatus fields:
{ "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}Coordinate normalization:
radius_cm = tank_diameter_cm / 2x_norm = x_cm / radius_cmy_norm = y_cm / radius_cmdistance_norm = distance_cm / tank_diameter_cmplatform_distance_norm = distance_to_platform_cm / tank_diameter_cmCross-lab reports should compare only compatible trial types and protocol versions, prefer normalized spatial metrics, keep raw cm values for within-lab reproducibility, and always report swim speed beside latency.
Quality control
Section titled “Quality control”QC status is about data reliability only. There is no behavioral pass/fail: the
behavioral result is the metric data itself. result.qc.status is the
reliability status.
| QC key | Unit | Default action |
|---|---|---|
tracking_confidence_mean |
ratio |
Warn below 0.80. |
tracking_confidence_p05 |
ratio |
Review below 0.50. |
dropped_frame_ratio |
ratio |
Warn above 0.05, fail above 0.15. |
calibration_error_cm_mean |
cm |
Warn above 1.0 cm. |
calibration_error_cm_max |
cm |
Review above 2.0 cm. |
occlusion_time_ratio |
ratio |
Warn above 0.10. |
out_of_bounds_time_ratio |
ratio |
Fail above 0.02. |
lighting_warning |
boolean |
Manual review. |
contrast_warning |
boolean |
Manual review. |
QC statuses: PASS, WARN, REVIEW_REQUIRED, FAIL.
Rules applied today
Section titled “Rules applied today”The table above is the target model. The rules the API applies to a tracked run
today are those of the paradigm version (trajectoryQC):
| Rule | Limit | Measured on |
|---|---|---|
min_tracking_confidence |
>= 0.7 |
mean confidence of observed samples (tracked and not inferred) |
max_lost_frame_ratio |
<= 0.1 |
share of samples that are not tracked; inferred samples count as tracked |
max_calibration_error_cm |
<= 2 cm |
the calibration’s check points, when it is saved |
Inferred samples never raise or lower the confidence mean. The worker records
their share in the trajectory’s diagnostics (worker.inferredRatio), and a
paradigm version may cap it with max_inferred_ratio; no published version sets
that rule yet. A run that breaks a rule fails with a QC_FAILED reason and publishes
nothing. The same rules apply to every paradigm.
Result shape
Section titled “Result shape”Test.result should become structured JSON in the domain migration.
{ "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" }}