# 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

```python
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`