Center refinement

COSEDA refines the per-frame beam centers without indexing by smoothing Friedel-pair deviations over time and applying damped updates. It consumes the initial centers from Find Centers and writes updated center_x/center_y plus detector shifts for downstream geometry. Only the Beamstop path is documented here; Direct mode is selectable in the GUI.

This stage requires center finding to have run first (center_x, center_y must exist in the HDF5).

Inputs

  • COSEDA working file (<dataset>.h5) with:

    • entry/data/images

    • entry/data/peakXPosRaw, peakYPosRaw, nPeaks

    • optional entry/data/index (raw → kept frames; falls back to identity if absent)

    • entry/data/center_x, center_y (from Find Centers)

  • Dataset .ini with centerrefinement_* parameters (see below)

How it works

  1. Per-frame deviations.
    For each kept frame, select peaks within a radial cutoff around the current center, form Friedel pairs whose vectors about the center nearly cancel, and compute deviation vectors (δx, δy). Per-frame deviations are aggregated to one robust median value per frame by default, or left at pair level when configured.

  2. LOWESS smoothing.
    Fit robust LOWESS curves δ̂x(k), δ̂y(k) versus raw frame index k. Results are stored in lowess_and_centers_itNNN.npz.

  3. Damped center update.
    Apply a half-step correction to every frame: [ c_{x,k}^{(t+1)} = c_{x,k}^{(t)} + \tfrac{1}{2},\widehat{\delta}x(k), \quad c{y,k}^{(t+1)} = c_{y,k}^{(t)} + \tfrac{1}{2},\widehat{\delta}_y(k). ] Iterate until (\max_k |\widehat{\delta}| < \epsilon) or max_iterations is reached.

  4. Detector shifts (mm).
    Convert refined centers to CrystFEL-style detector shifts: [ \mathrm{det_shift}_{x,y}^{\mathrm{mm}} =

    • \frac{\bigl(\mathrm{center}_{x,y} - \tfrac{\text{framesize}}{2}\bigr)}{\text{pixels_per_meter}} \times 1000. ] Shifts are written per frame.

Parallelism. Frames are processed in batches via Dask; if Dask fails, COSEDA automatically falls back to sequential processing.

Parameters (INI [Parameters])

Key

Description

centerrefinement_tolerance (px)

Friedel pairing threshold

centerrefinement_min_peaks

Discard frames with fewer peaks than this

centerrefinement_resolution_limit (px)

Radial cutoff; only peaks within this radius are considered

centerrefinement_max_iterations

Iteration cap

centerrefinement_convergence_threshold (px)

ε for stopping; refinement stops when LOWESS-smoothed deviations stay within this band

centerrefinement_lowess_frac (0–1)

LOWESS window as a fraction of surviving frames (default 0.1)

centerrefinement_lowess_window (frames)

Absolute window size for LOWESS; overrides the fraction when >0 (default 0, disabled)

centerrefinement_deviation_aggregation

How deviations are fed to LOWESS: median (default, one value per frame) or pair (all pair deviations)

centerrefinement_max_pairs_per_frame

Cap on Friedel pairs collected per frame (default 10000)

batch_size

Frames per batch (default 500); affects performance only, not results

Required keys check: the runner hard-fails if any of centerrefinement_tolerance, centerrefinement_min_peaks, centerrefinement_resolution_limit, centerrefinement_max_iterations, centerrefinement_convergence_threshold is missing.

pixels_per_meter is read from [AcquisitionDetails] and used to compute detector shifts.

Using the GUI

Open the Refine Centers window from the toolbar or menu.

  1. Select the method (Beamstop or Direct) from the drop-down.

  2. Set the required parameters: Tolerance, Min Peaks, Resolution Limit, Max Iterations, Convergence Threshold. Hover over any field for a tooltip explanation.

  3. Optionally adjust LOWESS Fraction, LOWESS Window, and LOWESS Input (per-frame median or per-pair deviations via the Use pair-level deviations checkbox).

  4. Set the Batch Size (default 500 frames per batch).

  5. Click Save Current (or Save All) under Save Settings to persist settings into the .ini.

  6. Click Find Current (one dataset) or Find All (all workspace datasets) under Find Centers to run.

  7. After completion, review the preview panel: deviations with LOWESS fit, Center X and Center Y traces with LOWESS deviation overlay. Use the run selector dropdown to switch between past runs, and Previous/Next to navigate iterations.

A Stop button is available during processing to cancel after the currently submitted batches complete.

CLI

from coseda.centerrefinement.refinecenters_beamstop import refinecenters_batch

ini = "/path/to/dataset.ini"
refinecenters_batch(input_path=ini, usedask=True, batch_size=500)

Outputs

  • HDF5:

    • entry/data/center_x, center_y (px, per frame)

    • entry/data/det_shift_x_mm, det_shift_y_mm (mm, per frame)

  • Run artifacts (per run; used by the GUI):

    • refinecenters_*/lowess_and_centers_itNNN.npz

    • refinecenters_*/deviations_itNNN.npz

    • refinecenters_*/paramdump.txt