Valis Registration Codex

VALIS Registration for CODEX Data

Experiment Overview

Context

KINTSUGI uses VALIS (Virtual Alignment of pathoLogy Image Series) for multi-cycle registration. CODEX (co-detection by indexing) tissue-on-slide data has both rigid deformation (stage repositioning) and subtle non-rigid deformation (tissue distortion from repeated staining/washing cycles). Registration requires rigid alignment + tuned non-rigid correction.

Critical Bug Fixes (Feb 2026)

Bug 1: Non-Rigid Parameters Silently Ignored (ROOT CAUSE)

File: notebooks/Kreg/serial_non_rigid.py:438

split_params() (line 343) correctly filters config dict into init_kwargs = {"smoothing_method": "gauss", "sigma_ratio": 0.01, ...} via inspect.getfullargspec. But line 438 passed this as:

non_rigid_reg = non_rigid_reg_class(params=init_kwargs)  # BUG: stores dict but kwargs stay at defaults

This set OpticalFlowWarper.__init__(params={"smoothing_method": "gauss", ...}) — the dict was stored in super().__init__(params) but the actual instance attributes used defaults:

• self.smoothing_method = None (not "gauss")
• self.sigma_ratio = 0.005 (not 0.01)

Fix: non_rigid_reg = non_rigid_reg_class(**init_kwargs) — unpack as kwargs.

Impact: ALL previous non-rigid tests (11/12 datasets "worse") ran with unsmoothed OpticalFlowWarper. The "rigid-only is best" conclusion was based on broken code, not on actual non-rigid behavior.

Bug 2: Coarse Non-Rigid at 1024px Resolution

File: notebooks/Kreg/registration.py (Valis.init, line 1771)

VALIS has three distinct dimension parameters:

• max_image_dim_px (default 1024) — max saved output image size
• max_processed_image_dim_px (default 1024) — rigid feature detection resolution
• max_non_rigid_registration_dim_px (default DEFAULT_MAX_PROCESSED_IMG_SIZE = 1024) — coarse non-rigid field resolution

When non_rigid_registrar_cls is passed to the Valis constructor, register() runs a coarse non-rigid pass at max_non_rigid_registration_dim_px (1024px by default). This resolution is far too low for CODEX nuclei patterns, and it poisoned alignment before the 4096px micro pass.

Fix: Set non_rigid_registrar_cls=None in Valis init to disable the coarse pass entirely. Non-rigid is done exclusively in register_micro() at NR_MAX_DIM (4096px).

Note: DEFAULT_MAX_NON_RIGID_REG_SIZE = 3000 exists in registration.py line 68 but is NOT used as the default for max_non_rigid_registration_dim_px — line 1771 uses DEFAULT_MAX_PROCESSED_IMG_SIZE = 1024 instead.

Bug 3: Missing non_rigid_registrar_cls in Valis Init

File: workflow/scripts/registration.py

The Valis init didn't pass non_rigid_registrar_cls or non_rigid_reg_params, so register() used VALIS defaults: non_rigid_registrar_cls=OpticalFlowWarper with empty params. This meant two unsmoothed non-rigid passes (one coarse at 1024px, one micro at whatever dim).

Fix: Pass non-rigid config explicitly to Valis init, or (current approach) set non_rigid_registrar_cls=None to disable the harmful coarse pass.

Current Architecture

# Valis init — coarse non-rigid EXPLICITLY DISABLED
# CRITICAL: non_rigid_registrar_cls=None must be passed explicitly.
# Without it, VALIS defaults to OpticalFlowWarper at 1024px (unsmoothed),
# which poisons alignment before the 4096px micro pass.
registrar = registration.Valis(
    src_dir=str(EDF_DIR),
    dst_dir=str(reg_output_dir),
    img_list=dapi_images,
    reference_img_f=dapi_images[ref_idx],
    max_image_dim_px=MAX_IMAGE_DIM,           # 4096 (was 2048)
    max_processed_image_dim_px=MAX_IMAGE_DIM,  # 4096 (was 2048)
    non_rigid_registrar_cls=None,              # MUST be explicit — disables coarse NR
    feature_detector_cls=fd_cls,               # VggFD (GPU)
    imgs_ordered=True,
    align_to_reference=True,
)

