← Back to “Processing sections & scripts”
WASP — the core ptychography pipeline (Void-filling, Vanishing-dose, Aperiodic-scan, Shadow-montage-registered, Probe-propagated) core workflow
The recommended end-to-end workflow: calibrate the geometry, map defocus, correct sample drift, then reconstruct. Run roughly top to bottom.
| # | Title | What it does |
|---|---|---|
| 01 | Calibration – frames, patterns and scan | Frame identification, PACBED / bright-field-disk calibration and scan scaling in one step. Three stages, each with its own on/off switch; what one stage returns is forwarded to the next. |
| 01 A | Frame identification (stage of step 01) | Splits a multi-pass acquisition into individual scan frames by detecting fly-back, tagging every position with its frame index. |
| 01 B | Pattern (CBED) calibration (stage of step 01) | Builds a position-averaged CBED (PACBED), detects the bright-field disk, and derives the detector cover angle (DCA), reconstructed pixel size, wavelength, and Ronchigram centre. |
| 01 C | Scan scaling (stage of step 01) | Calibrates the scan step from arbitrary units to Ångström by matching an imaged Quantifoil hole (or the grid mesh) to its known size. |
| 25 | Central defocus – Ronchigram CTF | Estimates a single starting defocus at the hole centre by fitting a CTFFIND-style Ronchigram CTF to a small central region. |
| 11 | Defocus – patches, measurement and map | Lays the patches out (ring, hand-picked or stored list), measures each with parallax or the Ronchigram CTF, and fits the defocus surface through them. Three stages, each with its own on/off switch. |
| 40 | Defocus map – parallax (run by step 11) | Measures defocus in each patch via py4DSTEM tilt-corrected bright-field (parallax), and scores how far each measurement can be trusted. |
| 41 | Defocus per patch – Ronchigram CTF (run by step 11) | Fits the CTF separately inside every patch. A second, independent defocus per patch that fails in completely different circumstances from parallax. |
| 50 | Drift correction | Builds per-layer shadow (bright-field) montages, aligns the temporal layers with MotionCor3, and propagates the measured drift back onto the scan positions; the deep-shadow method (selectable) adds the scan-position refinement, the CTF correction and the resolution measurement. |
| 80 | Ptycho – patches, reconstruction and merge | ROI layout, reconstruction with the chosen engine and the amplitude-phase merge of that reconstruction in one step. Three stages, each with its own on/off switch; what one stage returns is forwarded to the next. Flow charts: how the step works. |
| 44 | Ptycho – SLURM version | The ptychography step with stage B on the Slurm batch queue: every ROI is reconstructed by a job of its own on the GPU cluster, all at once as far as the cluster has room. Stages A and C, and stage B with the batch queue switched off, run as in step 80. |
| 80 A | Ptycho – patch marker (stage of step 80) | Tiles the field of view with an N × N block of reconstruction ROIs, tags each position with its ROI, and estimates the mean applied dose. |
| 85 | Deep shadow | Volumetric reconstruction by refocusing the shadow montage slice by slice, with a half-set height map, an optional 3-D deconvolution and a measured per-position defocus surface. |
| 80 B | Ptychographic reconstruction (stage of step 80) | Runs the py4DSTEM, the Torchslice or the GSharp engine on the ROIs, chosen by one parameter; all stay available as dependent scripts. |
| Ptycho – py4DSTEM (engine of stage B of step 80) | Recursive multi-level reconstruction using the py4DSTEM single-slice engine, with descan removal, learnable probe aberrations, per-position drift, and dose/damage-limited Fourier-space level fusion. | |
| Ptycho – Torchslice (engine of stage B of step 80) | The same recursive multi-level reconstruction using the PyTorch-optimizer Torchslice engine, with spectral dose-weighted Fourier fusion between levels. | |
| Ptycho – GSharp (engine of stage B of step 80) | One joint Torchslice reconstruction over disjoint dose fractions, the damage model applied as a per-fraction filter on the object gradient inside the solver; no levels, no fusion. | |
| 80 C | Amplitude phase merge (stage of step 80) | Low-passes the fused amplitude, high-passes the fused phase and adds the two, so each channel contributes the spatial frequencies it actually resolves. Crops every ROI to a shared size. |
| 99 | Single particle analysis | Picks particles out of the merged image, aligns and classifies them into reference-free 2D classes, and validates the result against a phase-randomised control. |
fd_stack HDF5 file:
10 fixes the diffraction geometry (BF disk, pixel size, Ronchi centre) →
15 tags scan frames →
20 calibrates the scan step to Ångström →
25 gives a starting defocus →
30/40 build a per-position defocus map →
50 drift-corrects the positions →
80 lays out reconstruction ROIs and the dose →
90 or 91 reconstructs one ROI (or every ROI in turn) →
98 merges the reconstructed amplitude and phase into one image →
99 runs single-particle analysis on it. Each step reads the calibration values and datasets the earlier steps wrote (e.g. pacbed_bf_disk, scan_hole, mask/frame_id, data/defocus/map, positions/shadow, mask/patches/ptycho). Each script's ? help button opens its entry below.
01 — Calibration: frames, patterns and scan
Purpose
Everything a 4D-STEM stack needs before any defocus, drift or reconstruction step: which pass of the scan each position belongs to, the geometry of the bright-field disk, and the scale that turns scanning units into Ångström. The three calibrations remain independent scripts, kept in scripts/image/WASP/dependents/ so they do not appear in the function list (they are listed under DEPENDENT SCRIPTS when the step is selected, where a double-click opens them). This step runs the switched-on ones in order as dependent scripts, with the same parameters they would get from the GUI, and their figures, values and progress come back here.
| Switch | Stage |
|---|---|
calib_run_frames | A — frame identification. Splits a multi-pass acquisition into its frames and writes mask/frame_id; a single frame switches the project to the single-frame fallback. Off: the frame mask of the last run stays. |
calib_run_cbed | B — pattern (CBED) calibration. PACBED, bright-field disk, detector cover angle, pixel size, wavelength, Ronchigram centre, descan. Off: the stored values are used by stage C. |
calib_run_scan | C — scan scaling. Detects the carbon hole or the grid mesh in the bright-field scan image and writes positions/angs, data/bfvalues, scan_hole and scan_units2ang. Off: the scan scale is left as it was. |
Each stage keeps its own parameters, listed on its page below; they are all shown on this step. A single calibration can be redone — another hole diameter, another descan setting, a different warm-up count — with the other two switched off.
Results pass from stage to stage
Stage C reads the Ronchigram centre, the detector cover angle and the bright-field disk diameter that stage B returns, and the frame mask that stage A writes to the stack. Run as separate steps these would reach it through the project configuration; run here in one go the next stage is baked before 4d has read the results, so every value a stage writes back (set lines of the results file) is forwarded by the step itself to the stages after it in the same run, and the log says which. A forwarded value is used even when the parameter is locked in the GUI; switch the producing stage off to keep a hand-set value.
Algorithm
- For every stage that is on, in the order A, B, C: reads its source from the
dependents/folder and bakes its header with this step's own values plus everything the earlier stages of this run returned, exactly as the app does for a script it starts, intoproc/of the image. - Runs that copy with the same Python, in the image directory, writing to this step's results file. Its progress is mapped into this step's own band. A failure stops the step, since the stages after it would run on stale values.
- Reads the values it returned and hands them to the next stage.
Results
Whatever the switched-on stages write: see the three pages below.
01 A — Scan calibration – frame id
Purpose
Splits a multi-pass acquisition into its individual scan frames by detecting the scan fly-back (X-direction reversal) and tags every scan position with an integer frame index, so drift correction and reconstruction can treat each pass over the field of view as a separate temporal layer. It uses the scan positions only, no diffraction data is read.
The step also returns scan_single_frame (y for one frame, n otherwise). Parameters that single-frame data does not use carry the visibility rule Frozen if scan_single_frame = y: the damage model, the image fusion and the scan layers of the multi-level reconstruction. The GUI greys them out, label and field, and blocks editing while the flag is y, and says why in the field's tooltip; their values are kept and come back with the next multi-frame stack. Such rules can be set for any parameter or section in the Parameter Editor; see Visibility rules.
Parameters
| Parameter | Role |
|---|---|
| from step 50 (Prepare) | Stage A has no knobs of its own. The dummy positions Scan Pattern into HDF5 file put in front of the pattern are recorded in the header as scan_pattern_dummies and are left out of the step estimate and the motion-based frame detection as warm-up positions. |
| from step 50 (Prepare) | When Scan Pattern into HDF5 file calibrated the positions with the scan generator conversion factor (scan_use_conversion_factor = y), the factor is recorded in the header as scan_units2ang, and the single-frame fallback uses it as the units-to-Angstrom factor. |
| from step 50 (Prepare) | A stack taken on a regular 4D grid (rewritten by Import 4D as 3D dataset, positions from Scan Pattern into HDF5 file) is recorded as ScanMode = Grid4D. It is one frame by construction: nothing is detected, and the single-frame fallback takes the step from the stack (scan_step_4d_nm). |
Algorithm
- Loads
positions/unitsand looks for the pass table of the pattern they came from: Scan Pattern into HDF5 file records the STAR file and the dummy count in the stack header, and the Scan Pattern Generator writes<name>_passes.txtnext to a pattern whose passes cannot be told from the scan motion (SunflowerRim12, Honeytomb9). If the table exists and matches row for row, the frame id is taken from it (rim waypoints flagged inmask/transit) and nothing is detected. Otherwise it histograms position-to-position steps to find the typical in-layer step. - Marks frame boundaries where the X step changes sign (within a frame, X is monotonic).
- Filters out spurious intra-frame reversals (a "sandwich" test against the typical frame length), then labels each run of positions with an incrementing frame index.
Single-frame fallback. If no detector finds a frame boundary the acquisition is a single pass: there is no dose-fractionation movie for MotionCor3, and such a scan is normally taken on the specimen, with no carbon hole in the field. The step then calibrates the scan with the scale Scan Pattern into HDF5 file recorded in the stack — the scan generator conversion factor as units2ang itself, or for a 4D grid units2ang = grid step / measured step, the step in scanning units measured as the median nearest-neighbour distance of the positions — and writes positions/angs exactly as stage C would. A virtual hole stands in for the carbon hole so the later steps keep their geometry: a circle centred on the scanned field, 80 % of its short side across, so that the default defocus ring (defocus_ring = 1.1 × its radius) still falls inside the scanned positions. Its diameter cancels out of every downstream formula (each reads it back as the physical size too), so the montage pixel size stays 1/cf Å. Downstream, stage C sees the single layer and skips the hole detection, and step 50 stops after the shadow montage. The step stops with a message when a single frame is found and the stack carries no scale (run Scan Pattern into HDF5 file again with the conversion factor switched on, or the 4D step set); the frame figure and mask/frame_id are already written by then, so the single frame is shown regardless.
Patterns and positions. The position list describes the scan that was programmed and the pattern stack what the detector recorded, so their counts can differ: dwell or dummy positions before the scan, an acquisition cut short, a dropped frame. Nothing in the two lists says which positions have no pattern, so the join is never guessed. Equal counts pair row for row. Unequal counts need an explicit map, positions/pattern_rows: one integer per pattern, the row of the position list (and of mask/frame_id) it was taken at. Without a valid map the single-frame calibration stops with the evidence it has, for example that the first positions coincide, and with the command that writes the map:
python scripts/proc/scan_rows.py STACK.h5 --show # counts, map, evidence python scripts/proc/scan_rows.py STACK.h5 --head N # the first N positions have no pattern python scripts/proc/scan_rows.py STACK.h5 --tail N # the last N positions have no pattern
The map is validated: one entry per pattern, distinct rows inside the position list, written against the position list now in the stack. positions/angs is stamped with the join it was written under, so stage C and step 50 refuse a positions/angs written under another join, including the common-prefix truncation of earlier versions. mask/frame_id keeps one row per position.
Results
Image: frame_id.png — one panel per detected frame, positions colour-coded.
Data written: the HDF5 dataset mask/frame_id (per-position integer frame index, with a source attribute naming the pass table or the detector) and, from a pass table, mask/transit. No results-file values. Every later step (CBED and scan calibration, defocus patches and methods, drift correction, ptychography ROIs and engines, deep shadow) leaves the waypoints flagged in mask/transit out of its selections, while per-pattern datasets keep one row per pattern.
01 B — CBED calibration
Purpose
The first calibration step. It builds a position-averaged CBED (PACBED) from the raw diffraction stack, detects the bright-field (BF) disk, and derives the reciprocal/real-space calibration every downstream step needs — detector cover angle (DCA), reconstructed pixel size, BF-disk diameter, electron wavelength, and the Ronchigram centre offset. Optionally it computes a per-pattern centre-of-mass "descan" so beam wander is removed before calibration.
Parameters
| Parameter | Role |
|---|---|
KV | Accelerating voltage (kV) → relativistic wavelength. |
CSA | Convergence semi-angle (mrad) |
cbed_descan | y/n: compute per-pattern centre-of-mass offsets, store them, and re-measure the calibration on the descanned PACBED. |
cbed_detector_ellipse | Detector ellipse on/off (default y). n skips the stage: nothing is measured, the patterns are used as recorded and a map stored by an earlier run (data/detector_ellipse) is removed. When on, the mode and the projection parameters below are shown. |
cbed_ellipse | Mode. correct (default): measure the elliptical distortion of the diffraction projection on the dark-field halo and resample the patterns with it when it is significant (the BF disk’s own ellipse also carries the illumination cone’s and is only reported); measure: report it only; manual: correct with the typed pacbed_ellipse_ratio / pacbed_ellipse_angle. |
cbed_ellipse_min | Smallest projection (halo) axis ratio that is corrected (default 1.02, above the ~1 % of cone ellipticity that leaks into the halo); its ellipticity must also exceed five times its odd/even error. |
fd_stack | The working HDF5 file (reads data/dpatterns, writes results back). |
Algorithm
- Detector ellipse. An elliptic BF disk has two possible causes. A projector (or detector) distortion stretches the whole diffraction plane, dark field and shadow image included, and is corrected on the patterns. An elliptic illumination cone makes the disk elliptic but leaves the detector round; it must not be resampled (that stretches the shadow image) and is handled by the ptychography aperture fit. Up to 4096 patterns are aligned by their centres of mass and averaged. Two ellipses are fitted: the half-level disk edge (cone and projection together, reported) and the iso-intensity contours of the dark-field halo at 1.75–2.3 disk radii (the projection: a projector distortion is in them at every radius, while the cone’s ellipticity fades away from the disk). With
cbed_ellipse= correct and a significant halo ellipse, every pattern is resampled with it: magnified across the major axis and left alone along it, counts kept. The rest of the step then runs on the corrected patterns, and the map is stored in the stack asdata/detector_ellipse; every later step that reads patterns (throughstack_io) applies the same resampling. On nion_cryoholder 594 the disk is 1.140 elliptic but the halo only 1.009, so the ellipse belongs to the illumination cone and nothing is resampled; correcting by the disk ellipse there doubled the CTF defocus. - Sums up to the first 10 000 diffraction patterns into a single PACBED image.
- Detects the BF disk: threshold at half-max, trace the longest contour, take its centre of mass and mean radius →
pacbed_bf_disk. DCA = CSA·(detector half-width / BF-disk radius); wavelength fromKV; reconstructed pixel size= λ / (2·DCA).- Records the BF-disk centre minus the geometric detector centre as
RonchiCenterOffsetX/Y. - Optional descan: compute each pattern's centre-of-mass offset, store it, re-centre the frames, and re-measure DCA / pixel size / disk on the aligned PACBED.
Results
Image: detector_ellipse.png — the aligned PACBED with the disk ellipse and the halo (projection) ellipse, the corrected PACBED when a correction was applied, and the disk edge radius against azimuth.
Image: pacbed.png — a sample frame and the PACBED with the detected centre and BF disk overlaid (three log-scaled panels including the descan offset scatter when descan is on).
Data written: results/GUI values pacbed_DCA, pacbed_PIX_itr, pacbed_bf_disk, pacbed_wavelength, RonchiCenterOffsetX/Y, pacbed_ellipse_ratio, pacbed_ellipse_angle (the projection ellipse from the halo; degrees from +column towards +row on the raw detector); the HDF5 dataset data/detector_ellipse (the 2×3 map and whether it is applied); and (descan mode) the HDF5 dataset data/descan (per-pattern offsets).
01 C — Scan calibration – ice hole
Purpose
Converts the scan step from arbitrary units to Ångström by matching an imaged Quantifoil/carbon hole to its known diameter. It forms a bright-field STEM image, detects the hole edge, locates the circle with a Hough transform, and derives the units→Å scale used for correct real-space scan sampling everywhere downstream. It depends on the BF-disk geometry and Ronchi offsets from stage B.
Parameters
| Parameter | Role |
|---|---|
scan_calib_image | Image reference calibration on/off (default y). n: no hole or mesh is detected; the scan is scaled with the scale Scan Pattern into HDF5 file recorded in the stack (scan generator conversion factor, or the step of a regular 4D grid) and a virtual hole (centred on the scanned field, 80 % of its short side) is written, as for a single-frame scan. The detection settings below are hidden while it is off; the step stops with a message when the stack carries no scale. |
scan_calib_source | Detection image: bright field (the BF image summed here), iDPC phase (the integrated DPC phase written by the CBED calibration, sampled at the scan positions) or DPC magnitude (|DPC| in mrad from the same calibration, which peaks on the rim, so the rim is taken as the crest of the raster rather than as a Canny step). Falls back to bright field when the stack has no DPC image. |
scan_shape | Calibration feature: carbon hole (circle) or grid square (the mesh, measured as a lattice). |
scan_hole_size | The known hole diameter (µm); sets the units→Å conversion in circle mode. |
scan_square_size | The grid mesh pitch (µm) — bar plus opening, e.g. ~83 µm for 300 mesh — in grid-square mode. |
| from stage B | RonchiCenterOffsetX/Y, pacbed_DCA, pacbed_bf_disk (read, not GUI). |
Algorithm
- For every position, sums the pixels inside the BF disk (radius 0.45·
pacbed_bf_disk, centred on the Ronchi offset) → a BF-STEM intensity (ice-filled hole bright, carbon dark). - With
scan_calib_source= iDPC phase, the per-position values are instead the iDPC phase grid of stage B sampled at every scan position (carbon positive, hole negative); the BF values are still computed and written. Then bins the scattered values onto a regular square raster (equal bin width on both axes), fills unsampled gaps of the scan pattern with the nearest sampled value so the sparse scan leaves no artificial edges, and normalises to [0, 1] between the 1st and 99th percentile. - Extracts the hole rim with a Canny edge detector, discarding edges outside the scanned support (the closed and filled footprint of the sampled bins) so the border of the scan field cannot be mistaken for the hole.
Grid-square mode replaces the rim and circle steps with a lattice measurement in real space, on the scanned support only (outside it the raster is extrapolation, which on a round scan draws radial streaks across the corners):
- Search. The image is folded onto every period and angle in range; the strongest periodic modulation locates the lattice. A fold cannot tell a pitch from its double, so this period is only a seed.
- Bars. Along each lattice direction the support is projected onto the bars' normal. Bars cross the whole field and survive as dips (or peaks, for bright bars) while contamination and cracks average down. The bar spacing comes from the autocorrelation of both projections together — the shortest lag that also correlates at 2× and 3× itself, which a comb of bars does and texture does not — never from the seed. Each bar is located at the midpoint of its half-depth edges (a flat-bottomed bar has no well-defined minimum), and position is fitted against bar index, so the pitch is the spacing of real bars.
- Checks. The common spacing must divide the fold seed, a direction whose fitted pitch strays from it by more than 6% is rejected, the two directions must agree within 5%, and the fold at the final pitch must stand clear of the scatter. The pitch is the calibration length; bar width and opening are logged alongside. Fewer than three pitches across the scan earns a warning.
- With no measurable lattice (a single cell in view) a single opening is segmented instead, with a warning that it measures the opening, not the pitch. A region spanning 90% of the scanned extent is rejected: that is the scan itself, not an opening.
The detection figure draws the bar centre lines and the measured opening over the raster, and shows the image folded onto one cell — a sharp cross means the pitch and angle are right.
- Runs a Hough circle transform over radii from 0.15 to 0.95 of the raster's short side: every edge pixel votes for the circles on which it could lie, and the strongest peak identifies the hole. The vote is global, so a partial or interrupted rim still determines the circle, and isolated edges from ice contamination or the corners of a hexagonal scan pattern do not accumulate enough votes to displace it.
- Converts the circle from raster pixels back to scanning units, giving the measured hole diameter in scanning units. The known physical diameter is the
scan_hole_sizeparameter, entered in micrometres and converted to Ångström. Their ratio is:units2ang = scan_hole_size·1e4 / measured_diameter
that is, the number of Ångström one scanning unit corresponds to. Every scan position is multiplied by it to givepositions/angs.
If detection fails: no result is produced and no substitute method is attempted. A scan in which the Hough transform finds no circle does not contain a hole edge this method can measure, and the scan step has to be calibrated by other means outside Sharp. Since units2ang scales every distance used downstream (defocus mapping, drift correction and reconstruction alike) an unreliable substitute would be worse than no result at all.
Single-frame scans: when stage A found a single frame (mask/frame_id holds one layer) it has already calibrated the scan from the scale Scan Pattern into HDF5 file recorded in the stack and written positions/angs with a virtual hole stamped on it. No detection is attempted: this step only computes and writes the BF values, saves the BF scan image at the step-calibrated pixel size (fd_BF_image.mrc and bf_scan_map.png), re-issues the stored virtual hole and scan_units2ang, and finishes. The hole and mesh settings are ignored in that case, and the step stops with a message if the single-frame stack carries no step-calibrated positions (run Scan Pattern into HDF5 file with the conversion factor or the 4D step, then stage A again).
Patterns and positions: patterns and scan positions are paired row for row only when their counts agree. When they differ the step uses the explicit map positions/pattern_rows if the stack carries a valid one, and otherwise stops with the evidence it has and the command that writes the map (see stage A). positions/angs is stamped with the join it was written under; in a single-frame scan the positions/angs written by stage A must carry the join the patterns are read with here, or the step stops and asks for stage A to be run again.
Results
Images: ice_hole_calibration.png — the BF map with the fitted circle, centre, diameter, and a set-vs-measured annotation. ice_hole_detection.png — a detection diagnostic showing the BF raster and the Canny edge map, with the circle as voted by the Hough transform (orange, dotted) and the refined circle used for the calibration (green, dashed). Consult this figure first if a fit appears incorrect, as it shows whether the hole rim was detected as an edge at all.
Data written: HDF5 positions/angs (positions in Å), data/bfvalues, and a hole attribute; results/GUI scan_hole and units2ang.
25 — Central defocus (Ronchigram CTF)
Purpose
The same measurement is available in step 41 with defocus_ctf_region = center, which also returns defocus_ctf.
Estimates a single defocus value at the hole centre by fitting a CTFFIND4-style Ronchigram CTF (via the bundled ctf_lmu.py) to the raw patterns of a small central region. It provides a robust starting defocus for ptychography and is the first quantitative defocus output once the geometry is calibrated.
Parameters
| Parameter | Role |
|---|---|
defocus_ctf_fraction | Radius of the central region as a fraction of the hole radius (e.g. 0.3). |
defocus_ctf_clusters | Advanced: KMeans patches used only for a per-cluster spread cross-check. |
defocus_ctf_device | Advanced: cpu/cuda torch device for the fit. |
defocus_ctf_descan | Advanced (y/n): remove the BF-disk wander before fitting. |
| from prior steps | scan_hole, pacbed_bf_disk, RonchiCenterOffsetX/Y, CSA, KV. |
Algorithm
- Selects scan positions within
defocus_ctf_fraction·(hole radius) of the hole centre; their raw patterns feed the fit. - Optionally descans each pattern (using the shared
data/descanwhen present) so the BF disk is centred. - Computes a Gaussian-windowed incoherent power spectrum and fits a CTFFIND4-style Ronchigram CTF to the mean spectrum for a global defocus (plus per-cluster fits for spread).
Results
Image: defocus_ctf.png — the ROI map, the log Ronchigram with the fitted defocus, and a radial profile with the CTF model overlaid.
Data written: the results/GUI value defocus_ctf (Å). No HDF5 writes.
11 — Defocus: patches, measurement and map
Purpose
Defocus need not be computed over the whole field of view. This step lays out square patches, measures the defocus inside each of them, and fits a surface through the per-patch values that is evaluated at every scan position. It runs as three stages, each with its own on/off switch, so the layout can be redone without re-measuring, a measurement re-run on the stored layout, or the map refitted in seconds from the values already on disk. A stage that is off is skipped and the next one reads what the last run of the skipped stage left behind.
| Switch | Stage |
|---|---|
defocus_run_patches | A — patch layout. Places the patches (automatically on a ring around the hole, by hand on the BF scan, or replayed from a stored list) and tags every scan position with its patch in the HDF5 mask mask/patches/defocus. Off: the mask already in the stack is used. |
defocus_run_measure | B — measurement. Runs the method chosen by defocus_patch_method on the patches: parallax (step 40) or ronchigram ctf (step 41), as a dependent script. Off: the per-patch JSON that method wrote on its last run is used. |
defocus_run_fit | C — defocus map. Fits a polynomial surface through the chosen patches and writes it as the per-position map data/defocus/map. Off: the map in the stack is left as it was. |
Parameters — stage A (layout)
| Parameter | Role |
|---|---|
defocus_patch_mode | How the patches are obtained. Automatic ring + center (default) places the ring and one more patch at its centre, numbered after the ring patches, which measures the defocus where the reconstructions are usually made and anchors the defocus surface in the middle. Automatic ring + small ring + center adds a second ring half way between the ring and the centre with about half as many patches, keeping the spacing of the outer ring, rotated by half a step so its patches sit between the outer ones, numbered after the outer ring and before the centre patch: three radii constrain a quadratic or cubic surface far better than one ring and a centre, at half again the measurement time. Automatic ring is the ring alone, without the centre patch. Center is the single centre patch alone, with no ring, overlap or fill check; stage C then uses its defocus everywhere as a constant. All four work without a display. Interactive picking opens a window on the BF scan. Stored list replays defocus_patch_list with no window, which makes a hand-picked layout reproducible on re-runs and on headless machines. |
defocus_patch_size | Side length of each square patch (Å). In the picker it is also the size of a patch added with a single click. |
defocus_patch_num | Number of patches placed around the ring. |
defocus_patch_min_pct | Fill check: a patch holding fewer than this percentage of the patterns of the fullest patch (default 50) is dropped and the rest renumbered; 0 switches the check off. |
defocus_ring | Ring radius as a multiple of the hole radius. |
defocus_patch_list | The patch bounds themselves, as MINx,MAXx,MINy,MAXy groups separated by semicolons (Å). Every run of stage A overwrites it with the layout it ended up with, so it is normally filled in for you rather than typed. Per-image, since the patches follow that image's hole. |
The picker window
Seeded with defocus_patch_list if it already holds a layout, otherwise with the automatic ring — so re-running continues from the last layout instead of starting over.
| Mouse / key | Action |
|---|---|
| left-drag | Add a patch with the dragged bounds. |
| left-click | Add a square patch of defocus_patch_size centred on the click. |
| right-click on a patch | Delete it. The rest renumber. |
| r / c / u | Back to the automatic ring / clear all / undo the last one. |
| Enter or q | Accept the layout and close. |
The toolbar's zoom and pan work as usual and are ignored by the picker, so navigating never leaves a stray patch behind. Closing the window with nothing selected falls back to the automatic ring rather than writing an empty mask.
Parameters — stage B (measurement)
| Parameter | Role |
|---|---|
defocus_patch_method | parallax or ronchigram ctf: the method stage B runs, and therefore the source of every patch value stage C fits through. The two remain independent scripts with their own parameters, kept in scripts/image/WASP/dependents/ so they do not appear in the function list; they are listed under DEPENDENT SCRIPTS when the step is selected, where a double-click opens them. |
| the parameters of steps 40 and 41 | Shown here so they can be set without leaving the step; the ones of the method not chosen are ignored. |
defocus_patch_method_used | Output — the method last run. |
Parameters — stage C (map)
| Parameter | Role |
|---|---|
parallax_plane_patches | Which patches enter the fit at all. Blank or all uses every one; 1,2,4,5,7 keeps those; -3,-6 drops those. Plain and negated entries cannot be mixed. |
defocus_plane_order | Order of the fitted surface: 1 = plane (3 terms), 2 = quadratic (6 terms), 3 = cubic (10 terms). A higher order follows a bent film but needs more patches than terms, with one of redundancy; the step lowers the order by itself when the selection is too small. |
defocus_map_points | Stage C fits the surface through the picked patches (default) or through the ice windows of the sliding-window CTF map (defocus_ctf_sliding), carbon and edge windows and the map's outliers left out. Hundreds of points instead of six, so order 2 or 3 is constrained and the map the drift correction and the ptychography read follows the buckle of the ice. |
defocus_patch_mode = Carbon rings + ice grid, defocus_rim_patch_nm, defocus_ice_patch_nm, defocus_rim_rings | A layout for the buckling of the ice: concentric rings of annular sectors (150 nm wide, touching, following the curved rim) on the carbon just outside the hole edge as the flat reference, and, inside the hole, concentric rings of wider sectors (300 nm, the smallest that fits reliably on thin cryo ice) running inward from the edge and a central disc with the area of one sector, so every ice patch holds the same number of patterns; the space left between the innermost ring and the disc stays a gap. The CTF does not care about the shape of the region it sums. The fill check judges patches per area so the small rim squares survive beside the large ice ones. |
defocus_map_model, defocus_spline_smooth | Stage C surface: the polynomial of the chosen order, or a thin-plate spline through the points, the smoothest surface with a plane as its tail, flat where the points are consistent (carbon rings) and bent where they bend (ice). Smoothing auto (leave-one-out), 0 (through every point) or a number. |
One bad patch drags the whole surface. On a real dataset where one patch of six had failed in parallax, the plane fitted through all six had an RMSE of 4046 Å and swung the per-position defocus from −28188 Å to +2718 Å — through focus, which is nonsense for a field the CTF says is flat. Leaving that patch out with parallax_plane_patches, with stages A and B switched off, refits the map in seconds without re-measuring anything.
Algorithm
Stage A — layout
- Builds the ring layout: patch centres at equal angular spacing on a circle of radius
defocus_ring·(hole radius) around the hole centre, each a square of sidedefocus_patch_size. In Automatic ring + center one more patch of the same size is added at the ring centre, numbered last. The hole geometry is taken from the copy stamped on the positions by the scan calibration, so the ring is drawn in the frame of the positions it is plotted on. - Depending on the mode, uses that layout, opens it in the picker for editing, or replaces it with
defocus_patch_list. - Tags every scan position with its 1-based patch index (0 outside all patches), checks the final layout for overlaps and drops the patches that fail the fill check.
Stage B — measurement
- Reads the chosen method's source from the
dependents/folder and bakes its header with this step's own values, exactly as the app does for a script it starts, intoproc/of the image. - Runs that copy with the same Python, in the image directory, writing to this step's results file, so its figures, values and progress appear here. A failure of the method fails this step. It reads the patch mask from the stack, so with stage A off it measures the layout of the last run.
Stage C — map
- Recomputes each patch's bounding box and centre from the patch mask and the scan positions, exactly as the parallax method derives them, so the centres fitted through are the same ones.
- Reads the per-patch defocus from the JSON of the chosen method —
parallax_update.jsonordefocus_ctfpicker.json— never from the other method's file, which may be left over from an earlier run with other settings. The CTF value carries no sign — ring spacing is the same either side of focus — so its magnitude is given the sign of the parallax consensus, and with no parallax at all to consult it is taken as underfocus, which is what step 40 writes. - Least-squares fits a polynomial surface of the chosen order through the selected patches and evaluates it at every scan position: order 1 is the plane
d = a·x + b·y + c, order 2 addsx²,xy,y², order 3 the cubic terms. The fit runs in coordinates centred on the patches and scaled to their extent, so the higher orders stay well conditioned. With fewer than three selected patches even a plane is undetermined and their mean is used everywhere, which is what the single-patch Center layout gives. - Compares every patch against that surface, the excluded ones included, so how far out the dropped ones really were is visible.
Results
Stage A. Image defocus_patches.png — the BF map with the ring and the numbered patch squares. Data: the HDF5 dataset mask/patches/defocus (per-position patch index) and the final layout back into defocus_patch_list.
Stage B. Whatever the chosen method writes (see steps 40 and 41), and defocus_patch_method_used.
Stage C. Images defocus_plane.png — the measured patches (dropped ones dashed in red) and the fitted per-position map — and defocus_plane_residuals.png — every patch against the surface, judged both against the fit's own RMSE and as a fraction of the defocus, so a uniformly bad fit cannot look uniformly fine. Data: HDF5 data/defocus/map (per-position defocus, Å, with the fit as dataset attributes: plane_order, plane_kind, the polynomial coefficients in the centred, scaled coordinates, and for every order plane_c = the defocus at the scan origin and plane_a/plane_b = the gradient there; the drift correction plans with the mean of the per-position map and falls back to plane_c only when the map holds no values). The parallax method's own per-patch map in data/defocus/parallax is left untouched. Values returned: parallax_plane_used, parallax_plane_eq, parallax_plane_rmse, defocus_plane_source_used.
40 — Defocus map (parallax) — run by step 11
Purpose
Measures the local defocus inside each patch using py4DSTEM tilt-corrected bright-field (parallax) reconstruction, and scores how far each measurement can be trusted. A plane is also fitted here through all the patches at once; when some of them are bad, the map fit of step 11 leaves the bad ones out (parallax_plane_patches) instead of accepting this one.
Parameters
| Parameter | Role |
|---|---|
parallax_binBy | Q-space binning before parallax (speed). |
parallax_alignment_bin_values | Coarse→fine alignment-bin schedule for the reconstruction. |
parallax_probe_power | Contrast-stretch exponent for the probe-size fit. |
parallax_force_transpose, parallax_update_force_rotation_deg | Force the scan/detector orientation so every patch stays on the same branch of the rotation/defocus 180° ambiguity. The rotation is a global parameter, −90° by default, since it follows from the microscope's scan wiring rather than from the image; leave it blank to have it fitted per patch instead. |
parallax_save_metadata | Write the five diagnostic PNGs per patch. Worth leaving on: they are what tells you why a patch scored badly. |
| from prior steps | KV, CSA, and mask/patches/defocus (aborts if missing). |
Algorithm
- Resamples each patch's irregular scan onto a regular square grid (each cell takes its nearest scan point's full pattern — never blended, so the sub-pixel disk shift is preserved). Cells with no scan point within two scan steps are masked out: they carry the nearest edge pattern copied outward, which against a straight edge shows up as stripes across the reconstruction. That happens wherever the patch has a hole, most often because another patch overlapped it.
- Runs py4DSTEM parallax on each patch: virtual tilt-corrected BF images, coarse-to-fine cross-correlation alignment, then an aberration fit for the defocus (C1).
- Scores the measurement (below) and fits a plane
d = a·x + b·y + cthrough the patch defoci (constant mean for 1–2 patches), evaluated at every scan position.
The quality score
C1 is read straight off the measured BF shift field, so the score asks whether that shift field is worth believing: score = 85 × (signal × fit) + 15 × trace, out of 100.
| Term | Meaning |
|---|---|
| signal | RMS shift magnitude in scan pixels, full credit at one pixel. On a patch with no localised contrast — a smooth carbon edge and nothing else — the cross-correlation peak sits at zero for every sub-aperture and this collapses to a fraction of a pixel. |
| fit | r² of the linear aberration model shifts = angles · m, which is the very fit C1 comes out of. Noise scores near zero. |
| trace | Relative drop of the alignment error trace. Weighted low on purpose: measured traces improve by well under a percent even on patches whose C1 is confirmed by an independent CTF fit, so it barely discriminates. |
signal and fit multiply because they are conjunctive — the shifts have to be real and follow the model. Adding them lets either carry the score alone, and both real failure modes do exactly that: r² is scale-free, so a shift field a tenth of a pixel across still fits a defocus pattern beautifully while measuring nothing, and a field of large noise has the magnitude but no structure.
patch_<id>_preprocess.png shows whether the patch has any localised contrast to cross-correlate — isolated specks and particles, not just a smooth carbon edge. patch_<id>_shifts.png shows the measured shift field: a clean radial fan (rotated by the scan/detector angle) means it worked, a field of dots means the cross-correlation never moved. The usual fix is to move that patch somewhere with visible features, or to switch the method of step 11 to the Ronchigram CTF instead.
Results
Images: defocus_map_update.png (per-patch field, labelled with the patch number and its C1, plus the per-position plane fit), convergence_table_update.png (per-patch C1, rotation, shift RMS, r², trace drop and score), and five diagnostics per patch in parallax_update_diagnostics/ when metadata is saved — probe size, average BF, convergence curve, shift field and CTF fit, each linked from the Results panel.
Data written: HDF5 data/defocus/parallax (per-position defocus, Å, with plane_a/b/c attributes) and parallax_update.json, which holds the per-patch numbers and is what steps 41 and 45 read.
41 — Defocus per patch (Ronchigram CTF) — run by step 11
Purpose
Step 25 fits one CTF at the middle of the hole. This one fits the same CTFFIND4-style Ronchigram model separately inside every patch the picker laid out — the same patches parallax measures — so the two methods can be compared patch by patch.
They are worth comparing because they fail in unrelated ways. Parallax needs localised contrast for its cross-correlation and returns a near-zero defocus on a featureless patch while its error trace still looks converged. The CTF reads Thon rings out of the power spectrum and does not care whether the patch has features, but it does need enough patterns and enough ring contrast. A patch where the two disagree is a patch to look at; a patch one of them measures badly is often measured perfectly by the other.
Parameters
| Parameter | Role |
|---|---|
defocus_ctf_region | patches (default): fit inside every patch of the picker, as described here. center: fit once on the central region step 25 used, and return the result as defocus_ctf (see the note below). |
defocus_ctf_fraction | center only: radius of the central region as a fraction of the hole radius (e.g. 0.3). |
defocus_ctf_clusters | KMeans sub-clusters per patch, each fitted on its own, for the consistency cross-check. |
defocus_ctf_device | cpu / cuda torch device for the fit. |
defocus_ctf_descan | Remove the scan-dependent BF-disk wander before fitting, so the Thon rings add coherently. |
defocus_ctf_sliding, defocus_ctf_window_nm, defocus_ctf_stride_nm | Sliding-window defocus map (off by default): a square window (200 nm) moved over the whole scanned field in steps (100 nm), carbon included, with the CTF fitted at every stop. Windows are labelled ice, carbon or edge by the hole; a plane is fitted through the carbon windows and the ice is reported against it, the buckling of the film (defocus_ctf_buckle, the value at the hole centre in Å, positive = further from focus than the carbon). Writes defocus_ctf_sliding.json, data/defocus/ctf_sliding defocus_ctf_sliding.png (map over the BF scan; the ice surface coloured by its deviation from the carbon plane with the carbon windows and their plane; profiles through the hole centre along x and y, the carbon windows in grey) and defocus_ctf_sliding_3d.html, the surface interactive in the browser. The window cannot be much smaller than 200 nm: the fit needs thousands of patterns. |
| from prior steps | pacbed_bf_disk, the Ronchi centre offsets, CSA, KV, and mask/patches/defocus (patches only; center reads the hole stamped on positions/angs, or scan_hole). parallax_update.json is read too, purely to print the parallax number beside the CTF one. |
The quality score
Two terms, score = 60 × cc + 40 × consistency, out of 100.
cc is the fit's own correlation coefficient, ramped from a measured noise floor. The floor is not a guess: fitting patterns with the ring structure destroyed — Poisson noise on the PACBED, and pixel-shuffled patterns — returns cc around 0.08–0.15 together with a meaningless C1, while fits that agree with each other and with step 25 sit at 0.32–0.46. cc also climbs with the number of patterns (about 0.18 at 50 patterns against 0.44 at 1500 on the same patch), so a thin patch scores low for a real reason.
consistency is the coefficient of variation of the sub-cluster defoci. Unlike the parallax score these two are added, not multiplied: a patch with a good cc but scattered sub-clusters may simply have a real defocus gradient across it, which is worth knowing rather than a disqualification.
mask/patches/defocus, so an overlapped patch loses the same points here as it does in parallax. It does not suffer the same damage, though: this step never resamples onto a grid, it just averages power spectra over an unordered set of patterns, so a missing region only means fewer patterns in the average. Measured on a patch that lost 15% of its points, the CTF defocus moved by 1.6%, against 32% for parallax on the same patch.
defocus_ctf_region = center the step does what step 25 does, with the same fit, descan, sub-cluster cross-check and score: the region is the scan positions within defocus_ctf_fraction × the hole radius of the hole centre stamped on positions/angs by the scan calibration (the scan_hole value when the stamp is missing), or of the centre of the scanned field when the hole centre lies outside its inner 80 %. It returns defocus_ctf, the starting defocus the reconstructions and the drift correction read, writes the three-panel figure defocus_ctf.png (region on the BF scan, region-averaged Ronchigram, radial power spectrum with the fitted CTF) and defocus_ctf.json. No patch mask is needed, so it can run before the patch picker. The per-patch outputs below are not written in that mode.
Results
Images: defocus_ctfpicker.png — the patches coloured by CTF defocus, and CTF plotted against parallax with a 1:1 line, where anything off the diagonal means one of the two failed. defocus_ctfpicker_table.png — per-patch defocus, cc, sub-cluster spread, score, and the difference from parallax, flagged when it exceeds 20%.
Data written: defocus_ctfpicker.json (read by the map fit of step 11) and defocus_ctf_patch_mean back to 4d. Nothing is written to the HDF5 stack.
50 — Drift correction (shadow montage + MotionCor3)
Purpose
Two methods, one step. drift_engine selects the standard method (this section) or the deep shadow method, which adds the scan-position refinement against the data, the per-pattern CTF correction, the damage model and the half-set resolution measurement; the deep-shadow knobs are those of the Deep Shadow section (shared with step 99). Either runs as a dependent script of step 50, baked with its parameters; drift_engine_used records which ran last and therefore which method positions/shadow comes from.
Corrects specimen/stage drift before reconstruction. It reassembles the diffraction patterns into per-layer bright-field "shadow" montages, treats the temporal layers as a movie, and aligns them with MotionCor3 software. The per-frame drift is interpolated onto every pattern by acquisition time and applied to the scan positions, iterating to shrink the residual drift.
Parameters
Method: drift_method (global = one rotation + conversion factor from shadow sharpness; interactive = the same two numbers fitted from alignments you make by hand; local = a per-position defocus map from Ronchigram-CTF fits on KMeans patches, every pattern Fourier-resampled onto one common defocus, then the same global sweep on the corrected stack — it also writes the defocus map to data/defocus/ctf), drift_clusters (patches and minimum patterns per patch for that map), drift_device (auto / gpu / cpu: where the rotation/cf sweep, the deep-shadow back-projections and position refinement run - a CUDA GPU on Linux and Windows or the Metal GPU of a Mac when there is one, the CPU otherwise; the results agree to float32 rounding. The local method's CTF fit moves to the GPU only with gpu: its patch fits sit near the noise floor, where float32 arithmetic can flip a borderline patch). The hole diameter is not asked for again here: stage C of step 01 scales the positions so the fitted circle measures exactly the diameter entered there, so the third component of scan_hole already is that diameter (in Å) and the step reads it from there. Re-entering it could only contradict the calibration the positions carry.
Shadow montage & search: shadow_defocus, shadow_res1/shadow_res2 (sharpness band), the rotation search (shadow_rotation, shadow_rotation_shortcut, shadow_rotation_range, shadow_number_rotation; the sweep is centred on shadow_rotation, the DPC estimate the CBED calibration fills in or the last refined value, and runs over ± the range about whichever of that orientation and the one 180° away scores better, since the DPC cannot tell them apart), the conversion-factor search (shadow_cf, shadow_cf_shortcut, shadow_cf_range, shadow_number_cf), shadow_njobs (global parallel-worker count, default 1 - each worker holds its own montage and FFT, so raising it multiplies peak memory for a sub-linear speedup; this step stamps its sweep with torch on the drift_device instead and needs it only when torch is missing), the optional search crop (shadow_crop_doit, shadow_crop_nm), shadow_crop, shadow_invert, and the montage pixel size (deep_pixel_size, 0 = native).
Interactive alignment (drift_method = interactive): two windows open - interactive - pattern for the pair alignment and its fit, interactive - scaling for the montage preview and the sliders. They share one state (a fit reaches the sliders at once) and every key works in either. The pattern window shows two neighbouring bright-field disks in the montage's own grey, the neighbour laid over the reference at 50% on a black ground, placed at the separation drift_interactive_cf0 implies. Slide the neighbour with the arrow keys and swing it about the reference with ,/. until the shared specimen detail lines up; t cycles the top disk 50% / on / off so you can blink the pair, s cycles the display smoothing, and a accepts the pair and steps on. Only patterns from the first temporal layer are offered: two patterns from different layers were recorded a whole pass apart, so specimen drift sits in the measured offset on top of the scan step, and biasing cf with the very drift this step exists to remove would corrupt every montage built from it. The disks are smoothed for display (normalised convolution, so the masked rim is not dragged inward); none of it reaches the fit, which uses your offsets alone. If a disk looks noisier here than the same disk inside a montage, that is scale, not data: a montage is written at full canvas size and shown ~5× downsampled, so each screen pixel there averages ~25, while this tool magnifies one 192 px disk ~3× so alignment can be judged to a pixel. The default smoothing sits near the effective smoothing a montage view already has. After drift_interactive_pairs of them, Calculate CF fits the values — its panel plots the component of each offset along the fitted direction against separation, not the offset's length, because the fit is a vector least squares: disagreeing per-pair directions shorten the resultant and pull cf below every point while the lengths stay put, so a length plot would draw a line missing its own points. The projection is what cf regresses, so the line passes through by construction, points are coloured by direction error, and a spread over 10° names the worst pair to redo. Apply rebuilds a montage preview at them. Two sliders under the preview also set cf and the rotation directly, with the preview following live — so the montage can be the target itself, sharpening as the values approach the truth. The two routes feed one pair of numbers: Calculate CF pushes its fit onto the sliders and a later slider move overrides it, so a fit can be nudged rather than taken whole. [/] nudge cf and ;/' the rotation (finer with f). Whatever the sliders read at close is what the step uses; closing untouched leaves the stored values standing.
The montage stamps pattern i at rotate(pos_i, theta) * cf, so a specimen point lands on one canvas pixel in every frame only when the shadow content between two patterns is displaced by dp = -cf · R(theta) · dpos. Aligning a pair measures dp directly. Both controls feed that same vector — translating along the separation pins cf, swinging across it pins the rotation — so as complex numbers the set is one linear model z_p = w·z_pos, solved exactly, with cf = |w| and theta = angle(−w). A single aligned pair already determines both (two unknowns, one 2-D offset); more pairs average down aiming error, and the residual only means something from three up. The starting cf need not be close — the offset you drag out is the measurement — but it sets which separations are offered, so that the two disks always still overlap.
Reach for it when the global sweep converges somewhere wrong: that sweep searches cf over a range centred on the stored value, so a stored value far from the truth puts the answer outside the range entirely and re-running cannot help. A minute of hand alignment gives a value to centre the range on. Needs a display; with none, the step says so and falls back to the stored values rather than failing.
Local method (drift_method = local): a single cf is exact for one defocus only — a pattern's object-space pixel size is proportional to its defocus, so across a tilted or buckled specimen the patterns image the object at different magnifications. Rather than varying cf per position (what the former local and CTF methods did), this method corrects the patterns. (1) The scan is cut into KMeans patches (drift_clusters); for each, the raw patterns are descanned onto the common BF centre, Gaussian-weighted, zero-padded to 512 px and summed incoherently in Fourier space, and a CTFFIND4-style Ronchigram CTF is fitted to the result — the same fit and settings as step 41 — giving a defocus and a fit correlation per patch. Patches whose correlation is below the measured noise floor (0.15) are dropped while three remain, as are patches whose defocus is more than 50% off the median of the others; a map whose resampling factors would exceed 2 stops the step before resampling, and the sweep refuses a canvas above 2.5 Gpx rather than running out of memory. A polynomial surface of degree ≤ 2 through the kept values, clipped to a margin around their range, assigns a defocus magnitude to every pattern (written to data/defocus/ctf, with the patch table and the reference defocus as attributes). (2) Every raw pattern is magnified by d_i / d_ref about the BF-disk centre by exact band-limited interpolation, with d_ref the map minimum so that every factor is ≥ 1 and every resampled disk stays filled with real data; the disk diameter is untouched, and the BF mask is cut afterwards with each pattern's descan centre carried through the magnification. (3) The global rotation/cf sweep runs on the corrected stack, centred on the cf the reference defocus itself implies (cf = hole_size·D_px/(2·hole·CSA·d_ref)): every pattern now sits at d_ref, and it is a defocus this step has just measured on this stack, so it cannot be stale the way a planned value can. The planned defocus does not set the centre for this method; the notebook's seed (geometric cf of the planned defocus × mean(map)/d_ref) is printed as a cross-check. The refined cf describes the montage at d_ref and is written back to shadow_cf like the global method's. drift_local_map.png shows the map with the patch fits, the distribution of the resampling factors, and the most-resampled pattern before and after.
Subset: shadow_frames keeps only the first N temporal layers and shadow_area keeps only the given central fraction of the field (the points nearest the centroid of the scan). They compose, and both act before anything is measured — so they shrink the data the rotation/CF search, the MotionCor3 alignment and the corrected positions are all derived from. Use them to get a quick look, or to cut away a bad periphery; not to produce the positions you intend to reconstruct from.
Hole only (deep engine): shadow_hole_only reconstructs only the patterns within the ice hole plus a carbon margin (shadow_hole_margin_nm, 100 nm by default) plus one shadow footprint, since particles on the carbon are never used; every stage after the selection costs in proportion to the pattern count. The margin gives the MotionCor3 alignment and the conversion-factor search the carbon edge to lock onto. The canvas is not shrunk, so the montages keep their size, centre and MRC origin; the MRC montages carry the ice inside the hole only, with the outside replaced by noise matched to the ice in mean and ring power (shadow_hole_fill = matched noise, which a particle picker sees as empty ice with no edge to pick along) or by zero. The PNG overview keeps the full reconstruction, and drift_hole.png shows the selection on the BF-STEM image, the montage as written and the spectra of the ice, the fill and the rim that was removed.
Detector frame: shadow_flip_x, shadow_flip_y and shadow_transpose map the detector axes onto the scan axes. That mapping is a property of the camera, its mounting and the acquisition software rather than of the method, so it has to be set once per setup. They are applied in the fixed order flip X, flip Y, transpose — these do not commute, since transposing and then flipping X is the same as flipping Y and then transposing. The defaults (n, n, y) reproduce exactly the unconditional transpose the step applied before the switches existed, so existing projects are unaffected until one is moved. A wrong mapping does not announce itself: the montage either fails to align at all, or aligns into a mirrored image that looks perfectly plausible until it is compared against something else.
Contrast: shadow_invert (advanced) reverses black and white in every shadow montage the step writes — before, aligned sum, after, and the diagnostics — by negating the bright-field frames they are stamped from. The sign of the defocus decides which way round the contrast falls, so an over-focus and an under-focus dataset come out looking opposite; this flips one onto the other. Nothing measured moves: the sharpness metric is a power spectrum and MotionCor3 aligns by cross-correlation, and neither can see a global sign flip. The same knob is shared with the Shadow Montage engine step, so the two produce montages the same way up.
Montage pixel size: deep_pixel_size (global; one knob shared by both drift methods and the deep-shadow step; 0 = native). A shadow montage has no free sampling: one canvas pixel is one detector pixel projected onto the specimen, so the pixel size follows from the refined conversion factor and lands on a different value for every acquisition, defocus and CF refinement (it is printed as Computed pixel size and stamped into the MRC headers). A positive value resamples the montages the step writes onto that constant pixel size, in Å per pixel, so shadow_original, shadow_updated and aligned_sum — and the montages of every other acquisition in the project — come out on one grid and can be compared or stacked directly. Coarser than native downsamples by a Fourier-space crop, exactly anti-aliased; finer than native only re-grids the montage, since interpolation cannot recover detail the native sampling never recorded (a factor beyond 16× either way is refused as a typo, and the run falls back to native). Nothing measured moves: the rotation/CF search, the MotionCor3 alignment — still run on native-sampling frames at the native -PixSize — and the corrected positions written to positions/shadow are all computed before the resampling. drift_motion.png and drift_search.png keep the sampling they were computed at.
Cropping: two independent settings share a similar name. shadow_crop_doit / shadow_crop_nm restrict the rotation and conversion-factor search to a small square at the centre of the scan; the rotation angle and global CF are scan-wide constants, so this yields the same result considerably faster, and the result is applied to the whole dataset. shadow_crop is separate and controls the montage window used for alignment: each montage is reduced to a centred square retaining the middle 1 − 2/shadow_crop of the shorter canvas side.
MotionCor3: mc3_niter (outer refinement passes), mc3_patch, mc3_bft, mc3_Iter, mc3_Tol, mc3_FmRef, mc3_cs, mc3_ampcont, mc3_gpu. The MotionCor3 executable is a system-wide preference, app_motioncor3 (MotionCor3 executable under Preferences, section Drift Corrector Software Setup, next to Motioncor2): the full path to a MotionCor3 binary, by default the one of the lab's site installation of 4d (/opt/lbem-site/4d/kernel/mrc/bin/MotionCor3, which every node of the Slurm queue mounts). Empty, or a path that does not exist (with a warning in the log), it is the MotionCor3 that comes with this 4d (built into its kernel/mrc/bin folder; on a Mac it runs on the GPU through Metal). On the Slurm queue, that one runs from 4d's copy in the shared directory, together with the CUDA libraries it was built with, which the nodes need not have. A typed path that does not exist falls back to the one that comes with 4d, with a warning in the log. An external CUDA build resolves its CUDA libraries through the system loader, so a CUDA in a private prefix must be on LD_LIBRARY_PATH in the environment 4d itself is launched from. Reads mask/frame_id and the calibration values from steps 10/20. The dose per frame for MotionCor3's weighting is not a knob: the step measures the dose of the acquisition as stage A of step 80 does (every count over the convex hull of the scan, through CPE) and divides it by the number of frames.
Algorithm
- Builds a bright-field image per pattern (BF-disk mask, in-disk mean subtracted).
- Refines the scan-to-image rotation and conversion factor by the chosen method (global sharpness sweep, hand alignment, or — local — a CTF defocus map and pattern resampling followed by that sweep).
- Splits the patterns into per-frame layers and stamps each layer onto a shared canvas, so that all layers share one set of dimensions. Every montage is reduced to a centred square window and Hann-tapered.
- Zero-pads the tapered layers to a frame size whose prime factors are small (2, 3, 5, 7) and stacks them into a movie. MotionCor3 constructs its Fourier transforms with cuFFT, which cannot build a plan for a dimension carrying a large prime factor; padding to a compatible size avoids this while preserving the full cropped field of view. Applying the taper before padding leaves no intensity step where the padding begins.
- Runs MotionCor3 on the movie and removes the padding from the aligned sum; interpolates each frame's shift onto every pattern by acquisition time and applies it to the positions.
- Repeats for
mc3_niterpasses until the drift converges.
Memory (deep engine): the whole bright-field stack stays in memory (34 GB for 245 k patterns of 192 × 192 pixels), and every montage is built on a fine grid at twice the output sampling before being brought down to it in Fourier space. The canvas side is therefore rounded up to a size whose prime factors are small (2, 3, 5, 7), for the same reason as the MotionCor3 frames above: the transform of a side with a large prime factor needs a workspace several times the array, on the GPU (cuFFT) and on the CPU (pocketfft) alike — an 18 110-pixel canvas asked the GPU for 26 GB, failed, and fell back to a double-precision transform on the CPU. The fall-back now works in single precision on the half spectrum, the GPU is asked only when it has room, and the final montage, its two halves and the whole-set montage are built one after the other, so one pair of fine-grid buffers is alive at a time instead of three. The scan-position refinement gathers each half set’s in-disk pixels inside the back-projector, row block by row block, instead of first copying half the stack (17 GB, twice per pass). This matters because the workstation’s session manager (systemd-oomd) stops a step whose memory pressure stays high for twenty seconds, long before the memory is exhausted; the app reports it as “killed by a signal” with no traceback. The import step’s manual entry has the background.
Single-frame scans: when mask/frame_id holds a single layer there is nothing for MotionCor3 to align, so the step switches mc3_doit off by itself and stops after the shadow montage: the rotation / conversion-factor refinement runs as usual, shadow_original is written with its pixel size, and positions/shadow receives the refined positions; the MotionCor3 passes, the aligned sum, the updated montage and the drift map are not produced, and no MotionCor3 executable is needed. scan_hole is then the virtual hole written by stage A of step 01 (centred on the scanned field); its diameter cancels out of every formula here, so the pixel size is 1/cf Å exactly as for a fitted hole.
Patterns and positions: patterns, positions and frame ids are paired row for row only when the pattern stack and the scan position list have the same length; otherwise the explicit map positions/pattern_rows is required (see stage A of step 01). mask/frame_id has one row per position and is mapped onto the patterns through that join. A positions/angs without the stamp of the same join, such as one written by an earlier version that truncated to the common prefix, stops the step, which then asks for stage A of step 01 or stage C of step 01 to be run again.
Results
Images: drift_motion.png (Global motion: the frame-to-frame drift trajectory and the per-pattern applied-drift quiver; with the deep engine and mc3_local also Local motion: MotionCor3’s patch shifts per frame, the fitted field and the half-set verdict), drift_search.png (the search crop on the BF-STEM image with the best cropped montage and its power spectrum, above the rotation and conversion-factor refinement), shadow_montages.png (the original, the MotionCor3 aligned sum and the corrected montage side by side in the MotionCor3 window, each with its power spectrum inset), and the full-extent montages as MRC files, each behind its own knob: shadow_original.mrc (Montage original, shadow_save_original, on by default; the single-particle step falls back to it when the corrected one is absent), aligned_sum.mrc (Montage MotionCorr3, shadow_save_mc3sum, off by default) and shadow_updated.mrc (Montage corrected, shadow_save_corrected, on by default); plus, for the deep engine, drift_quality.png (Montage quality: the CTF correction report, the per-frame signal with the frame weights applied, and the half-set ring correlation of the final montage) drift_hole.png with the hole-only reconstruction, and drift_refine.png when the scan-position refinement ran (the run shifts, the per-run uncertainty of the refined positions over the field, and the half-set correlation before and after; the uncertainty is also written per pattern to positions/shadow_sigma beside positions/shadow); plus drift_local_map.png for the local method.
Data written: HDF5 positions/shadow (drift-corrected positions, Å) and, for the local method, data/defocus/ctf (per-position defocus magnitude, Å, with the patch table and the reference defocus as attributes).
85 — Deep shadow (volumetric reconstruction)
Purpose
Reconstructs a depth-resolved volume from the bright-field shadow montage, by rebuilding the montage once per depth at the conversion factor belonging to that depth. Features at that depth come into focus while everything above and below spreads out and blurs; stacking the slices gives a volume, and the depth at which each part of the field is sharpest gives a height map of the specimen.
Why a conversion-factor sweep is a focal sweep
The montage stamps pattern i at pos_i · cf, and one canvas pixel is one detector pixel projected onto the specimen. A ray leaving scan position u at angle θ meets the specimen at x = u + Δf·θ, so it lands on the canvas at cf·u + θ/θ_px. Those two agree — every ray through one specimen point piling onto one canvas pixel — only when cf = 1/(θ_px·Δf), which is exactly the relation step 50 already uses, cf = D_px / (2·CSA·Δf). So cf and defocus are one quantity, and the canvas coordinate is X = cf·x: the shadow montage is a light-field (plenoptic) refocus of the scan, and sweeping cf sweeps the plane in focus. This step is that sweep, plus the bookkeeping that makes the slices comparable.
Why the defocus map matters
A single global cf brings one surface into focus, not one plane: wherever the specimen is tilted or buckled the true defocus differs across the field, so a global sweep sharpens different parts of the field at different steps and the "slice" it produces is the specimen's own tilted surface. Three earlier steps measure that variation per scan position, all in Å: the parallax step fits it as a plane over the whole field (data/defocus/map, written by step 11, or failing that step 40’s data/defocus/parallax), while the local drift method measures it per KMeans patch by a Ronchigram-CTF fit (data/defocus/ctf).
Sign conventions differ, and none is required. The ctf map is a magnitude by construction (the CTF reads ring spacing, not sign), but the parallax map is a refined C10 from an aberration fit — a signed coefficient, so an underfocus map is legitimately negative at every position. Only the magnitude reaches the geometry: the BF disk shadows 2·|Δf|·tan(CSA) of specimen on either side of focus, so cf = D_px/(2·CSA·|Δf|), and the sign only decides which way round the contrast falls — that is shadow_invert's job. A wholly negative map is used as it stands, with its convention reported in the log.
A map that changes sign across the field is refused rather than normalised. The parallax fit's polar decomposition carries a 180° ambiguity, and patches landing on opposite branches return opposite defocus signs (step 40 warns about this and offers parallax_update_force_rotation_deg to pin the branch). Taking magnitudes there would fold the disagreement into a smooth-looking V and reconstruct a tilt that is an artefact of the fit, not a property of the specimen.
Given a usable map, this step uses a per-position conversion factor cf_i(z) = D_px / (2·CSA·(Δf_i + z)). A feature is stamped consistently by every pattern that sees it when Δf_i + z equals its absolute depth, so the surface brought into focus in slice z lies at depth Δf_i + z — which varies across the field exactly as the defocus map does. The slice therefore follows the specimen surface: on a tilted sample z = 0 is the tilted surface, in focus everywhere at once and rendered flat, and the volume's z axis measures depth relative to that surface, not absolute depth. Correcting the tilt here means flattening the specimen, not cutting flat planes through it.
With deep_local = constant defocus the median is used everywhere, giving one constant conversion factor and hence a plane at constant absolute depth. On a tilted specimen that plane cuts across the surface, so only the band where the local defocus matches the median comes into focus — which is the honest comparison for judging whether the correction is doing anything.
Worked example. On a 15.6° tilt (gradient 0.279 Å of defocus per Å lateral), over a ±400 Å strip of field the in-focus depth with deep_local = follow the surface runs 13119 → 13343 Å, tracking the measured surface exactly; with n it is a flat 13231 Å throughout and coincides with the surface only at the centre.
Parameters
Which region: pty_ROI_id — the same knob the ptychography step uses, read against the same mask (mask/patches/ptycho, written by the ptycho patch marker). It is shared rather than duplicated as a deep_* knob so that a ROI id cannot come to mean two different regions in the two steps. A positive id reconstructs that ROI alone; 0 loops over every id the mask holds, in ascending order, writing each ROI's outputs under a _roi<id> suffix so nothing overwrites anything, and reporting and skipping a ROI that fails rather than stopping the rest. An id the mask does not hold is refused with the list of the ids it does.
The ROI states both where the box is and how big it is: its centroid, and the half-side of its own bounding box (the maximum of |Δx| and |Δy| over its positions, so a square ROI gives its half-side and a round, hexagonal or rotated one gives the square box containing it). The box is then square, and the patterns are selected in the max norm to match it rather than as a radius — the box corner sits at 1.41 × the half-side from the centre, so a circular selection drops exactly the patterns that cover the corners whenever the shadow margin is under 0.41 × the half-side. Measured on a 421 Å box with a 57 Å margin, a circle excluded 2 of the ROI's own 81 positions and left the box corners built from fewer stamps than its middle.
Geometry: the reconstructed region is the ROI selected with pty_ROI_id — its centroid places the box and its own bounding box sizes it — and the ROI mask from 80_ptycho_patches is required; without it the step stops rather than reconstructing the whole field. A diffraction pattern is read only when its shadow reaches into that box. The volume grows as the square of the box in x–y and linearly with the slice count. Also deep_z_range (depth span in Å) and deep_pixel_size (common output sampling; 0 takes it from the middle slice).
Depth sampling is automatic. deep_z_slices defaults to auto, because the answer is set by physics rather than preference: the depth resolution is dz = Δf/D_px, so sampling at dz/2 is Nyquist for it — coarser aliases the focal response, finer only interpolates between slices that cannot differ. The step computes it from the defocus map and prints what it chose, capped at 99 slices. auto dz spaces the slices at dz itself instead — one slice per resolvable depth, so every slice is genuinely distinct, for half the slices, memory and run time; the cost is that a feature lying between two slices is caught by neither at full sharpness, so the height map is coarser. A number overrides both.
Defocus: the per-position map is data/defocus/map, the surface fit written by step 11 — the one input, so there is nothing to select; without it the step falls back to a constant (no tilt correction) and says so. deep_local chooses follow the surface (each position refocused with its own map value) or constant defocus (the map's median everywhere: every slice a flat plane at constant absolute depth). Which positions are stamped from is no longer a setting: the step takes positions/shadow when the drift step has run, falls back to positions/angs otherwise, and says which it used — residual drift blurs a volume exactly as an out-of-focus slice does, so the fallback is reported rather than silent.
Display and analysis: deep_depthmap (write the height map), deep_depthmap_method / deep_depthmap_window (focus measure and lateral window), deep_write_defocus (height map → data/defocus/deep), deep_baseline (the comparison figure against a plain back-projection), deep_frame_weight (per-frame weighting of a dose-fractionated acquisition: off, measured from each frame’s own half-set signal, or the Grant & Grigorieff dose model as in stage B of step 80; the per-frame signal table and deep_frames.png are produced regardless, and on the reference data the first frames carried the least detail, and on held-out patterns neither weighting changed the half-set correlation beyond its noise, so the default is off). There is no depth filter on the xy stack: measured on real data an unsharp mask along z removed 99% of the particle-scale contrast and the |kz| ramp all of it — both are zero at kz = 0, where 99.8% of that power sits — so the stack is written as the raw focal stack.
Band cuts through one feature (deep_cut_project = band). There is no field-wide side view any more: a single central plane uses one row out of a thousand and reads as noise, and a projection over the whole box dilutes any one feature into nothing. What remains is aimed at a feature. It averages a narrow band of rows (columns), deep_cut_band wide, through a point of the preview slice — deep_cut_point, auto for the strongest local structure or x,y in nanometres from the top-left corner of the box — and cuts the raw volume with no depth filter. It shows the feature’s own edges slice by slice, sharp where it focuses and spread by 2·CSA·|Δz| away from it; the point is marked in every panel. Do not expect an hourglass in the to-scale cuts: the blur cone’s half-angle is the convergence angle — 5.6 nm of spread over 400 nm of depth at 7 mrad — so band mode also writes deep_shadow_focus.png: the same cuts with z compressed to one slice per row and the predicted cone drawn in, the patch about the point slice by slice, and the feature’s focus curve (the amplitude of 60–20 Å structure about the point above the field’s own level, which a plain sharpness measure cannot separate from noise, plus the half-set correlation there when that stack exists). Measured on a 35 nm contamination particle: a single plane through it is lost among noise streaks of the same width, a 12 nm band brings its shell out as two clean columns, and the whole-field mean dilutes it into nothing. none skips the figure.
Rendering of the previews: deep_invert, deep_white_bg, deep_contrast. These are three separable controls, because "black particles on a white background" is two questions, not one: deep_invert sets which way the features point (it reverses the greyscale), while deep_white_bg sets where the background sits in that greyscale. deep_contrast is the percentage of pixels allowed to clip, across both tails, and is what makes the rendering punchier.
Why flipping the colormap alone does not give a white background. A montage is a mean of bright-field frames whose own mean has been subtracted, so its background is not merely near zero — it is zero, and a range symmetric about zero puts zero at mid-grey however hard the contrast is pushed. Inverting such a range turns dark particles into bright ones on the same mid-grey field. deep_white_bg clips the bright side instead, lifting zero to ~83% of the way up the ramp, so anything darker than background reads black against a near-white field that keeps its own texture. Bright features are flattened in exchange, so it suits the usual mass-thickness case where protein scatters electrons out of the bright-field disk and comes out dark.
All three act on the PNG previews only — the MRC always holds the unclipped, un-inverted data, so nothing measured moves and no downstream tool inherits a display choice. shadow_invert is the knob that changes the underlying data, by negating the bright-field frames themselves. Shares the montage knobs with step 50: shadow_frames, shadow_area, shadow_invert, shadow_flip_x/shadow_flip_y/shadow_transpose, shadow_defocus and cbed_descan.
Algorithm
- Settles the box first, from the ROI, and reads only the patterns whose shadow reaches into it. That margin ring deliberately reaches outside the ROI and takes in positions belonging to its neighbours: the ROI says where the box is, while every pattern whose shadow covers the box is evidence about it, and dropping the ring would thin the coverage at the box edge for nothing in return. The reference defocus is then the median over the box rather than over everything read, because the ring covers two to three times the box's own area and on a tilted specimen would otherwise decide the reference itself.
- Reorients the patterns onto the scan axes, masks the BF disk and subtracts its mean — with descan on, shifting each disk onto a common centre first. Identical preparation to step 50, through the same shared helpers.
- Plans the depth range about the median defocus, and prints the geometric depth resolution
dz = pixel / (2·CSA)next to the requested slice spacing. A few mrad of convergence gives adzof tens of nanometres: this method separates layers, it does not resolve along the beam. - Finds the geometric focus by scanning z for the peak correlation between the montages of two independent random halves of the patterns (noise cannot raise a half-set correlation, unlike a sharpness measure). The CTF filter then takes its phase from the defocus map but the pattern sampling from that focus; the positions are registered there; and
deep_png_slice = sharpestis that depth. A focus more than 5 % off the defocus map is reported together with the CSA that would reconcile it. - Optionally (
deep_refine_pos, on by default) refines the scan positions first: the correlation functions of each run of consecutively acquired patterns are pooled and registered against a montage of the other random half of the data in the 16–120 Å band; each run is measured twice (odd/even patterns) to obtain the measurement noise, and the shifts are applied scaled by jitter/(jitter+noise), so nothing moves where the data cannot see the error. Single patterns cannot be registered at cryo dose, so only errors shared by a run (line offsets, flyback, residual drift) are corrected. - Weights every slice by
sqrt(2·FRC/(1+FRC))from the half-set ring correlation at the geometric focus, removing rings without significant signal, and prints the resolution at FRC 0.5 / 0.143. - Assembles each slice by back-projecting every pattern in sample coordinates: detector pixel u of pattern i, measured from the BF-disk centre, is carried to
s = p_i + (u / cf_i(z)) / (1 - g·u / K)and accumulated there as a weight-normalised bilinear splat. The per-position magnification goes into the pattern; the scan position is never scaled. Runs on the GPU (torch, CUDA) when available, numpy otherwise. - Accumulates every slice directly on one fixed sample grid (the ROI's box about its centroid), twice as fine as the output, and brings it down to the common pixel size in Fourier space — so all slices share the same box, centre and sampling with nothing to crop or register.
- Removes the depth-independent haze along z, then optionally measures local sharpness per slice and takes its peak depth as the specimen height, masking points whose sharpness never rises above its own spread over z.
What sets the depth resolution
Substituting the shadow sampling pixel = 2·CSA·Δf / D_px into dz = pixel/(2·CSA) cancels the convergence angle and leaves dz = Δf / D_px — the defocus divided by the number of detector pixels spanning the BF disk, which is the number of independent views the refocus has to work with. Both forms are printed; they are the same number. So the convergence angle is not itself the lever: opening it helps only insofar as it spreads the disk over more detector pixels. Widening the angle while lengthening the camera length, so the disk covers the same pixels, buys no depth at all and only coarsens the lateral sampling. To section more finely, lower the defocus or put more pixels across the disk.
Why the height map can be trusted
Each point is assigned the depth at which the two independent half reconstructions agree best about the detail around it (deep_depthmap_method = halfset, the default): their local correlation in the 60–20 Å band under a Gaussian window of deep_depthmap_window (80 Å). Noise cannot raise a correlation between halves that share nothing but the specimen, so the peak is where the detail is — the same principle as the global focus scan, per point. A parabola through the three slices about the peak places the depth between slices, and the peak correlation is written as a confidence map.
The mask is calibrated. The null level of the local correlation is measured on every run (the halves displaced against each other by more than the window) and matches the analytic value to 5 %; the threshold is that level × (√(2 ln N) + 1.5), what the peak of pure noise over N resolvable depths reaches. Measured on real data a featureless field passes at 0.0–0.4 %. The reported trusted fraction is the number to read; the window sets the trade between coverage and lateral resolution (at 2 Å/px: 40 Å → 21 %, 80 Å → 65 %, 120 Å → 96 %). The earlier sharpness mask (a fixed 1.5 on the peak-over-spread statistic) let pure noise through almost entirely — 97 % at 31 slices — so its fraction meant nothing; sharpness remains available with a threshold drawn from the null for the actual slice count.
Depth precision. A detail of d Å stays in focus over about d / (2 CSA), so the 60–20 Å band has a focal response thousands of Å wide and the sub-slice peak is precise to a few hundred Å (IQR ±200 Å on a flat ROI). The nominal dz = defocus/Dpx is the finest the sampling admits, not what survives the noise.
As a defocus map. deep_write_defocus writes data/defocus/deep: the defocus each box was built against plus the trusted height at every scan position inside it, the source map elsewhere — a defocus surface measured from the data. Off by default; nothing reads it yet.
Known limit. When the specimen detail is only a few pixels across, little survives in the correlation band and the trusted fraction falls; the volume still refocuses correctly there, it is the depth assignment that runs out of signal.
Memory
Peak memory scales with the subset, not with the acquisition. The subset knobs (shadow_frames, shadow_area) are settled from frame_id and the scan positions alone — a few megabytes between them — so they are decided before any pattern is read, and only the surviving patterns are fetched. On a 173 125-pattern acquisition (25.5 GB of patterns) a 5% subset peaks at 2.8 GB rather than the 50.7 GB it costs to read the stack and preprocess it before cutting it down — the saving is the whole stack twice over, since both the read and the preprocessed copy are avoided. Patterns are gathered by direct indexing rather than in blocks, which suits a stack chunked one pattern per chunk: selecting a pattern decompresses exactly that pattern and no neighbours. What remains is the volume itself, which grows as the square of the box — the ROI's own extent — and linearly with deep_z_slices. In all-ROI mode the ROIs are built one at a time and each one's arrays are dropped before the next starts, so the peak is one ROI's rather than the sum of them.
Results
In all-ROI mode every name below carries a _roi<id> suffix — deep_shadow_roi3.mrc, deep_shadow_roi3.png, deep_depth_roi3.mrc and so on — while a single ROI keeps the plain names. deep_defocus_ref and deep_pixel_achieved are per-ROI quantities and only one value of each can be returned to 4d, so in all-ROI mode they describe the last ROI reconstructed and the log names it; every ROI's own values are printed as it is built.
Images: deep_compare.png (with deep_baseline on, the default: the preview slice as processed beside the same slice as a plain back-projection — patterns re-read from the file, unrefined positions, no CTF correction, no frame weighting, no deconvolution, everything else identical — at one display range, with the half-set ring correlation of both underneath; what the four stages bought, seen rather than assumed), deep_refine.png (when the positions were refined: the correction per run of consecutively acquired patterns with the measurement noise marked, the corrections as arrows over the field, and the half-set ring correlation at the focus before and after), deep_shadow_focus.png (with deep_cut_project = band: the band cuts through one feature, z compressed, and its focus curve), deep_depth.png (height map, focus-versus-depth curve, confidence map), deep_ctf.png (with deep_ctf on: the CTF's report card — the transfer function assumed and the filter applied; the Thon rings of the patterns themselves (the radial profile of their summed power spectrum, the same measurement 25_defocus_ctf makes, which reaches far beyond the 20 Å the montage's half-set correlation can see) against |CTF| at the defocus the filter used, with its zeros dashed — the title quotes the defocus the rings fit, how many lobes it resolved and to what resolution, against the value the filter took, and when the two differ the fit is drawn too; and the ring correlation of one corrected half of the montage with the other uncorrected half, which must change sign at every zero and nowhere else — judged lobe by lobe, with all the Fourier pixels between successive zeros pooled so that the 3 σ threshold falls to what the data at 10 Å can clear; each lobe is drawn as a bar, green where the applied sign is the CTF's, red where it is the opposite, grey where the lobe stays below 3 σ even pooled, and the title counts the testable lobes and the right ones. The filter's defocus is the defocus map; the rings' own fit is printed beside it for comparison. deep_ctf_depth says what that correction does away from the focus plane: pattern leaves every slice with the focus-plane filter, slice (default) flips back, on each assembled slice and its two half slices, the bands between the zeros the stamp rescaling has carried the filter to, k·df/(df+dz), and the zeros a feature at that depth truly has, k·√(df/(df+dz)) — one Fourier multiplication per slice, exact for a flat specimen and first order for a tilted one), and deep_shadow_slice.png — one xy slice on its own at full resolution and with nothing drawn into it. Which slice is set by deep_png_slice: the default sharpest takes the peak of the interior focus curve (z = 0 is only the median of the defocus map, and the specimen is not obliged to sit exactly there — on real data the sharpest slice lay 1500 Å off it), a number is a z in Ångström snapped to the nearest slice, and 0 restores the reference slice. The z it landed on is printed and carried in the image caption. The display range of every preview is computed from this very slice, so the file is that same rendering at full size — one file pixel per voxel, and no scale bar burned across the pixels, which is what makes it usable for measuring distances or for dropping into a figure. It is not a photometric copy: with deep_white_bg on, the bright tail is clipped deliberately (at the default deep_contrast roughly a third of the pixels sit at pure white — the noise around the white background), so read anything quantitative from deep_shadow.mrc, which keeps the unclipped values.
Data written: deep_shadow.mrc (the volume, sampling in x/y and slice spacing in z stamped into the header), deep_shadow_slice.mrc (the preview slice alone, the unclipped voxels behind deep_shadow_slice.png) and deep_depth.mrc (the height map). With deep_movie on, also deep_shadow.gif: an animation stepping through the stack in xy at that same fixed display range, one frame per slice, running forward then back. It is registered for display and 4d's viewer plays it in place; its path is printed too for opening outside the app. Returns deep_defocus_ref and deep_pixel_achieved to 4d.
A caveat worth knowing
Why the patterns are rescaled rather than the positions: with a per-position conversion factor, stamping native-scale patterns at p_i · cf_i puts a feature at s down at s · cf_i — a different place for every pattern that sees it, by an amount that grows with the distance from the origin of the position list (14 px measured on a tilted ROI 5900 Å off it) — and warps each slice differently, so features away from the iso-defocus line drift sideways through the stack. deep_deconv turns that drift into speckle everywhere except along that line. Back-projecting in sample coordinates removes both; the remaining g·u / K term is the keystone of a tilted specimen, about 0.1 px at the disk rim.
80 — Ptycho: patches, reconstruction and merge
Purpose
The ptychography chain in one step: lay out the reconstruction ROIs, reconstruct them with the chosen engine, and merge the amplitude and phase of that reconstruction into the image the particle analysis reads. The ROI layout, the three engines and the merge remain independent scripts, kept in scripts/image/WASP/dependents/ so they do not appear in the function list (they are listed under DEPENDENT SCRIPTS when the step is selected, where a double-click opens them). This step runs the switched-on stages in order as dependent scripts, with the same parameters they would get from the GUI, and their figures, values and progress come back here.
| Switch | Stage |
|---|---|
pty_run_patches | A — ROI layout. Tiles the field of view with the reconstruction ROIs, writes mask/patches/ptycho and measures the applied dose (pty_dose). Off: the layout of the last run stays. |
pty_run_reconstruct | B — reconstruction. Runs the engine chosen by pty_engine (py4DSTEM, Torchslice or GSharp) on the ROI(s) selected with pty_ROI_id and returns pty_engine_used. Off: nothing is reconstructed. |
pty_run_merge | C — amplitude-phase merge. Band-passes the amplitude, high-passes the phase and adds the two, writing a_p_merge*.mrc / .png. Off: the merged image is left as it was. |
Each stage keeps its own parameters, listed on its page below; they are all shown on this step. Lay the ROIs out and check the overlay without reconstructing, reconstruct again on the stored layout, or re-merge in seconds with other filter cutoffs, by switching the other stages off.
The merge takes the reconstruction of this run
Every engine writes its own ptycho_<engine>_amplitude / _phase files and nothing is overwritten by another engine's run, so the merge has to be told which engine's files to read. When stage B runs, stage C merges the output of that engine, the one chosen in pty_engine, whatever apmerge_source says, and the log says so. With stage B off, apmerge_source chooses as before: an engine by name, or latest for the engine the reconstruction ran last (pty_engine_used) or, failing that, the engine whose files are newest on disk.
Results pass from stage to stage
The reconstruction reads the dose the ROI layout measures and the ROI mask it writes to the stack; the merge reads the engine the reconstruction ran. Run as separate steps these would reach the next step through the project configuration; run here in one go the next stage is baked before 4d has read the results, so every value a stage writes back (set lines of the results file) is forwarded by the step itself to the stages after it in the same run, and the log says which. A forwarded value is used even when the parameter is locked in the GUI; switch the producing stage off to keep a hand-set value.
Algorithm
- For every stage that is on, in the order A, B, C: reads its source from the
dependents/folder and bakes its header with this step's own values plus everything the earlier stages of this run returned, exactly as the app does for a script it starts, intoproc/of the image. - Runs that copy with the same Python, in the image directory, writing to this step's results file. Its progress is mapped into this step's own band. A failure stops the step, since the stages after it would run on stale results.
- Reads the values it returned and hands them to the next stage.
Results
Whatever the switched-on stages write: see the pages below.
44 — Ptycho: SLURM version (stage B in parallel on the cluster)
Purpose
The ptychography step with its stage B, the reconstruction, spread over the GPU cluster set up in Preferences › System › Slurm Batch Queue System. The reconstruction of every ROI is independent of the others, so each ROI becomes a Slurm job of its own, and the 9 to 16 ROIs of a layout take about the time of one instead of the sum of all. The parameters, the stages A, B and C and their switches, and the results are those of step 80; what differs is where stage B runs.
| Use the Slurm batch queue | Stage B |
|---|---|
y | One Slurm job per ROI: the ROIs of the layout (pty_ROI_id = 0), or the one ROI chosen. The jobs run at the same time as far as the partition has room. |
n | Here, one ROI after the other, exactly as in step 80. |
Stages A and C always run here: they take seconds.
What reaches the nodes
The nodes cannot see the image directory, so the step stages what the jobs need on the shared NFS directory of the Slurm preferences:
- The stack. Its patterns, nearly all of the file, are copied once into
4d_slurm_cache/stacksand reused for as long as they stay the same (a fingerprint of the pattern dataset decides). Everything else of the stack, the ROI mask stage A has just written, the positions, the maps, a few tens of MB, is written fresh at every run into a small file of the job folder whose patterns are an HDF5 link to the cached copy. The jobs open that file as their stack. The first run of a 20 GB stack copies for about a minute; the runs after it stage in seconds. - The code.
scripts/procand the Torchslice tree, a few MB, are copied with every run, so a job runs the code of the step that started it. - One job per ROI. Each job runs the engine baked for its ROI, in a folder of its own below
4d_slurm_jobs/ptycho_<engine>_<user>_<time>, and names its outputs as the run over every ROI does (_roiN), so the merge of stage C finds them all.
While the jobs run
The log shows one table of the jobs, rewritten in place: ROI, job id, state (PENDING with its reason, RUNNING, COMPLETED, FAILED …), node, a progress bar fed by the engine's own progress marks, the time and the engine's latest message. The progress bar of the step follows the mean of the jobs. As soon as a job ends, its log follows in full, its files are copied into the image directory, its result lines go to the results file and its images appear in the results.
When a job fails
A job that fails is reported with its reason: the time limit or the memory of the Slurm preferences, an error of the engine (its log is shown), or a cancellation. Its files stay in its job folder, and the other ROIs go on, as in step 80, where a failed ROI is skipped. The step stops when every job failed, since the merge would only find old results. Stopping the step cancels the jobs.
Resources
Every job asks for the GPUs, cores, memory and time of the Slurm preferences. The log says how many jobs of that size the partition runs at once; ROIs beyond that wait in the queue. One job per GPU needs at most the cores and memory of a node divided by its GPUs: 16 cores and 62 GB on the lbem-gpus nodes (64 cores, 250 GB, 4 GPUs). The time limit must cover the reconstruction of one ROI.
Results
Those of step 80: the engine's ptycho_<engine>_*_roiN files and images per ROI, pty_engine_used, and the merge of stage C. The job folder keeps the batch scripts, the job logs and the result lines of every job; the files of a successful job are moved into the image directory.
80 A — Ptycho patch marker
Purpose
Lays out the regions of interest (ROIs) for the reconstruction, tiling them as an N × N block over the hole centre, and tags every scan position with its 1-based ROI index so the reconstruction step pulls one ROI at a time. It also estimates the mean applied electron dose, returned as pty_dose.
Parameters
| Parameter | Role |
|---|---|
ptycho_roi_shells | The ROI layout: an N × N block of exactly N² ROIs. The parity matters as much as the count — an ODD N puts one ROI centred on the hole centre, while an EVEN one (2 × 2, 4 × 4) has no central ROI at all and straddles the centre, where four tiles meet. In auto size mode the ROI size adjusts so the layout tiles the field of view exactly, so a larger N means proportionally smaller ROIs over the same area, not a wider one. Projects predating this may still hold the old “single shell” wording; it names the same arrangement as 3 × 3 and is read as such. |
ptycho_roi_size_mode, pty_roi_size_nm | Auto (tile the FOV) or manual ROI side (width) in nanometres, on the calibrated positions; the log also gives it as a percent of the field-of-view width (twice the distance from the hole centre to the farthest scan position). |
pty_roi_rot | Grid rotation about the hole centre (degrees). |
ptycho_roi_center | Where the layout is centred: hole (the hole found by stage C of step 01, the classic behaviour) or field of view (the centre of the scanned field, for a scan off the hole, a hole larger than the scan, or a single-frame scan with only a virtual hole). The FOV radius that sizes the ROIs is measured from the chosen centre; the hole is still drawn where it is. |
ptycho_roi_shape | Square / round / hexagon ROI shape. |
| positions | Chosen automatically: the drift-corrected positions/shadow, else the calibrated positions/angs, else the raw positions/units; the log says which was used. |
CPE | Counts per electron, for the dose estimate. |
Algorithm
- Estimates the dose: total electrons (sum of all patterns /
CPE) divided by the convex-hull area of the scan positions → mean dose in e/Ų. - Places exactly N² ROIs over the hole centre — on a square lattice for square ROIs, a hexagonal one for round and hexagon ROIs — auto-sized so the layout tiles the field of view, or at the manual size, then rotated by
pty_roi_rot. An odd N puts a ROI on the centre; an even N straddles it. - Tags each position with the ROI it falls in (per shape: radius, apothem, or Chebyshev distance).
Results
Image: ptycho_roi.png — the BF map with the hole circle, the numbered ROI outlines, and positions coloured by ROI.
Data written: HDF5 mask/patches/ptycho (per-position ROI index); results/GUI value pty_dose.
80 B — Ptychographic reconstruction
Purpose
One step for the ptychographic reconstruction of the ROIs laid out by stage A, with the engine chosen by pty_engine: py4dstem runs the py4DSTEM single-slice solver, torchslice the recursive Torchslice solver, gsharp Torchslice’s joint dose-fraction solver. The three remain independent scripts with their own parameters, kept in scripts/image/WASP/dependents/ so they do not appear in the function list; this step runs the chosen one as a dependent script (listed under DEPENDENT SCRIPTS when the step is selected, where a double-click opens it).
Parameters
| Parameter | Role |
|---|---|
pty_engine | py4dstem, torchslice or gsharp. |
| shared | The parameters both recursive engines read: ROI, defocus mode and map, positions source, the levels (sharp_level_scheme: how many and how many frames each keeps, as a rule against the stack’s frame count; sharp_lvl_lrs for a custom list) with iterations per level, transpose, detector mask and rotation (Ptychography section and 4D STEM family), the Damage model and the Image fusion families. |
| py4Dstem section | Read by the py4DSTEM engine only: batch size and step size per level, mixed-state modes, object mode, pure phase, probe aberration order, position-update limits, background high-pass, detector-orientation search, upsampling, tilt refinement. |
| Torchslice section | Read by the Torchslice and GSharp engines: loss and optimisers, CBED alignment, aperture fit, scan-lag and direction-descan corrections, defocus surface order; the per-level learning rates and batch by the Torchslice engine only. |
| GSharp section | Read by the GSharp engine only, shown when it is chosen: the dose-fraction cut, and single-valued iterations, minibatch and learning rates, since it makes one solve. The per-level lists and the Image fusion family are hidden for it. |
| Visualisation section | pty_show_spectrum: whether the reconstruction figure of either engine carries its power-spectrum panels (one switch for both). |
pty_engine_used | Output — the engine last run. |
Algorithm
- Reads the chosen engine's source from the dependents folder and bakes its header with this step's own values, exactly as the app does for a script it starts, into
proc/of the image. - Runs that copy with the same Python, in the image directory, writing to this step's results file, so its figures, values and progress appear here. A failure of the engine fails this step.
Results
Whatever the chosen engine writes, see the three engine sections below. Every file is named ptycho_<engine>_<name>: the figures ptycho_<engine>_levels.png and ptycho_<engine>_summary.png with the engine’s own diagnostics, the MRC images ptycho_<engine>_amplitude.mrc and ptycho_<engine>_phase.mrc (ptycho_py4dstem_potential.mrc in potential mode) and the engine’s data files; the two Torchslice engines share their preprocessing outputs under ptycho_prep_<name>. Nothing is overwritten by another engine’s run; the image merge and the particle analysis choose the engine with apmerge_source, and pty_engine_used records the engine this step ran last.
py4DSTEM engine — run by stage B of step 80 (formerly step 90)
Purpose
The main ptychographic reconstruction. It reconstructs one ROI's complex object (amplitude + phase) with py4DSTEM in three recursive "levels," each using progressively fewer scan layers (so less dose/damage), then fuses the levels in Fourier space — the high-dose level supplies robust low frequencies, the low-dose levels supply undamaged high frequencies.
Parameters
ROI & geometry: pty_roi_all (All ROIs: every ROI in turn) with pty_ROI_id (the ROI when All ROIs is off), pty_positions_source (units/angs/shadow), pty_detector_mask (advanced: zero every count beyond this multiple of the BF-disk radius before the solve, e.g. 1.2, with a 2 px cosine taper; 0 = off; the outer dark field is mostly noise at cryo dose, and the transferred angle is capped at mask + 1 times the convergence semi-angle; ptycho_prep_detector_mask.png shows the PACBED before and after with the radial profile and the limit), pty_defocus_mode (manual/map with pty_defocus_invert (invert the map) — map averages over the ROI the defocus map step 11 writes to data/defocus/map, invert the map multiplies that map by −1 on read, where the source of every patch, parallax or Ronchigram CTF, is chosen; the step 40 parallax map stands in until step 11 has run) with fallback pty_dF, pty_transpose (swap the detector axes before the solve), and the detector-orientation controls pty_detector_orientation, pty_detector_rotation_try, pty_detector_rotation_set. py4DSTEM is very sensitive to detector handedness — a wrong transpose does not fail, it prints a periodic moiré lattice across the object that no denoiser removes. Run the orientation sweep (it scores each combination by CoM curl/|div|, which approaches zero for the correct one) and set pty_transpose to the TRANSPOSE it reports; its ROT_K partner remains fixed at 2 in the script. Default n reproduces the previous behaviour exactly.
Levels: sharp_level_scheme — how many recursive levels (up to 5) and how many frames each keeps, as a rule against the number of frames the frame identification step counted (scan_frames), so one choice fits a 9- and a 12-frame stack: all, two thirds, one third is 9, 6, 3 frames on nine (the default), all, half two levels, the quarter and fifth rules four and five, one frame fewer per level 9, 8, 7, 6, 5, halving per level 9, 4, 2, 1, all frames level 0 alone, custom the counts of sharp_lvl_lrs. Level names are generated. Per-level lists (comma-separated, one value per level up to that count; a shorter list repeats its last value): sharp_lvl_iter, sharp_lvl_batch, sharp_lvl_step (learning rate), positions_max_update and positions_total_distance (per-position drift limits).
Probe aberration fitting: sharp_probe_cor (drop-down, 1–6, default 3) sets the highest aberration order kept when the probe is re-fitted, the same for every level. Each iteration the probe’s Fourier phase is unwrapped, least-squares fitted (amplitude-weighted) to an aberration basis χ(α,θ) and replaced by that fit, so it acts as a regularizer — anything the basis cannot describe is discarded. 1: constant phase only (probe phase flattened). 2: C1 defocus + A1 2-fold astigmatism. 3: + B2 coma + A2 3-fold astigmatism. 4: + C3 spherical + S3 star + A3 4-fold astigmatism. 5: + B4 coma + D4 three-lobe + A4 5-fold astigmatism. 6: + C5 + S5 star + R5 rosette + A5 6-fold astigmatism. Low orders hold the probe close to a textbook aberration function; high orders let it keep more structure but also fit noise and phase-unwrapping artefacts outside the bright-field disk.
Reconstruction & filtering: pty_mode (complex/potential), pty_pure (pure phase), pty_noncoherent_modes (incoherent probe modes; ≥2 → mixed-state), sharp_bcg (high-pass cut-off Å); damage model sharp_dmg_mode (Grant & Grigorieff roll-off with its hard stops, or fixed cutoffs), sharp_lvl_dmg and sharp_lvl_ord (the fixed cutoffs and filter order; under the Grant & Grigorieff choices each level's cutoff, which the fusion works from, is computed from the model at the level's dose and printed in the log); fusion sharp_fusion_mode (SNR-weighted Wiener or plain ring, both dose-weighted), sharp_fusion_margin (plain ring), sharp_level_align; display upsampling pty_upsample_mode/pty_upsample_factor. Reads pixel size, dose, the defocus map, positions, and mask/patches/ptycho from earlier steps.
Algorithm
- Selects the ROI, resolves the defocus (manual, or ROI-mean of the chosen defocus map), and derives per-level scan-layer counts and per-level dose.
- Pre-processes: reorients patterns, removes descan (per-pattern centre-of-mass + plane fit), builds the initial probe (mixed-state modes if requested) and object canvas.
- Level 0 uses all points, fits probe aberrations and refines positions →
ptycho_py4dstem_lvl0.h5. - Levels 1 and above (as many as the rule gives) use subsampled layers, each seeded from a damage-limited fusion of the previous levels →
ptycho_py4dstem_lvl1.h5,ptycho_py4dstem_lvl2.h5. - Between levels the outputs are fused in Fourier space, after every level has been registered onto level 0: the SNR-weighted (Wiener) merge lets every level contribute up to its own cutoff, weighted by dose; the plain ring fusion hands over at the cutoffs with a tanh edge. A damage filter is applied per level.
mask/frame_id holds one layer, or is absent) has nothing to fractionate. Such data is reconstructed in one level: level 0 alone on the whole point set, with Scan layers (sharp_lvl_lrs) forced to 1 so the dose accounting sees the full dose. Levels 1 and 2 are not run, no damage model is applied (a single unfractionated frame has no dose curve to weight against, and the Damage model settings are greyed out for it) and no level fusion is applied; the level-0 object, as reconstructed, is the final reconstruction, written under the usual merged names. The figures show that one level only. The other entries of the per-level lists are ignored, but the lists still need their three values.
Results
Images: ptycho_py4dstem_levels.png (per-level and running-fusion amplitude/phase), ptycho_py4dstem_summary.png/.pdf (hero phase, amplitude, diffractogram with info-limit ring, radial-PSD resolution estimate, per-level convergence), ptycho_py4dstem_radial_profiles.png, ptycho_py4dstem_probe_tilt.png (with the local tilt refinement) and ptycho_py4dstem_detector_mask.png (with the detector mask).
Data written: per-level HDF5 files ptycho_py4dstem_lvl0.h5, ptycho_py4dstem_lvl1.h5, ptycho_py4dstem_lvl2.h5 (each holding the object, cropped object, object FFT, probe, sampling, and error curve), the MRC images ptycho_py4dstem_amplitude.mrc / ptycho_py4dstem_phase.mrc (ptycho_py4dstem_potential.mrc in potential mode) with the pixel size stamped as the voxel size, and ptycho_py4dstem_rotation_scan.json, ptycho_py4dstem_tilt_scan.json and ptycho_py4dstem_tilt_plane.json from the orientation and tilt searches. All images are registered to the Results panel.
Torchslice engine — run by stage B of step 80 (formerly step 91)
Purpose
Reconstructs one ROI with Torchslice, a PyTorch/GPU single-slice ptychography engine — the SGD-optimizer counterpart of script 90. It is recursive and multi-level: level 0 uses the full point set with learnable probe aberrations and per-position drift, and later levels use fewer scan layers, each seeded by a dose-weighted Fourier fusion of the prior levels to limit carried-forward damage.
Parameters
ROI & geometry: pty_roi_all (All ROIs: every ROI in turn) with pty_ROI_id (the ROI when All ROIs is off), pty_positions_source (units/angs/shadow), pty_detector_mask (advanced: zero every count beyond this multiple of the BF-disk radius before the solve, e.g. 1.2, with a 2 px cosine taper; 0 = off; the outer dark field is mostly noise at cryo dose, and the transferred angle is capped at mask + 1 times the convergence semi-angle; ptycho_prep_detector_mask.png shows the PACBED before and after with the radial profile and the limit), pty_defocus_mode (manual/map with pty_defocus_invert (invert the map), the same choice as stage B: map is the ROI mean of the defocus map step 11 writes, with invert the map, that mean multiplied by −1) with fallback pty_dF, and pty_dose (from stage A).
Levels: sharp_level_scheme, the same rule against the frame count as in the py4DSTEM engine (custom reads sharp_lvl_lrs). Per-level lists (one value per level up to that count; a shorter list repeats its last value): sharp_lvl_iter (SGD iterations), sharp_lvl_dmg (fixed cutoffs Å; under the Grant & Grigorieff choices the level cutoffs are computed from the model at each level's dose), sharp_lvl_lrbatch (minibatch size), and per-level learning rates sharp_lvl_lrnet (object), sharp_lvl_lrgrid (positions), sharp_lvl_lrprobe (probe).
Torchslice solver: pty_torchslice_loss (loss function), the optimizers pty_torchslice_netoptim/_gridoptim/_probeoptim (object/positions/probe), and pty_torchslice_cut (hard zeros frequencies past the optimal dose in the dose weighting).
Scan-coil lag: pty_lag_nm (lag applied to the positions, nm; 0 = off; the refinement and the scan write their result back here), pty_lag_refine (measure the one lag scalar inside the engine from the forward- and backward-travelled rows reconstructed separately), pty_lag_scan (comma-separated trial lags in nm; non-empty turns the run into a merit scan and no full reconstruction is made) and pty_lag_scan_size (side of the central sub-region the scan reconstructs, nm).
Direction-dependent descan: pty_descan_direction (y/n: add to the descan model a bright-field disc shift that flips sign with the direction each scan row was travelled, measured on the rim of the forward and backward mean patterns, since the smooth polynomial cannot carry a row-alternating term and the in-disc centre of mass is blind to a rigid disc shift) and pty_descan_direction_order (radial Zernike order of its variation over the ROI, default 2; 0 = one constant vector). The term is not constant over a scan — on the honeytomb stacks 0.05 px at the field edge and 1.7 px right of its centre, a smooth quartic that is the same in every pass — so a constant leaves its gradient uncorrected at the edges of a larger ROI (0.5 px over 400 nm, 0.9 px over 700 nm), where the two-row stripes survive. The polynomial is fitted on the per-exposure whole-pattern centre of mass against the travel sign (orthogonal to the specimen’s shadow because the rows alternate), scaled to the rim fit, and applied only if it reproduces between the two interleaved halves of the exposures; ptycho_prep_lag_result.json stores the coefficients under descan_direction.
Algorithm
- Selects the ROI and resolves the defocus; derives per-level scan-layer counts and per-level dose.
- Builds the microscope/simulation model, an initial probe with the defocus aberration, and a per-pattern descan/tilt model: the whole-field model of the CBED calibration (
data/descan_model, smooth part only, about the ROI mean) when the stack carries one, otherwise a Zernike fit of the in-ROI centre of mass gated by its correlation with the measured shifts; plus the direction-dependent disc shift with its position dependence over the ROI, applied with the travel sign of every exposure. The ROI fit is printed as a cross-check either way and the run card says which model was applied. - Scan-coil lag (optional). The coils trail the commanded position along the direction of travel, so an exposure commanded at rj happened at rj − δ·tj, with tj the unit travel vector and δ the lag. On a serpentine traversal tj alternates sign row to row and the reconstruction shows stripes of two-row period along the rows (13.84 nm for the nine-pass ShaRP pattern); per-position refinement does not remove them at cryo dose. The travel vectors are taken once from the stack's own position array in acquisition order (central difference within a row; a row ends at a frame change, a transit waypoint or a step over 30 nm), so they share its axis order, source and rotation, and the correction is applied in memory. A fixed
pty_lag_nmshifts the positions before the solve;pty_lag_refinemeasures the one scalar inside the engine before level 0: the exposures travelling along +e, reconstructed alone, give a clean object displaced by +δe, those along −e the same object displaced by −δe, and half their registration shift along the row axis is the lag (the shift across the rows is a null test); it is applied, re-measured once for the residual, written back topty_lag_nmand used by every level with per-position refinement off. The solver's position gradient projected onto the travel vectors was tried first and found degenerate: the object absorbs the row inconsistency as a doubled image that is a fixed point of the alternating updates, which is also why free per-position refinement leaves the stripes;pty_lag_scanreconstructs level 0 of the central sub-region once per trial lag and reports a table of trial lag, stripe metric and data error with a parabola through the three lowest stripe metrics. The stripe contrast — the power at the row frequency along the row normal (±15 %, ±12°, Hann-windowed) over the power of the flanks of that line, so 1 means no stripes — is the merit, and it and the band power fraction are reported for every reconstruction. The two half-set objects of the refinement are also correlated ring by ring: solved from disjoint exposures and registered by the measured shift, with the scan-lattice lines left out, their Fourier ring correlation is a half-set resolution measurement of level 0 — the log prints the finest significant ring (3 σ, three rings running), the FRC 0.5 and 0.143 crossings, the same along and across the rows (the split is by travel direction, so the overlap differs), and the full-count estimate 2 FRC/(1 + FRC); the curves are inptycho_prep_lag_result.jsonand drawn inptycho_prep_lag_refine.png. It measures reproducibility against shot noise of level 0 at half its exposures, not the fused result and not accuracy: the probe, the descan model and the positions are common to both halves. - For each level, runs a Torchslice SGD reconstruction (chosen loss and optimizers, per-position drift) over that level's point count, then fuses all levels so far by dose-weighting each frequency (Grant & Grigorieff critical dose) to seed the next level.
- The final fusion is the same merge over all levels (
sharp_fusion_mode: SNR-weighted Wiener, or plain ring with tanh band edges at the level cutoffs and √dose magnitude weighting), after registering the levels onto level 0.
mask/frame_id holds one layer, or is absent) has nothing to fractionate, so it is reconstructed in one level, level 0 alone on the whole point set with Scan layers (sharp_lvl_lrs) forced to 1. Levels 1 and 2 are not run, no damage model is applied (a single unfractionated frame has no dose curve to weight against, and the Damage model settings are greyed out for it) and no level fusion is applied; the level-0 object, as reconstructed, is the final reconstruction, written under the usual merged names, and the figures show that one level only.
Results
Images: ptycho_torchslice_levels.png (a 4×3 grid — levels 0/1/2 and the fused result × amplitude / phase / log power spectrum) ptycho_torchslice_summary.png (the finished run on one page — fused amplitude and phase, the power spectrum of the fused phase with resolution rings, the probe before and after refinement, and the per-level convergence curves end to end) and the per-level damage weights are a panel in the bottom row of ptycho_torchslice_summary.png (each level's share of the fused signal against spatial frequency as a stacked band, its own damage weight as a dashed line, the band edges and the Nyquist of the measured pixel marked, resolution in Å along the top).
Scan-coil lag: ptycho_prep_lag_result.json (the lag applied or measured, in nm and pixels, the half-set registration history, and the stripe metric of the fused result and of every level) with every reconstruction; a scan run writes ptycho_prep_lag_scan.png (stripe metric and data error against the trial lag, and the trial phases at one contrast) and ptycho_prep_lag_scan.json instead, and writes the parabola minimum back into pty_lag_nm.
Data written: the fused result only, as ptycho_torchslice_amplitude.mrc / ptycho_torchslice_phase.mrc with the pixel size stamped as the voxel size (the levels are shown in the figure, not written); all images registered to the Results panel.
GSharp engine — run by stage B of step 80
Purpose
Reconstructs one ROI with Torchslice’s GSharp reconstructor: ONE object solved from every exposure at once, with the beam-damage model applied inside the solver instead of between recursive levels. The exposures of a multi-pass scan are split into disjoint dose fractions at the layer counts of sharp_lvl_lrs, each fraction keeps its own scan grid and pattern set, and the gradient of the object that each fraction produces is filtered in Fourier space by the damage weight of the dose it was taken at before the optimiser sees it. The fractions are solved interleaved, minibatch by minibatch, so the least exposed fraction writes the fine frequencies and the heavily exposed ones only the coarse ones, with no band edges and no fusion step. It shares every input and every preprocessing stage with the Torchslice engine.
Parameters
ROI & geometry, scan-coil lag, direction-dependent descan: exactly the Torchslice engine’s — pty_ROI_id, pty_positions_source, pty_detector_mask, pty_detector_rotation_set, pty_transpose, pty_defocus_mode with pty_dF, pty_defocus_local and pty_defocus_order, pty_cbed_align, pty_aperture_fit and pty_aperture_order, the pty_lag_* knobs and pty_descan_direction / pty_descan_direction_order; see that section.
GSharp section (shown when the engine is gsharp): pty_gsharp_fractions (how the layers are cut into fractions: first fraction then single layers, first fraction then pairs or first fraction then triples — the first fraction holds pty_gsharp_first_layers leading layers and the rest follow one, two or three at a time to the last layer, so on nine layers with a first fraction of 3 the fractions are 0–2, 3, 4, …, 8 / 0–2, 3–4, 5–6, 7–8 / 0–2, 3–5, 6–8 — or custom with the cumulative counts of pty_gsharp_fraction_edges, e.g. 3,5,7,9), pty_gsharp_iter (iterations of the joint solve; one iteration passes over every exposure once), pty_gsharp_batch (minibatch per fraction), pty_gsharp_lrnet, pty_gsharp_lrgrid, pty_gsharp_lrprobe (learning rates of object, positions, probe). The per-level lists of the recursive engines are not read and are hidden for this engine. The damage model sharp_dmg_mode with sharp_lvl_dmg and sharp_lvl_ord becomes the per-fraction gradient filter (the fixed cutoffs are given level 0 first, so the least exposed fraction takes the last entry). pty_torchslice_loss and the three optimisers as in the Torchslice engine; the plain poisson loss has no learning-rate bound in this reconstructor and is replaced by poisson_approx with a note. The Image fusion family is not read.
Algorithm
- ROI selection, defocus, preprocessing (hot pixel, detector mask, disc detection, CBED alignment, aperture fit, descan model with its correlation check, direction-dependent descan from the stack or the ROI rim fit), scan-coil lag scan or refinement with its half-set FRC — stage for stage the Torchslice engine’s, with the same figures (
detector_mask,cbed_align,aperture_fit,lag_refine,lag_scan; the direction-descan figure is the one step 02 writes). The lag measurements are made with the plain Torchslice reconstructor on level 0, as there, before the joint solve. - Dose fractions. Cumulative layer counts cut the stack into disjoint fractions, chosen by
pty_gsharp_fractions(a first fraction ofpty_gsharp_first_layerslayers, then single layers, pairs or triples to the last layer, or a custom list); the exposures are stored in layer order, so each fraction is a contiguous slice. A fraction that comes out empty is skipped with a note, and the log prints the cut used. For each fraction a Fourier filter over the object canvas is built from the samedamage_weightthe Torchslice engine applies to its levels: the Grant & Grigorieff critical dose exp(−0.5·dose/Nc(q)) at the dose the fraction ends with, the hard stop ofsharp_dmg_modetested at the dose it began with, or the Butterworth low-pass atsharp_lvl_dmg/sharp_lvl_ordunder fixed cutoffs. Under the dose models the filters are divided by the first (least exposed) fraction’s, as in the reference notebook, so that fraction is unfiltered and the later ones carry their damage relative to it, capped at 1 and zero wherever the first fraction’s own weight has been hard-stopped; under fixed cutoffs the low-passes apply as they are. The log prints, per fraction, the layers, the exposures, the dose range and the resolution at which its relative filter falls to 0.5 and to 0.1. - Joint reconstruction. One
GSharpReconstructorover all fractions: the single-slice phase grating, the probe (the shifting wrapper that carries the descan, direction and local-defocus models) and the positions are optimised with the chosen loss and optimisers forsharp_lvl_iter[0]iterations. In every iteration the minibatches of the fractions are interleaved, and after each backward pass the object gradient is multiplied in Fourier space by that fraction’s filter before the optimiser steps, so the frequencies a fraction has lost to damage never reach the object from it. Per-position refinement is off when the lag refinement measured its scalar, as in the Torchslice engine. No seeding between levels and no fusion: the object as it stands at the end is the result.
mask/frame_id holds one layer, or is absent) has nothing to fractionate: the whole point set is one fraction with no gradient filter, and Scan layers is forced to 1 so the dose accounting sees the full dose.
Results
Images: ptycho_gsharp_levels.png (amplitude, phase and, with pty_show_spectrum, the log power spectrum of the joint object, whole out to the Nyquist of the reconstructed pixel with the measured pixel’s Nyquist as a dashed square), ptycho_gsharp_summary.png (the phase large with a scale in radians, the amplitude, the power spectrum with resolution rings, the probe as seeded and as it came out with the share of power outside the aperture, their radial profiles, a run card with the fractions and every applied or rejected correction, the loss curve, and the per-fraction gradient filters against spatial frequency as applied, with the cutoffs and the measured Nyquist marked and a resolution axis along the top) and ptycho_gsharp_spectrum_gold.png (the power spectrum of the phase with the gold lines, as in the Torchslice engine).
Scan-coil lag: ptycho_prep_lag_result.json with the lag applied or measured, the half-set registration history, the stripe metric of the object and the fraction table (layers, exposures, dose range and the 0.5 / 0.1 resolutions of each filter).
Data written: ptycho_gsharp_amplitude.mrc / ptycho_gsharp_phase.mrc with the pixel size stamped as the voxel size; the image merge and the particle analysis select the engine with apmerge_source. Phase carries its physical sign, so an MRC phase is the contrast-inverse of the matching PNG panel. With more than one ROI every name gains a _roiN suffix.
80 C — Amplitude phase merge
Purpose
Combines the two channels of the level-fused reconstruction into a single image. Amplitude and phase describe the same object but carry different information about it: the phase resolves fine detail, while the amplitude mostly reports large-scale mass-thickness and is noisy at high frequency. Low-passing the amplitude before the sum keeps its long-range contrast and leaves the fine detail to the phase, instead of adding amplitude noise on top of a sharper channel.
Parameters
Source: apmerge_source chooses which engine's reconstruction is merged. Every engine writes its own files, ptycho_py4dstem_amplitude / ptycho_torchslice_amplitude / ptycho_gsharp_amplitude and the matching phase, and nothing is overwritten by another engine’s run, so any result can be merged regardless of run order. py4DSTEM, torchslice and gsharp read that engine’s files; latest reads the engine the reconstruction step ran last (pty_engine_used), or, when that is not known in the image, the engine whose files on disk are the newest; the log says which. The outputs keep the same names whichever source is chosen, and the particle analysis follows the same choice for its merged / potential sources.
Filters: each channel's filter has its switch, apmerge_amp_filter and apmerge_pha_filter (off: the channel goes into the sum as reconstructed). apmerge_amp_lowpass and apmerge_amp_highpass bracket the amplitude into a BAND (10–200 Å by default; the high-pass may be set to 0 to disable it), and apmerge_pha_highpass cuts the phase background at the same 200 Å. All three are Butterworth, the same form as the damage-limiting filter in stage B, so they behave alike. The amplitude high-pass matters because both channels are normalised before being added: the amplitude carries its own slow ramp from uneven illumination and bulk mass-thickness, and left in, that ramp — not the local contrast — sets the scale of everything the amplitude contributes.
Sign & output: apmerge_invert (flip the phase so both channels read dark on a feature and the sum reinforces instead of partly cancelling), apmerge_clip (display percentile pair for the figure only). Pixel size comes from the MRC voxel size; pacbed_PIX_itr is used only if that header field is empty, and would be the pre-upsampling value.
Algorithm
- Finds every
ptycho_<engine>_amplitude*.mrc/ptycho_<engine>_phase*.mrcof the chosen engine pair on disk. It carries no ROI setting of its own, so it follows a single-ROI and an all-ROI reconstruction automatically and cannot drift out of step with stage B. - Butterworth band-pass on the amplitude and Butterworth high-pass on the phase. The high-passes remove the slow large-scale ramp — residual illumination, sample tilt, the reconstruction’s own low-frequency gauge — which is not specimen contrast and would otherwise set the scale of the sum. The two filters overlap rather than partition: the amplitude supplies everything coarser than its cutoff, the phase everything finer than its own, and both contribute in between.
- Centre-crops every result to the smallest input, since each ROI’s canvas is sized to its own scan extent and they generally differ by a few pixels. Filtering happens at full size first, so the transforms keep the context outside the crop instead of wrapping against a fresh edge.
- z-scores both channels and adds them, so their different offsets and contrasts contribute equally rather than whichever has the larger numerical range dominating.
Results
Images: a_p_merge.png — two rows of three panels: the filtered amplitude, the filtered phase and their sum on top, the unfiltered inputs and their straight sum beneath. Every panel is stretched to its own percentiles, so the rows compare what is resolved, not how dark it looks.
Data written: a_p_merge.mrc (uncompressed float32, unclipped, pixel size stamped as the voxel size). Per ROI it is suffixed _roi1, _roi2, …
a_p_merge.mrc, apart from the reconstruction’s own ptycho_<engine>_* files, so a differently-processed image never overwrites the reconstruction’s output. And apmerge_invert affects only the sum and the figure — the reconstruction’s own phase file keeps its physical sign either way, so it stays usable for quantitative work.
pty_mode set to potential the reconstruction solves a single real channel and writes ptycho_py4dstem_potential.mrc instead, so there is no separate amplitude to merge. The script says so and stops cleanly rather than failing.
99 — Single particle analysis
Purpose
Picks particles out of the merged ptychographic image, extracts and centres them, and runs a reference-free 2D classification. It stops at the 2D class level — no 3D, no refinement. The point is to answer whether the reconstruction carries interpretable single-particle signal at all, and at what resolution, before any of that effort is spent.
Parameters
Input & particle: spa_source (which image on disk: the drift-correction step’s plain shadow montage, shadow_original.mrc, which covers the whole scan and is not ice-hole filtered, since it lies in that step’s own frame; the amplitude+phase merge, the cropped or merged phase, the merged amplitude, the potential, or the deep-shadow step’s sharpest slice, deep_shadow_slice.mrc, whose own frame the ice-hole filter follows automatically), spa_diameter (particle diameter in Å — the one setting that must be right; it sets the picking template, the minimum pick separation, the box, the background ring and the alignment mask), spa_dark (particles darker or brighter than background), spa_pickthr (peak threshold in σ of the correlation map), spa_minsep (minimum pick separation in diameters — a true circular distance).
Ice hole: spa_hole keeps only particles over free ice, discarding those on the carbon rim, and spa_hole_margin sets how far inside the measured rim a particle must sit (200 Å by default, about one apoferritin diameter).
Classification: spa_classes, spa_iters (alignment rounds), spa_bin (box binning — also sets the Nyquist limit no FRC can report past), spa_box (extraction box in Å, 0 = auto at 1.6 × diameter).
Screening & validation: spa_notch (periodic-artifact screen, off by default) and spa_control (the phase-randomised control). Pixel size comes from the MRC header, with pacbed_PIX_itr as a fallback.
Algorithm
- Periodic artifact screen (optional). Finds discrete spikes standing more than 200× above the radial median of their own frequency ring — a median, because a mean would be inflated by the very peaks being looked for. It removes nothing unless the flagged pixels are concentrated in one direction (R > 0.8): a scan error is locked to the raster, while a crystal or a particle packing ring flags at many angles.
- Picking. Template correlation against a soft disc on a 4× binned copy, with a heavily smoothed percentile mask rejecting contamination first. Picks are separated by 0.85 of a diameter so neighbours are not picked twice.
- Ice-hole restriction (optional). Particles on the carbon rim are imaged through a much thicker support and reconstruct poorly, so they are dropped. The boundary comes from the calibration, not the image: the ice-hole step (20) measured the hole centre and diameter in Å in the same frame as the scan positions, and each pick is placed in that frame through its ROI's scan extent.
- Extraction. Boxes are normalised on their background ring, not the whole box, so a box holding a neighbour enters the average on the same footing as an empty one. Every ROI found on disk is picked separately and the particles are then pooled into a single classification, since a single ptychographic field rarely holds enough particles on its own.
- Centring in a single pass against one fixed reference: the rotational average of the particles as picked, low-passed to 25 Å so it keeps the particle envelope. A reference rebuilt from the stack it has just shifted bootstraps itself out of noise and turns the average into a bullseye with a bright central dot — it does so on boxes of pure noise — whereas a fixed reference has nothing to bootstrap. A particle whose correlation peak lands on the edge of the search window is left where it was picked, and the log reports how many.
- Classification. Reference-free multi-reference alignment, seeded by k-means on rotation-invariant polar harmonics so no external reference enters anywhere. Rotation is searched by FFT correlation in polar coordinates with sub-sample peak interpolation, over radii inside the particle only (0.85 of its radius) so that neither the noise outside it nor the rims of neighbouring particles in a packed field steer the alignment. Translations are not refined during classification: doing so against a class reference built from the same particles is the same self-referential loop the centring avoids.
- Validation. Convergence, the phase-randomised control, and per-particle SSNR with a half-set FRC averaged over 12 random splits.
Results
Images: spa_classes.png (class averages sorted by population, with the control classes beneath them), spa_validation.png (SSNR by shell, half-set FRC, and the rotation-convergence trace), and spa_picking_roi<id>.png (the picks drawn on the image, per ROI).
Data written: spa_class_averages.mrc, spa_global_average.mrc, spa_particles.mrc (the extracted, centred, aligned stack) and spa_particles.star — a RELION-style particle list carrying the coordinate, class number, in-plane angle and source ROI for anything downstream.
spa_classes.png you will often see a perfectly plausible-looking particle. That is the point of showing it. Three indicators are reported and weighed together, because no single one is reliable alone:
- Separation — how many classes are populated, real vs control. This is the one the control cannot fake: structureless input has no distinct views, so it collapses into a single class however many are asked for. It carries the most weight.
- Angular feature — the RMS of each class average after its own rotationally symmetric part is removed, which is precisely what the control destroys and the radial profile it preserves does not.
- FRC — real vs control half-set resolution. A matching pair is expected once both saturate at the binned Nyquist limit, and means only that the FRC is uninformative here, not that the data are bad.
scan_hole and the scan stack, and it checks that each image actually covers its ROI's scan extent — a rotated scan frame or an upsampled pixel size would break the placement. If any of that fails it reports the reason in the log and keeps every particle, rather than silently cutting against a boundary it has placed wrongly.
spa_iters if the trace is still falling at the end.
spa_dark first. Getting the contrast sign backwards picks the gaps between particles, and the class averages come out as holes. In the amplitude+phase merge and in the phase as stage B of step 80 inverts it, particles are dark.