Step Configs & Info

DetectFitConfig <: AbstractSMLMConfig

Combined detection and fitting step. Detects ROIs via SMLMBoxer and fits localizations via GaussMLE in a single step, with per-dataset processing.

Embedded Configs

• boxer::BoxerConfig: Detection parameters (boxsize, minphotons, psfsigma, etc.)
• fitter::GaussMLEConfig: Fitting parameters (psf_model, iterations, constraints, etc.)

Data Source Keywords (for file-based workflows)

• path: Single H5 file path
• paths: Vector of H5 file paths (one per dataset)
• dataset_frames: Explicit frame ranges per dataset
• h5_format: :auto, :smart, or :mic

Dataset Selection

• datasets: Optional AbstractVector{Int} (e.g. 1:19 or [1,2,3,5]) selecting a subset of the resolved source slots. Applies uniformly across all source modes: MIC auto-blocks, multi-path paths, explicit dataset_frames, and in-memory Vector{Array} input. Selected slots are reindexed to contiguous 1:length(datasets) in the output SMLD (original source indices preserved in DetectFitInfo.selected_source_indices). Default nothing uses all resolved slots.

FilterConfig <: AbstractSMLMConfig

Quality-based filtering of localizations. All criteria use (min, max) tuples.

Keywords

• photons: Photon count range, e.g. (500.0, Inf)
• precision: Lateral localization precision range in microns, max(σ_x, σ_y), e.g. (0.0, 0.007)
• pvalue: Goodness-of-fit p-value range, e.g. (1e-3, 1.0)
• psf_sigma: PSF width filter. :auto uses mode ± 10%, or explicit (min, max) in microns
• z: Axial position range in microns (3D fits only), e.g. (-0.4, 0.4). Useful to drop localizations railed to the z-grid edge. No-op on 2D SMLDs.
• sigma_z: Axial precision range in microns (3D fits only), e.g. (0.0, 0.030). The axial analog of precision. No-op on 2D SMLDs.

All filters default to nothing (disabled).

IntensityFilterConfig <: AbstractSMLMConfig

Intensity-based multi-emitter rejection. Estimates the spatially-varying expected single-emitter photon rate and rejects localizations whose photon count is statistically inconsistent with single-emitter emission (Poisson upper-tail test).

The rate estimate uses the rate_percentile of the per-bin photon distribution (default: 95th percentile). This captures the upper bound of single-emitter emission at each spatial position, accounting for both excitation field variation and stochastic on-time variance. The Gaussian field fit then smooths across bins.

Keywords

• cutoff::Float64: P-value cutoff; emitters with p < cutoff are rejected (default: 0.01)
• field_mode::Symbol: Excitation field model — :uniform (single global rate) or :gaussian (spatially-varying Gaussian beam fit) (default: :gaussian)
• n_bins::Int: Spatial grid bins per axis for field estimation (default: 10)
• min_bin_count::Int: Minimum emitters per bin for rate estimation (default: 30)
• rate_percentile::Float64: Percentile of per-bin photon distribution used as the expected single-emitter rate (default: 0.95). Higher = more permissive.

DensityFilterConfig <: AbstractSMLMConfig

Density-based filtering that removes isolated localizations lacking nearby neighbors.

Keywords

• n_sigma: Search radius in localization uncertainty units (default: 2.0)
• min_neighbors: Minimum neighbor count. :auto uses valley detection between isolated and clustered populations (default: :auto)

FrameConnectConfig

Configuration parameters for frame connection algorithm.

Fields

• n_density_neighbors::Int=2: Number of nearest preclusters used for local density estimates (see estimatedensities)
• max_sigma_dist::Float64=5.0: Multiplier of localization errors that defines a pre-clustering distance threshold (see precluster)
• max_frame_gap::Int=5: Maximum frame gap between temporally adjacent localizations in a precluster (see precluster)
• max_neighbors::Int=2: Maximum number of nearest-neighbors inspected for precluster membership (see precluster)
• track_length::Union{Tuple{Float64,Float64}, Nothing}=nothing: Inclusive (min, max) range on the number of localizations a track must contain to be emitted as a combined localization (lo <= nperID <= hi). Counts localizations sharing a track_id, not temporal frame-span. nothing (default) disables filtering. Use (2.0, Inf) to drop single-frame blinks, or (2.0, 50.0) to also drop over-long tracks (e.g. fiducials, sticky docking strands in dense DNA-PAINT). Mirrors the (min, max) filter idiom used elsewhere in the ecosystem. See combinelocalizations.
• calibration::Union{CalibrationConfig, Nothing}=nothing: Optional uncertainty calibration

