Add YAML example to every step reference entry

docs/steps/binning.md

@@ -24,6 +24,11 @@ Compute per-shot delays from laser timing keys and lay down delay bins.
 | `tt_correction_key` | `"time_tool_correction"` | time-tool jitter correction key |
 | `resolution` | `50e-15` | bin width in seconds for `bins: auto` |
 
+```yaml
+- step: time_binning
+  bins: [-1e-12, 5e-12, 25]
+```
+
 ### `make_ccm_axis`
 Build incident-energy (CCM) bin edges and centers for an XAS scan.
 
@@ -37,6 +42,11 @@ Build incident-energy (CCM) bin edges and centers for an XAS scan.
 | `ccm_key` | `"ccm"` | per-shot incident-energy key |
 | `resolution` | `0.001` | bin width (keV) for `energies: auto` |
 
+```yaml
+- step: make_ccm_axis
+  energies: [7.10, 7.15, 51]
+```
+
 ### `ccm_binning`
 Assign each shot to a CCM energy bin.
 
@@ -49,6 +59,12 @@ Assign each shot to a CCM energy bin.
 | `ccm_key` | `"ccm"` | per-shot incident-energy key |
 | `ccm_bins_key` | `"ccm_bins"` | edges produced by `make_ccm_axis` |
 
+```yaml
+- step: ccm_binning
+  ccm_key: ccm
+  ccm_bins_key: ccm_bins
+```
+
 ### `bin_uniques`
 Bin an arbitrary scan variable by its unique values (one bin per value).
 
@@ -60,6 +76,11 @@ Bin an arbitrary scan variable by its unique values (one bin per value).
 |------|---------|-------------|
 | `on` | required | per-shot scan variable to bin |
 
+```yaml
+- step: bin_uniques
+  on: sample_temperature
+```
+
 ### `make_energy_axis`
 Convert pixel index to emission energy from von Hamos crystal geometry.
 
@@ -77,6 +98,15 @@ Convert pixel index to emission energy from von Hamos crystal geometry.
 | `mm_per_pixel` | `0.05` | pixel pitch (mm) |
 | `name` | `"xes"` | output prefix, so the axis is `<name>_energy` |
 
+```yaml
+- step: make_energy_axis
+  detector_key: epix
+  crystal_detector_distance: 100.0
+  crystal_radius: 500.0
+  d_spacing: 1.6375
+  name: xes
+```
+
 ## Binned reductions
 
 Each reduction sums per-shot data into its bins. Pass `average: True` to divide
@@ -97,6 +127,12 @@ Bin a per-shot spectrum along delay.
 | `timing_bin_key` | `"timing_bin_indices"` | bin-index attribute |
 | `average` | `False` | divide each bin by its shot count |
 
+```yaml
+- step: reduce_detector_temporal
+  on: epix_ROI_1_simultaneous_laser
+  average: true
+```
+
 ### `reduce_detector_ccm`
 Bin a per-shot spectrum along incident energy.
 
@@ -110,6 +146,12 @@ Bin a per-shot spectrum along incident energy.
 | `ccm_bin_key` | `"ccm_bin_indices"` | bin-index attribute |
 | `average` | `False` | divide each bin by its shot count |
 
+```yaml
+- step: reduce_detector_ccm
+  on: epix_ROI_1
+  average: true
+```
+
 ### `reduce_detector_ccm_temporal`
 Bin a per-shot spectrum along both delay and incident energy (2D map).
 
@@ -125,3 +167,9 @@ Bin a per-shot spectrum along both delay and incident energy (2D map).
 | `timing_bin_key` | `"timing_bin_indices"` | delay bin-index attribute |
 | `ccm_bin_key` | `"ccm_bin_indices"` | energy bin-index attribute |
 | `average` | `False` | divide each bin by its shot count |
+
+```yaml
+- step: reduce_detector_ccm_temporal
+  on: epix_ROI_1
+  average: true
+```

docs/steps/detector.md

