Internals

TeeLogger(loggers)

Logger that forwards messages to multiple loggers. Used internally to tee @info output to both console and log file.

Apply ROI cropping to data.

_auto_camera(cfg::DetectFitConfig) -> AbstractCamera

Resolve camera from DetectFitConfig. Uses cfg.camera if set, otherwise auto-builds from MIC H5 calibration when pixel_size is provided.

Calculate inter-dataset shift magnitudes in nm (Euclidean distance)

Calculate max intra-dataset drift using drift_trajectory

_calculate_mode(values; n_bins=100)

Calculate the mode of a distribution using histogram binning. Returns the center of the most populated bin.

Uses a median-centered range (median ± 3×MAD) to avoid outlier peaks at large fitted PSF sigma pulling the mode away from the true peak.

Reconstruct SMLD from columnar format.

_compute_bin_stat(xs, ys, values, cfg, stat_fn) -> Matrix{Float64}

Bin emitters spatially and compute stat_fn(bin_values) per bin. Returns n_bins × n_bins grid in Makie convention: grid[ix, iy] maps to (x_centers[ix], y_centers[iy]) when used with heatmap!(ax, x_centers, y_centers, grid).

This is the fundamental convention: first array index = x-axis (horizontal), second = y-axis (vertical). Julia arrays are (row, col) = (y, x) in image convention, but Makie's heatmap maps first index to x. So we store as [ix, iy].

_compute_crosscorr(smld_a, smld_b, cfg) -> (r, g, area)

Compute pair cross-correlation g(r) between two SMLDs using KDTree + Ripley's edge correction.

_compute_intensity_pvalues(xs, ys, photons, field_model)

Compute Poisson upper-tail p-values for each emitter. p = P(X ≥ N) where X ~ Poisson(λ) and λ = field_model(x, y).

λ is the per-bin percentile (upper bound of single-emitter emission at this position), so emitters near or below λ get p ≈ 1 (kept), while emitters far above λ get small p.

_construct_emitters(...)

Internal: Construct emitters of the appropriate type based on emittertypestr.

_convolve_1d(h::Vector{Float64}) -> Vector{Float64}

Self-convolution of histogram h. Returns vector of length 2n-1 where n = length(h). The result represents the distribution of the sum of two independent draws from h.

_default_colors(n::Int) -> Vector{Symbol}

Default color palette for multi-target rendering. 2 channels: cyan/magenta. 3 channels: cyan/magenta/yellow. Supports up to 6 channels; provide explicit colors for more.

Detect H5 file format by checking internal structure

_empty_emitters(emitter_type_str, T, is_3d)

Internal: Create empty emitter vector of appropriate type.

_estimate_bleaching_rate(frame_counts) -> NamedTuple or nothing

Fit N(t) = a + b*exp(-k*t) to a per-frame localization count vector via linearized initial guess + Nelder-Mead refinement.

This is the OBSERVED decay rate, not the true kbleach for GenericFluor: bleaching only occurs from the On state, so `kobserved = kbleach * Pon, wherePon = kon/(kon+koff)is the duty cycle. To get true k_bleach:kbleach = kobserved / P_on`.

Returns (k_bleach, N_0, offset, half_life, r_squared, valid_frames, smoothed) or nothing if the fit fails.

_estimate_excitation_field(xs, ys, photons, lambda_global, cfg, verbose)

Estimate excitation field from per-bin percentiles of photon counts.

Each spatial bin computes quantile(photons, rate_percentile) independently, capturing the local upper bound of single-emitter emission. A Gaussian field model is then fit to these per-bin rates to produce a smooth field_model(x, y).

Returns (actual_mode, field_params, r2, field_model).

Estimate koff from track length distribution. For geometric distribution: mean = 1/koff, so k_off = 1/mean

_estimate_p2(xs, ys, photons, field_model, cfg) -> (p2, tail_obs, tail_f2)

Estimate double-emitter fraction via mixture decomposition of field-normalized photons.

Algorithm:

1. Compute normalized photons: n_i = photons_i / λ(x_i, y_i)
2. Histogram fobs with `p2n_binsbins over[0, p99.5]`
3. Self-convolve: f₂ = conv(f_obs, f_obs) — distribution of sum of two singles
4. At threshold τ: p₂ = Σf_obs(>τ) / Σf₂(>τ)

Returns (nothing, nothing, nothing) if estimation fails (e.g., zero tail mass).

Determine box color based on FilterConfig thresholds. All-nothing filters = all green.

_fit_gaussian_field(cx, cy, rates, xs, ys)

Fit N(x,y) = A·exp(-2·((x-x₀)² + (y-y₀)²)/w²) + bg to per-bin rates.

Returns (params::NamedTuple, r2::Float64) or (nothing, 0.0) on failure.

Build title string from actual FilterConfig thresholds.