Example

# Without calibration (default)
(combined, info) = frameconnect(smld)

# With calibration
config = FrameConnectConfig(calibration=CalibrationConfig())
(combined, info) = frameconnect(smld, config)

# With calibration + chi2 filtering
config = FrameConnectConfig(
    calibration=CalibrationConfig(filter_high_chi2=true, chi2_filter_threshold=4.0)
)
(combined, info) = frameconnect(smld, config)

CalibrationConfig

Configuration for optional uncertainty calibration within frame connection.

Calibration analyzes frame-to-frame jitter within connected tracks to estimate a motion variance (σ_motion²) and CRLB scale factor (k²), then applies corrected uncertainties before track combination: Σ_corrected = σ_motion² I + k² Σ_CRLB.

Fields

• clamp_k_to_one::Bool=true: Clamp k_scale to minimum of 1.0 (CRLB is a lower bound)
• filter_high_chi2::Bool=false: Filter tracks with high chi² pairs before fitting
• chi2_filter_threshold::Float64=6.0: Chi² threshold for track filtering (per pair)

DriftConfig <: AbstractSMLMConfig

Configuration for drift correction, holding all algorithm parameters. Constructed with keyword arguments; all fields have sensible defaults.

Fields

Example

julia> config = DriftConfig(quality=:iterative, degree=3);

julia> config.quality
:iterative

julia> config.degree
3

julia> config.convergence_tol
0.001

RenderConfig <: AbstractSMLMConfig

Flat rendering configuration. Fields correspond 1:1 with render() keyword arguments.

Fields

• strategy::RenderingStrategy: Rendering algorithm (default: GaussianRender())
• pixel_size::Union{Float64, Nothing}: Pixel size in nm (data bounds mode)
• zoom::Union{Float64, Nothing}: Zoom factor (camera FOV mode)
• roi::Union{Tuple, Nothing}: Camera pixel ROI as (x_range, y_range)
• target::Union{Image2DTarget, Nothing}: Explicit target specification
• colormap::Union{Symbol, Nothing}: Intensity-based colormap (:inferno, :viridis, etc.)
• color_by::Union{Symbol, Nothing}: Field for field-based coloring (:z, :photons, etc.)
• color::Union{RGB, Symbol, Nothing}: Manual color
• categorical::Bool: Use categorical palette for integer fields (default: false)
• clip_percentile::Union{Float64, Nothing}: Intensity clipping percentile (default: 0.99). Use nothing for saturate mode (no normalization, values can exceed 1.0).
• field_range::Union{Tuple{Float64,Float64}, Symbol}: Value range or :auto
• field_clip_percentiles::Union{Tuple{Float64,Float64}, Nothing}: Percentile clipping
• backend::Symbol: Computation backend (default: :cpu)
• filename::Union{String, Nothing}: Save to file if provided
• scalebar::Bool: Enable scale bar overlay (default: false)
• scalebar_length::Union{Float64, Nothing}: Physical length in μm (nothing = auto)
• scalebar_position::Symbol: Corner position (:br, :bl, :tr, :tl)
• scalebar_color::Symbol: Bar color (:white or :black)

BaGoLConfig <: SMLMData.AbstractSMLMConfig

Configuration for BaGoL analysis. All fields correspond 1:1 to run_bagol kwargs.

Count Model

• μ=10.0: Mean localizations per emitter
• shape=2.0: Gamma shape (1=exponential/dSTORM, >1=peaked/DNA-PAINT)
• learn_distribution=true: Learn count params. true=both, false=fix both, :mu=learn μ only, :shape=learn shape only
• gamma=nothing: DM concentration. nothing=use shape (default), Float64=fixed
• learn_rho=true: Learn Poisson-K emitter density ρ independently of μ/shape. For fully fixed hyperparameters, set both learn_distribution=false and learn_rho=false.
• rho=nothing: Initial ρ in emitters per unit area. If provided with learn_rho=false, hold this fixed for Fazel-style fixed-ρ-over-bounding-box flat Poisson-K runs.