@@ -55,6 +55,13 @@ Repair bad pixels or columns, either from an explicit list or auto-detected.
 | `poly_range` | `6` | half-width of the fit window |
 | `deg` | `1` | polynomial degree for `mode: polynomial` |
 
+```yaml
+- step: patch_pixels
+  on: epix
+  pixels: [383, 384]   # dead column pair
+  mode: polynomial
+```
+
 ## Geometry
 
 ### `find_rotation_angle`
@@ -72,6 +79,12 @@ it.
 | `high_threshold` | `100` | upper ADU bound for edge detection |
 | `angle_key` | `<on>_angle` | attribute to store the detected angle |
 
+```yaml
+- step: find_rotation_angle
+  on: epix
+  angle_key: epix_angle
+```
+
 ### `rotate_detector`
 Rotate detector frames by a fixed angle or by a previously detected one.
 
@@ -111,6 +124,12 @@ Crop to one or more regions of interest, keeping the spatial dimension.
 | `rois` | required | list of `[row0, row1, col0, col1]` crops |
 | `combine_rois` | `True` | merge ROIs into one array vs keep separate `_ROI_n` |
 
+```yaml
+- step: apply_roi
+  on: epix
+  rois: [[270, 330, 400, 700]]
+```
+
 ### `reduce_detector_spatial`
 Crop to ROIs and collapse one spatial axis into a per-shot dispersion trace.
 
@@ -131,6 +150,13 @@ ROI rows are given in absolute detector coordinates; the step translates them
 into the loaded crop using the run's `_row_offset`, so the same YAML works
 whether the detector was cropped at load or not.
 
+```yaml
+- step: reduce_detector_spatial
+  on: epix
+  rois: [[270, 330, 400, 700]]
+  reduction: sum
+```
+
 ### `reduce_detector_shots`
 Collapse the shot axis into a single averaged or summed frame.
 
@@ -143,3 +169,9 @@ Collapse the shot axis into a single averaged or summed frame.
 | `on` | required | detector key |
 | `reduction` | `"sum"` | `sum` or `mean` over shots |
 | `purge` | `True` | drop the source key after reducing |
+
+```yaml
+- step: reduce_detector_shots
+  on: epix
+  reduction: mean
+```

docs/steps/loading_filtering.md

@@ -18,6 +18,12 @@ Load scalar and 1D keys from the smalldata HDF5 into named run attributes.
 | `keys` | `[]` | list of HDF5 dataset paths |
 | `friendly_names` | `[]` | attribute names to store them under (parallel to `keys`) |
 
+```yaml
+- step: load_run_keys
+  keys: [ipm_dg2/sum, enc/lasDelay]
+  friendly_names: [ipm, encoder]
+```
+
 ### `load_detector`
 Load a 3D detector stack (one image per shot) with optional crop and transpose.
 
@@ -33,13 +39,24 @@ Load a 3D detector stack (one image per shot) with optional crop and transpose.
 | `rois` | `None` | list of `[start, end]` ranges to crop at load |
 | `combine_rois` | `True` | merge ROIs into one array vs keep separate |
 
+```yaml
+- step: load_detector
+  keys: [epix100/ROI_0_area]
+  friendly_names: [epix]
+  transpose: false
+```
+
 ### `get_run_shot_properties`
 Load the per-shot x-ray / laser status masks from `lightStatus`.
 
 - **Reads:** `lightStatus` (via the run).
 - **Writes:** `xray`, `laser`, `simultaneous` — each `(shots,)` bool.
 - **Parameters:** none.
 
+```yaml
+- step: get_run_shot_properties
+```
+
 ### `droplet_reconstruction`
 Rebuild dense per-shot images from `droplet2photon` sparse photon positions,
 reading directly from the source HDF5. Output plugs into every downstream
@@ -81,6 +98,13 @@ filter key are dropped.
 | `filter_key` | `"ipm"` | per-shot key to threshold on |
 | `threshold` | `1e4` | scalar (keep `> threshold`) or `[min, max]` (keep inside) |
 