Format a possibly-nothing numeric value for stats output.

_get_gaussmle_emitter_types()

Internal: Try to get GaussMLE emitter types if the package is loaded. Returns nothing if GaussMLE is not available.

_get_psf_sigma_bounds(range_spec, values) -> (lo, hi)

Calculate PSF sigma filter bounds.

• :auto → mode ± 10%
• (min, max) → explicit bounds in microns

_grid_figure_size(data; n_cols=4, n_rows=3, panel_height=200)

Calculate figure size for grid overlay plots based on data aspect ratio.

_inject_camera(cfg::DetectFitConfig, camera::AbstractCamera) -> DetectFitConfig

Inject camera into DetectFitConfig if not already set. Used by AnalysisConfig pipeline.

Check if a value is a config-like struct (has fields, not a primitive/collection).

Load images from a data source

Normalize input data to Vector{AbstractArray{<:Real,3}} for uniform processing.

_plan_sample_frames(ds_frame_counts::Vector{Int}, n_samples::Int=12)

Precompute which frames to sample across all datasets for overlay plots. Always includes first and last absolute frames, with equal spacing between.

Returns (plan, abs_frames):

• plan::Dict{Int, Vector{Int}}: dataset index → local frame indices to capture
• abs_frames::Vector{Int}: absolute frame numbers for display labels (in order)

Pre-dispatch hook: inject pipeline-level config into step configs.

_find_final_smld_step(steps) -> Int

Walk steps in reverse and return the 1-based index of the last step that produces a BasicSMLD (i.e., not a terminal render). Returns 0 if no SMLD-producing step is found.

Used by _run_pipeline to translate Checkpoint.END into a per-step "this is the final, save it" decision.

_resolve_colors(cfg::CompositeRenderConfig, defaults::Vector{Symbol}) -> Vector{Symbol}

Use per-step colors if specified, otherwise fall back to MultiTargetConfig defaults.

Resolve file-based sources from config options.

Returns a vector of NamedTuples describing each dataset to load. Dataset count is determined from the data structure, not from a config field.

_resolve_psf_bounds(emitters, cfg) -> Union{NamedTuple, Nothing}

Pre-resolve PSF sigma filter bounds from the emitter population. Returns named tuple with :iso or :aniso bounds, or nothing if psf_sigma filter is off.

_rightmost_significant_peak(smoothed, peak_threshold) -> Int

Index of the rightmost local maximum of smoothed (a value ≥ both neighbours, with a missing right edge treated as 0) whose height is at least peak_threshold. Returns 1 if none qualifies. Shared by the valley-threshold search and the diagnostic figure so both mark the same peak.

_ripley_edge_weight(x, y, r, bounds) -> Float64

Ripley's isotropic edge correction: fraction of circle circumference at (x,y) with radius r that falls inside the rectangular FOV defined by bounds.

Returns a weight in (0, 1]. Points near boundaries get lower weights, which are inverted to up-weight their contributions.

_run_pipeline(initial_state, steps, camera, outdir, verbose)

Internal pipeline executor. Folds analyze() dispatch over the steps vector, threading state through each step. Step routing is determined entirely by Julia's method dispatch on (state_type, config_type).

Wrong step ordering produces a MethodError — e.g., FilterConfig before DetectFitConfig gives no method matching analyze(::Vector{...}, ::FilterConfig).

_save_box_overlay(dir, filename, images, roi_batch, box_colors; ...)

ROIBatch convenience (detectfit/filter): unpack x_corners/y_corners/frame_indices/roi_size and delegate to the core renderer above. Behavior unchanged for existing callers.

_save_box_overlay(dir, filename, images, x_corners, y_corners, frame_indices, box_size, box_colors; ...)

Core box-overlay renderer: a grid of sample frames (contrast-stretched grayscale) with a colored box_size rectangle drawn at each (x_corner, y_corner) on its frame. This is the shared "boxes on the raw data" diagnostic style — detectfit (detection_overlay.png) and filter (fit_overlay.png) render through it so the whole pipeline's overlays are one visual family.

The box-geometry is passed as plain arrays so non-ROIBatch callers use the identical renderer; see the roi_batch convenience method below.

Save calibration diagnostic plots from FrameConnectInfo.calibration. Called when calibration was enabled and outdir is set.

Plot uncertainty calibration: binned observed vs CRLB variance with WLS fit line. FC stores bin data in μm²; convert to nm² for readable axes.

Save step config to config.toml in the step output directory.

Plot drift trajectory with global frame view for multi-dataset acquisitions. Uses drift_trajectory default mode (inter + intra per chunk) so boundary discontinuities between chunks are visible as gaps.

Save sample frame data to pipeline cache for the filter step to generate fit_overlay.png.

Decomposes ROIBatch into plain arrays (avoids camera serialization issues with JLD2).