MCMC

• n_iterations=4000: Total MCMC iterations
• burn_in=2000: Burn-in before accumulating
• sync_interval=100: Iterations between global hierarchical updates
• allocation_model=:dm: :dm (Dirichlet-Multinomial), :decoupled (no partition prior), or :categorical (labeled K^(-N) — Fazel-equivalent when paired with spatial_model=:flat + k_prior=:none)
• spatial_model=:locmix: :locmix (localization mixture) or :flat
• k_prior=:auto: K-prior gating. :auto uses spatial-model default (Poisson(ρA) under :flat, none under :locmix); :poisson always include (only valid with :flat); :none always disable
• n_restricted_scans=5: Jain-Neal restricted Gibbs scans for split/merge
• n_bd_substeps=5: Birth/death substeps per BD selection

Partitioning

• partition_sigma=3.0: DBSCAN threshold in sigma units (Inf=no partitioning)
• min_partition_size=0: Minimum locs per partition
• max_partition_size=1000: METIS-split partitions larger than this
• skip_partition_size=typemax(Int): Skip partitions larger than this
• overlap=:auto: Overlap width for bisected partitions (:auto or Float64 in μm)
• bridge_ratio=0.0: Optional bridge refinement strength for DBSCAN clusters
• min_split_size=3: Minimum core component size for bridge refinement

Uncertainty Correction (standalone; 0 in the integrated pipeline)

• se_adjust=:auto: :auto runs the finder (estimate_se_adjust) and uses τ̂ (skipped if the SMLD is already σ-corrected); 0.0 = no correction; a numeric value = manual τ (μm) added in quadrature to per-loc σ (σ²+τ²) — scalar, (τx,τy) tuple, length-N vector, or (τx_vec,τy_vec).
• force_se_adjust=false: Apply even if the SMLD is already σ-corrected.

Output

• posterior_pixel_size=0.001: Rao-Blackwellized posterior image pixel size in μm (1 nm; 0.0=disable)
• archive_path=nothing: Mmap chain archive path (nothing=disable)
• progress_file=nothing: Write progress to file (nothing=disable)
• verbose=true: Print progress to stdout

DetectFitInfo <: AbstractSMLMInfo

Info from combined detection and fitting step.

selected_source_indices records the original source slot indices when DetectFitConfig.datasets selected a subset (e.g. [1,2,3,5,7] when a corrupted block was skipped). nothing means no selection was applied and the output datasets correspond 1:1 to the resolved source slots.

FilterInfo <: AbstractSMLMInfo

Info from quality filtering step.

IntensityFilterInfo <: AbstractSMLMInfo

Info from intensity-based multi-emitter rejection step.

Fields

• n_before::Int: Emitter count before filtering
• n_after::Int: Emitter count after filtering
• field_mode::Symbol: Actual field mode used (:uniform or :gaussian, may fallback)
• lambda_max_global::Float64: Global mode photon count
• field_params::Union{NamedTuple, Nothing}: Gaussian field params (A, x0, y0, w, bg) or nothing
• field_fit_r2::Float64: R² of field fit (0.0 for uniform)
• elapsed_s::Float64: Elapsed time (s)
• p2_estimate::Union{Float64, Nothing}: Estimated double-emitter fraction
• p2_tail_threshold::Float64: Normalized threshold used for p₂ estimation
• p2_tail_obs::Union{Float64, Nothing}: Observed tail mass fraction above threshold
• p2_tail_f2::Union{Float64, Nothing}: Double-distribution tail mass fraction above threshold

DensityFilterInfo <: AbstractSMLMInfo

Info from density-based filtering step.

BaGoLInfo <: AbstractSMLMInfo

Info from BaGoL grouping step.

Fields

• n_locs_in::Int: Input localization count
• n_emitters::Int: Output emitter count
• compression::Float64: Compression ratio (nlocsin / n_emitters)
• final_μ::Float64: Final mean localizations per emitter
• final_shape::Float64: Final NegBin shape parameter
• n_partitions::Int: Number of spatial partitions used
• diagnostics::SMLMBaGoL.BaGoLDiagnostics: Full diagnostics for advanced use