+```yaml
+- step: filter_shots
+  on: xray
+  filter_key: ipm
+  threshold: [2e4, 8e4]
+```
+
 ### `filter_detector_adu`
 Zero detector pixels outside an ADU window. Shape unchanged.
 
@@ -93,6 +117,12 @@ Zero detector pixels outside an ADU window. Shape unchanged.
 | `on` | required | detector key |
 | `adu_threshold` | `3.0` | scalar (keep `> t`) or `[min, max]` (keep inside) |
 
+```yaml
+- step: filter_detector_adu
+  on: epix
+  adu_threshold: 5.0
+```
+
 ### `filter_detector_variance`
 Zero pixels whose value barely changes across shots (dead/hot/constant pixels).
 Data-driven alternative to a hand-tuned ADU cut, using sklearn
@@ -107,6 +137,12 @@ Data-driven alternative to a hand-tuned ADU cut, using sklearn
 | `on` | required | detector key |
 | `variance_threshold` | `0.0` | pixels with variance `<=` this are zeroed; `0.0` removes only constant pixels |
 
+```yaml
+- step: filter_detector_variance
+  on: epix
+  variance_threshold: 0.0
+```
+
 ### `hitfinding`
 Keep only shots whose total detector signal clears a threshold.
 
@@ -123,6 +159,12 @@ Keep only shots whose total detector signal clears a threshold.
 Use `min_sum: 1.0` to drop shots that are all-zero after ADU filtering. The
 relative mode breaks down when most shots are dark (median ≈ 0).
 
+```yaml
+- step: hitfinding
+  on: epix
+  min_sum: 1.0
+```
+
 ### `union_shots`
 Keep shots where ALL listed masks are true (logical AND).
 
@@ -136,6 +178,12 @@ Keep shots where ALL listed masks are true (logical AND).
 | `filter_keys` | `[]` | mask names to AND together |
 | `new_key` | auto | output name; defaults to `<on>_<joined keys>` |
 
+```yaml
+- step: union_shots
+  on: epix_ROI_1
+  filter_keys: [simultaneous, laser]
+```
+
 ### `separate_shots`
 Keep shots matching the first mask but NOT the second (A and not B).
 
@@ -148,3 +196,9 @@ Keep shots matching the first mask but NOT the second (A and not B).
 | `on` | required | data/detector key |
 | `filter_keys` | `[]` | `[include_mask, exclude_mask]` |
 | `new_key` | auto | output name; defaults to `<on>_<A>_not_<B>` |
+
+```yaml
+- step: separate_shots
+  on: epix_ROI_1
+  filter_keys: [xray, laser]   # x-ray on, laser off
+```

docs/steps/spectra.md

@@ -23,6 +23,12 @@ For 2D input each row (bin) is divided by its own sum; zero-sum rows are left
 unchanged. If `<on>` carries a companion `_std` array, it is scaled by the same
 factor and written as `<on>_normalized_std`.
 
+```yaml
+- step: normalize_xes
+  on: epix_ROI_1_time_binned
+  pixel_range: [100, 400]
+```
+
 ### `subtract_polynomial_background`
 Fit a polynomial baseline along the spatial axis and subtract it.
 Non-destructive.
@@ -64,6 +70,11 @@ Set the listed run attributes to `None` to free memory mid-pipeline.
 |------|---------|-------------|
 | `keys` | `[]` | list of attribute names to drop |
 
+```yaml
+- step: purge_keys
+  keys: [epix, epix_ROI_1]
+```
+
 ## Cross-run reduction
 
 ### `combine_runs`
@@ -87,3 +98,9 @@ laser-on and laser-off binned data across runs and returning a results dict.
 | `laser_off_suffix` | `"_xray_not_laser_time_binned"` | laser-off data suffix |
 
 Results land in `pipe.results` under the reduction name.
+
+```yaml
+reduction:
+  - step: combine_runs
+    detector_key: epix_ROI_1
+```