Plot frame-to-frame drift jitter and cumulative drift from linked emitters. Three panels: jitter X, jitter Y (top), cumulative drift (bottom). Uses global frame numbering (absolute_frame across datasets).

_save_drift_model!(group, dm::LegendrePolynomial, compression)

Save LegendrePolynomial drift model to HDF5 group.

_save_filter_quality_figures(dir, smld_raw, cfg)

Generate fit quality distribution plots with filter thresholds highlighted. Shows photons, background, precision, p-value, and PSF sigma distributions from the raw (unfiltered) SMLD, with rejected regions marked per FilterConfig.

Generate fit overlay: boxes colored by fit quality using FilterConfig thresholds.

Colors: green=pass, red=photons fail, orange=precision fail, purple=pvalue fail, gray=no match.

Load detectfit sample cache and generate fit_overlay.png with FilterConfig thresholds. Gracefully skips if cache is missing (e.g., standalone filter without prior detectfit).

_save_info!(dir::String, info; section::String="")

Write upstream Info struct fields to info.toml in TOML format.

Writes scalar fields (numbers, bools, strings, symbols, tuples of scalars). Skips complex fields (arrays, dicts, structs like BasicSMLD, models).

When section is empty, writes a fresh file with type header. When section is provided, appends a [section] block.

_save_loc_per_frame(dir, smld; filename, title) -> bleach_result or nothing

Plot localizations per absolute frame across all datasets, with photobleaching exponential decay fit overlay (a + b*exp(-k*t)). Marks dataset boundaries for multi-dataset SMLDs.

Used by detectfit (raw fits) and filter (post-filter fits) steps.

_save_multitarget_config!(config::MultiTargetConfig)

Serialize MultiTargetConfig to TOML file in the output directory.

_save_pipeline_config!(dir, steps, camera, roi, verbose, checkpoint)

Write the orchestration-level AnalysisConfig to dir/config.toml.