# Rigid registration at 4096px
rigid_registrar, non_rigid_reg, rigid_summary = registrar.register()

# Non-rigid exclusively via register_micro() at 4096px with tuned smoothing
# Sigma math: sigma_pixels = sigma_ratio * max(image_dim_px)
# At 4096px: 0.01 = 41px, 0.005 = 20px (OpticalFlowWarper default), 0.05 = 205px (too high!)
non_rigid_registrar, non_rigid_summary = registrar.register_micro(
    max_non_rigid_registration_dim_px=4096,
    non_rigid_registrar_cls=non_rigid_registrars.OpticalFlowWarper,
    non_rigid_reg_params={
        "smoothing_method": "gauss",
        "sigma_ratio": 0.01,       # 41px sigma at 4096px (was 0.05 = 205px, way too high)
        "n_grid_pts": 50,          # No-op with "gauss" (only for broken "regularize"/"inpaint")
        "fold_penalty": 1e-6,      # No-op with "gauss" (only for broken "regularize")
    },
    align_to_reference=True,
)

Optical Flow Algorithm

OpticalFlowWarper uses OpenCV optical flow under the hood:

• GPU (CUDA available): TVL1 optical flow (cv2.cuda.OpticalFlowDual_TVL1) with default parameters
• CPU fallback: DeepFlow (cv2.optflow.createOptFlow_DeepFlow()) with default parameters
• No tuning knobs are exposed for the flow algorithm itself — only smoothing of the resulting displacement field

Smoothing Methods

Config (workflow/config.yaml)

registration:
  reference_cycle: 1
  reference_channel: 1
  max_image_dim: 4096         # Rigid feature detection resolution (was 2048)
  rigid_only: false           # Non-rigid enabled with tuned smoothing
  feature_detector: "VggFD"
  imgs_ordered: true          # Keep sequential cycle order
  align_to_reference: true    # Direct alignment to reference (not serial chain)
  non_rigid:
    max_dim: 4096             # Displacement field resolution
    smoothing_method: "gauss"
    sigma_ratio: 0.01         # sigma = 0.01 * 4096 = ~41px (was 0.05 = 205px, extreme over-smoothing)
    n_grid_pts: 50            # No-op with "gauss"
    fold_penalty: 1.0e-6      # No-op with "gauss"

Validation Results (CX_19-001_SP_CC2-A28, Feb 18 2026)

Key Findings

• Non-rigid with tuned smoothing (sigma_ratio=0.01) decisively outperforms rigid-only. The earlier "rigid-only is best" conclusion, based on the broken parameter-passing code, is now conclusively disproven.
• Dimension normalization is critical for VALIS. EDF output images had inconsistent dimensions across cycles. The registration wrapper now pads all images to a common size (7479 x 12662 for this dataset) before passing to VALIS. Without this, VALIS either crashes or produces incorrect displacement fields. The normalize_dimensions: true config option enables this behavior.
• Defensive guard in measure_error(): When end_non_rigid_time is None (e.g., non-rigid step skipped or errored), the original code crashed with a NoneType subtraction. A guard now handles this gracefully.
• Timing record added at end of register_micro(): Ensures measure_error() always has valid timing data, even if called from different code paths.

Per-Cycle Results

Registration QC: Green/Magenta Overlay

Full-resolution 1000x1000 crop (whole-image thumbnails are too zoomed out):

import pyvips, numpy as np
img = pyvips.Image.new_from_file(path, access="random")
crop = img.crop(x, y, 1000, 1000)
# Green = cyc01 DAPI, Magenta = last cycle DAPI
# White/gray = aligned, color fringing = misaligned

Important: Average metrics (mean_rigid_D, mean_NCC) are meaningless since poor registration affects only parts of the image. Use spatial NCC heatmaps or targeted overlays on specific regions to evaluate quality.

Failed Attempts

What Worked

Experiment Tracking

VALIS Metrics Reference

Important: D values are at processing resolution, not original image resolution. When comparing experiments at different max_image_dim, use rTRE for valid comparison.

Key Insights

• Non-rigid parameters were NEVER applied in all previous tests (Bug 1). The "rigid-only is best" conclusion is invalidated.
• Coarse non-rigid at 1024px is actively harmful — always disable it for CODEX (set non_rigid_registrar_cls=None in Valis init)
• 4096px rigid processing improves feature matching on difficult cycles (vs 2048px)
• Three VALIS dimension parameters control different things — conflating them causes silent quality loss
• Average metrics are meaningless — poor registration is localized. Use spatial NCC heatmaps or full-resolution crops.
• imgs_ordered=True is critical — VALIS default reorders by visual similarity, breaking CODEX sequential order
• align_to_reference=True prevents error accumulation in long cycle chains (13+ cycles)
• All 47 batch-processed datasets may need re-registration once optimal non-rigid parameters are determined
• Diagnostic logging: Added print in OpticalFlowWarper.__init__ confirms params reach the constructor
• non_rigid_registrar_cls=None must be EXPLICIT — omitting it leaves the VALIS default (OpticalFlowWarper), which runs the harmful coarse NR pass. The comment was there but the param was never passed.
• None bk_dxdy: When coarse NR is disabled, slide_obj.bk_dxdy stays None. register_micro() needs a zero-displacement fallback or it crashes on slide_obj.bk_dxdy[0]
• Sigma math: sigma_pixels = sigma_ratio * max(image_dim_px). sigma_ratio=0.05 at 4096px = 205px sigma — averages over 400+ pixel neighborhoods, completely washing out local corrections needed for nuclei alignment (~3-6px at 4096px)
• Validated (Feb 18 2026): sigma_ratio=0.01 at 4096px confirmed on CX_19-001_SP_CC2-A28 — 11/12 cycles improved, mean D 1.12 to 0.77. This is the recommended starting configuration for CODEX datasets.
• Dimension normalization: EDF outputs can have inconsistent dimensions across cycles. The registration wrapper must pad all images to a common size before VALIS, or displacement fields will be incorrect. Use normalize_dimensions: true in config.
• Stale Snakemake coordinators: After cancelling SLURM jobs, background Snakemake processes may still be alive and resubmit jobs. Always check squeue for duplicate jobs before manual resubmission.
• Defensive timing: register_micro() must record end_non_rigid_time before returning, and measure_error() must guard against None timing values to prevent crashes in edge cases
• Batch re-registration validated: 4/16 projects completed (CX_19-002_lymph-node_R1: 29.5 min, CX_19-002_lymph-node_R3: 27.6 min, CX_19-003_lymph-node_R1: 40.8 min). Tuned non-rigid params (sigma_ratio=0.01, 4096px) generalize across spleen and lymph node tissue types.
• Fallback copy is dangerous: The old fallback_copy sentinel masked 3 broken registrations with error=Rigid registration failed. These passed the pipeline without error and were only caught by manual inspection of sentinel JSON. Fallback copies should NEVER be used — registration failures must raise exceptions.
• Race condition on relaunch: Old SLURM jobs from killed Snakemake coordinators can write stale output after Phase 1 cleanup. Must cancel ALL old jobs (scancel) and kill stale coordinators before relaunching registration.
• Bash array pitfall: declare -a TODO_PROJECTS does NOT clear an existing bash array. Use TODO_PROJECTS=() to explicitly empty it before repopulating.
• Snakemake CLI argument order: Targets after --configfile are interpreted as additional config files, not rule targets. Always place targets BEFORE options: snakemake registration --configfile config.yaml

When to Apply

• Any CODEX/multiplex IF dataset with multi-cycle acquisition
• When registration QC shows color fringing in green/magenta DAPI overlays
• When VALIS summary CSV shows non_rigid_D > rigid_D — check if params are actually being applied
• After any upgrade to the VALIS/Kreg library — re-verify parameter passing

Files Modified

References

• Related skill: gpu-only-scheduling (GPU slot management for registration jobs)
• Related skill: snakemake-skip-existing (sentinel file patterns)
• Related skill: cleanup-qc-review-guard (QC verification before cleanup)
• VALIS library: notebooks/Kreg/registration.py (Valis class, line 1771 for dimension defaults)
• VALIS library: notebooks/Kreg/serial_non_rigid.py (line 438, params bug location)