Mirrors the per-step _save_config! (which writes each step's config into its own subdir) but captures what those don't: the camera, the global ROI crop, verbosity, checkpoint level, and a manifest of the step sequence.

Plot histogram of frame-to-frame shifts from calibration analysis.

_save_step_smld(dir, smld; filename, kwargs...)

Persist a step's output SMLD via JLD2 so downstream iteration (e.g., diagnostic plots, parameter sweeps, BaGoL re-runs) can resume without re-running the upstream pipeline. The SMLD is stored under the smld key:

data = JLD2.load("path/smld_corrected.jld2")
smld = data["smld"]   # full BasicSMLD with camera, n_frames, n_datasets

Extra named values are stored as additional top-level keys (e.g., pass drift_model=drift_model to embed the drift model alongside the SMLD).

No-op if dir is nothing.

Apply cfg.datasets selection to a resolved source list. Bounds-checks and returns the selected subset in the order given. Pass-through when cfg.datasets is nothing.

Convert SMLD emitters to columnar format for fast JLD2 serialization. Returns a NamedTuple with arrays for each field.

_spatial_bin_rates(xs, ys, photons, cfg)

Bin emitters spatially and compute rate_percentile of photons per bin. Returns named tuple with centers_x, centers_y, rates, counts, and grid info.

Find threshold using valley detection between isolated (low neighbors) and clustered (high neighbors).

Algorithm:

1. Build and smooth histogram
2. Find rightmost significant peak (clustered population)
3. Find local minimum (valley) between origin and that peak
4. If no clear valley (unimodal), use heuristics based on peak position

Update emitter's dataset field using struct reconstruction

_with_log_file(f, outdir)

Run f() with @info output teed to outdir/log.txt. If outdir is nothing, just runs f() directly.

_write_camera!(io, cam)

Write a compact [camera] provenance block: type, pixel grid dimensions, and pixel size derived from the edge vectors (rather than dumping the full edges). sCMOS calibration fields are written as scalars, or summarized by shape if maps.

_write_composite_readme!(composite_dir, config, smlds, step_infos)

Write a README.md in the composite directory documenting the color scheme, channel labels, multi-target steps, and per-channel localization counts.

Write config fields to TOML. Nested structs become [section] blocks.

_write_detection_frame_movies(dir, stacks, abs_frames, fps, v)

DEBUG-verbosity output. For each detection-overlay gallery frame, write a short realtime MP4 of the raw camera frames. stacks[k] is a (H, W, ~100)-frame window containing gallery frame abs_frames[k] (same order as the overlay panel). Contrast is ONE global linear stretch over the whole 100-frame window: black point = 0.1st percentile (0.001), white point = 99.9th percentile (0.999) of all pixels in the window. Played at fps (realtime = 1/exposure). A label (frame / fps / stretch percentiles / black-white values) is burned into each frame. Files: dir/frame_movies/detection_frame_<gallery_frame>.mp4. Requires ffmpeg on PATH.

Write a single field to info.toml, skipping complex types.

Write residual correlation section to stats.md.

bagol_step(smld, cfg; outdir=nothing, step_number=0, verbose=Verbosity.STANDARD)

Group localizations into emitters via BaGoL. Returns (bagol_smld, BaGoLInfo).

cache_dir(outdir) -> Union{String, Nothing}

Returns joinpath(outdir, ".cache") or nothing if outdir is nothing.

composite_render_step(smlds, cfg; outdir, step_number, verbose, colors) -> (smlds, CompositeRenderInfo)

Render a multi-channel composite image. SMLDs pass through unmodified.

crossalign_step(smlds, cfg; outdir, step_number, verbose) -> (aligned_smlds, CrossAlignInfo)

Align multiple SMLDs to a common reference using entropy-based alignment.

crosscorr_step(smlds, cfg; outdir, step_number, verbose, labels) -> (smlds, CrossCorrInfo)

Compute pair cross-correlation g(r) between two channels. SMLDs pass through unmodified.

densityfilter_step(smld, cfg; outdir=nothing, step_number=0, verbose=Verbosity.STANDARD)

Filter localizations by neighbor density. Returns (filtered_smld, DensityFilterInfo).

Arguments

• smld::BasicSMLD: Input localizations
• cfg::DensityFilterConfig: Density filter parameters

Keyword Arguments

• outdir: Output directory (nothing to skip file output)
• step_number: Step number for output directory naming
• verbose: Verbosity level

Returns

(filtered_smld, DensityFilterInfo)

detectfit(images::AbstractArray{<:Real,3}, camera, cfg; kwargs...) -> (smld, info)

Convenience method for a single image stack. Wraps into a 1-element vector.

detectfit(camera, cfg; kwargs...) -> (smld, info)

File-based detectfit. Loads image data from cfg.path or cfg.paths. Each data source is loaded one at a time for memory efficiency.

detectfit(data, camera, cfg; kwargs...) -> (smld, DetectFitInfo)

Run combined detection and fitting on image data.

Arguments

• data::Vector{<:AbstractArray{<:Real,3}}: Vector of image stacks (one per dataset)
• camera::AbstractCamera: Camera model
• cfg::DetectFitConfig: Detection and fitting configuration

Keywords

• outdir::Union{String,Nothing}=nothing: Output directory for results
• step_number::Int=1: Step number in the pipeline
• verbose::Int=Verbosity.STANDARD: Verbosity level

Returns

(smld::BasicSMLD, info::DetectFitInfo)

driftcorrect_step(smld, cfg; outdir, step_number, verbose) -> (corrected_smld, DriftInfo)

Run drift correction on smld, returning the corrected SMLD as the primary result, plus the upstream DriftInfo.

Returns

(corrected_smld, DriftInfo)

filter_step(smld, cfg; outdir=nothing, step_number=0, verbose=Verbosity.STANDARD)

Filter localizations by quality criteria. Returns (filtered_smld, FilterInfo).

Diagnostic plots use smld (the input) for pre-filter distributions.

Arguments

• smld::BasicSMLD: Input localizations
• cfg::FilterConfig: Filter criteria

Keyword Arguments

• outdir: Output directory (nothing to skip file output)
• step_number: Step number for output directory naming
• verbose: Verbosity level

Returns

(filtered_smld, FilterInfo)

frameconnect_step(smld, cfg; outdir, step_number, verbose) -> (combined_smld, FrameConnectInfo)

Run frame connection on smld, returning the combined (recombined) SMLD as the primary result, plus the upstream FrameConnectInfo.

When cfg.calibration is set, uncertainty calibration is applied before combination: link -> calibrate -> combine (single pass with correct weights).

Returns

(combined_smld, FrameConnectInfo)

intensityfilter_step(smld, cfg; outdir=nothing, step_number=0, verbose=Verbosity.STANDARD)

Filter localizations by intensity-based multi-emitter rejection. Returns (filtered_smld, IntensityFilterInfo).

load_cache(outdir, filename) -> Union{Dict, Nothing}

Load data from outdir/.cache/filename via JLD2. Returns nothing if missing or outdir is nothing.

render_step(smld, cfg; outdir=nothing, step_number=0, verbose=Verbosity.STANDARD)

Render localizations to a super-resolution image. Returns (render_image, RenderInfo).

Arguments

• smld::BasicSMLD: Input localizations
• cfg::SMLMRender.RenderConfig: Render configuration

Keyword Arguments

• outdir: Output directory (nothing to skip file output)
• step_number: Step number for output directory naming
• verbose: Verbosity level

Returns

(render_image, RenderInfo)

save_cache(outdir, filename; kwargs...)

Save data to outdir/.cache/filename via JLD2. No-op if outdir is nothing.