API Reference

GaussMLE

Maximum-likelihood fitting of Gaussian PSF models to single-molecule ROIs, on the CPU or a CUDA GPU, with Cramér-Rao lower bound uncertainties. Noise models: Poisson (IdealCamera) and sCMOS (SCMOSCamera, per-pixel readout noise).

Entry points: fit with a GaussMLEConfig or keywords; PSF models GaussianXYNB, GaussianXYNBS, GaussianXYNBSXSY and AstigmaticXYZNB; generate_roi_batch for simulated data. Results are SMLMData.BasicSMLD with model-specific emitter types.

GaussMLEConfig{P,PC,W}

Main type for configuring and performing Maximum Likelihood Estimation of Gaussian blob parameters.

Fields

• backend::Symbol: Compute backend (:cpu, :gpu, or :auto)
• psf_model::P<:PSFModel: Point spread function model
• iterations::Int: Number of Newton-Raphson iterations
• constraints::PC<:Union{Nothing, ParameterConstraints}: Parameter bounds and step limits; nothing builds defaults from the ROI size at fit time
• batch_size::Int: Batch size for GPU processing
• auto_timeout::Float64: Seconds to wait for GPU in auto mode
• gpu_timeout::Float64: Seconds to wait for GPU in explicit gpu mode
• on_wait: Callback for GPU wait progress feedback

See also

fit, GaussMLEFitInfo, PSFModel

fit(data::AbstractArray{T,3}, fitter::GaussMLEConfig; variance_map=nothing) ->
    (BasicSMLD, GaussMLEFitInfo)

Fit Gaussian blobs to a stack of ROIs using Maximum Likelihood Estimation.

Arguments

• data::AbstractArray{T,3}: ROI data as (roisize, roisize, n_rois) array
• fitter::GaussMLEConfig: Configured fitter object

Keyword Arguments

• variance_map=nothing: Poisson noise when nothing; a supplied readnoise-variance map (electrons²) selects the sCMOS path for data already calibrated in electrons

Array input assumes 0.1 μm pixels and synthetic horizontally tiled ROI corners. Use ROIBatch for real camera calibration and coordinates.

Returns

• Tuple{BasicSMLD, GaussMLEFitInfo}: Fitted localizations and fit metadata

Examples

# Fit 1000 ROIs
data = zeros(Float32, 7, 7, 1000)  # Your ROI data here
fitter = GaussMLEConfig(psf_model = GaussianXYNB(0.13f0))
smld, info = fit(data, fitter)

# Access results
println("Fitted $(info.n_fits) ROIs in $(info.elapsed_s * 1000) ms")
println("Mean x position: ", mean([e.x for e in smld.emitters]))

See also

GaussMLEConfig, GaussMLEFitInfo

fit(batch::ROIBatch; psf_model=GaussianXYNB(0.13f0), iterations=20,
    backend=:auto, ...) -> (BasicSMLD, GaussMLEFitInfo)

Convenience form of fit() that creates a GaussMLEConfig from keyword arguments. Kwargs match GaussMLEConfig fields exactly.

Arguments

• batch::ROIBatch: Input ROI data with camera calibration

Keyword Arguments

• psf_model=GaussianXYNB(0.13f0): PSF model to use
• iterations=20: Number of Newton-Raphson iterations
• backend=:auto: Compute backend (:cpu, :gpu, or :auto)
• constraints=nothing: Parameter constraints; nothing builds defaults from the ROI size at fit time
• batch_size=10_000: Batch size for GPU processing
• auto_timeout=300.0: Seconds to wait for GPU in auto mode
• gpu_timeout=Inf: Seconds to wait for GPU in explicit gpu mode
• on_wait=nothing: Callback for GPU wait progress

Returns

• Tuple{BasicSMLD, GaussMLEFitInfo}: Fitted localizations and fit metadata

Examples

Fit 10 simulated ROIs on the CPU:

julia> batch = generate_roi_batch(IdealCamera(64, 64, 0.1), GaussianXYNB(0.13f0);
           n_rois = 10, seed = 1);

julia> smld, info = fit(batch; backend = :cpu);

julia> length(smld.emitters), info.n_fits
(10, 10)

With the default backend = :auto, which uses a GPU when one is available:

# Simple fit with defaults
smld, info = fit(batch)

# Custom model and iterations
smld, info = fit(batch; psf_model=GaussianXYNBS(), iterations=30)

See also

GaussMLEConfig, GaussMLEFitInfo

GaussMLEFitInfo

Metadata about a fit operation, returned as the second element of the fit() tuple.

Fields

• elapsed_s::Float64: Elapsed time in seconds
• backend::Symbol: Actual execution backend (:cpu or :gpu, never :auto)
• device_id::Int: GPU device index (0-based) or -1 for CPU
• n_fits::Int: Number of ROIs attempted
• n_converged::Int: Number of ROIs that converged (currently equals n_fits since all iterations run)
• batch_size::Int: Actual batch size used for processing
• n_batches::Int: Number of batches processed (1 if all-at-once)
• memory_per_batch::Int: Estimated memory bytes per batch

Example

smld, info = fit(batch, fitter)
println("Fit $(info.n_fits) ROIs in $(info.elapsed_s * 1000) ms on $(info.backend)")
println("Processed in $(info.n_batches) batches of $(info.batch_size)")

See also

fit, GaussMLEConfig

PSFModel{NParams,T}

Abstract type for point spread function models.

The type parameter NParams specifies the number of fitting parameters at compile time, enabling type-stable code generation. The type parameter T specifies the numeric type.

GaussianXYNB{T} <: PSFModel{4,T}

2D Gaussian PSF with fixed width σ.

Parameters (in order)

1. x: x-position (fitted in ROI pixels, output in microns)
2. y: y-position (fitted in ROI pixels, output in microns)
3. N: total signal (photons for IdealCamera, electrons for sCMOS)
4. bg: background per pixel

Fields

• σ::T: Fixed Gaussian width (standard deviation in microns)

Example

julia> psf = GaussianXYNB(0.13f0)  # σ = 130 nm (typical ~500nm emission, 100nm pixels)
GaussianXYNB(σ=0.13)

julia> fitter = GaussMLEConfig(psf_model = psf);

Note

PSF width is specified in physical units (microns) for camera-independence. Internally converted to pixels based on camera pixel size during fitting.

GaussianXYNBS{T} <: PSFModel{5,T}

2D Gaussian PSF with variable width σ (fitted parameter).

Parameters (in order)

1. x: x-position (fitted in ROI pixels, output in microns)
2. y: y-position (fitted in ROI pixels, output in microns)
3. N: total signal (photons for IdealCamera, electrons for sCMOS)
4. bg: background per pixel
5. σ: Gaussian width (fitted in pixels, output in microns)

Example

psf = GaussianXYNBS()  # Variable sigma (no fixed value)
fitter = GaussMLEConfig(psf_model = psf)

Note

The fitted σ parameter is stored in microns in Emitter2DFitSigma output.

GaussianXYNBSXSY{T} <: PSFModel{6,T}

2D Anisotropic Gaussian PSF with independent x and y widths (both fitted parameters).

Parameters (in order)

1. x: x-position (fitted in ROI pixels, output in microns)
2. y: y-position (fitted in ROI pixels, output in microns)
3. N: total signal (photons for IdealCamera, electrons for sCMOS)
4. bg: background per pixel
5. σx: Gaussian width in x (fitted in pixels, output in microns)
6. σy: Gaussian width in y (fitted in pixels, output in microns)

Example

psf = GaussianXYNBSXSY()  # Variable σx, σy (no fixed values)
fitter = GaussMLEConfig(psf_model = psf)

Note

The fitted σx and σy parameters are stored in microns in Emitter2DFitSigmaXY output.

AstigmaticXYZNB{T} <: PSFModel{5,T}

3D astigmatic PSF for z-position estimation using engineered astigmatism.

The PSF width varies with z-position according to:

σx(z) = σx₀ * sqrt(1 + ((z-γ)/d)² + Ax*((z-γ)/d)³ + Bx*((z-γ)/d)⁴)
σy(z) = σy₀ * sqrt(1 + ((z+γ)/d)² + Ay*((z+γ)/d)³ + By*((z+γ)/d)⁴)

Parameters (in order)

1. x: x-position (fitted in ROI pixels, output in microns)
2. y: y-position (fitted in ROI pixels, output in microns)
3. z: z-position (microns throughout fitting and output)
4. N: total signal (photons for IdealCamera, electrons for sCMOS)
5. bg: background per pixel

Fields (spatial calibration parameters in microns)

• σx₀, σy₀::T: In-focus PSF widths (microns)
• Ax, Ay::T: Cubic coefficients (dimensionless)
• Bx, By::T: Quartic coefficients (dimensionless)
• γ::T: Astigmatism offset (microns)
• d::T: Depth scaling parameter (microns)

Example

# Typical parameters from calibration (all spatial params in microns)
psf = AstigmaticXYZNB{Float32}(
    0.13f0, 0.13f0,  # σx₀, σy₀ (130 nm)
    0.05f0, 0.05f0,  # Ax, Ay (dimensionless)
    0.3f0, 0.3f0,    # Bx, By (dimensionless)
    0.05f0,          # γ (50 nm astigmatism offset)
    0.4f0            # d (400 nm depth scale)
)
fitter = GaussMLEConfig(psf_model = psf)

Note

Spatial calibration parameters are specified in microns for camera-independence. Internally, x, y and lateral widths use pixels; z, γ and d remain in microns. Ax, Ay, Bx and By are dimensionless.

See also

The astigmatic PSF model is described in Huang et al., Science 319, 810-813 (2008).

Emitter2DFitGaussMLE{T} <: AbstractEmitter

2D emitter for fixed-σ Gaussian PSF (GaussianXYNB) with goodness-of-fit.

Equivalent localization fields to SMLMData.Emitter2DFit, with an additional pvalue field.

Fields

Spatial (microns)

• x::T, y::T: Position in microns

Photometry

• photons::T: Total signal (photons for IdealCamera, electrons for sCMOS)
• bg::T: Background (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

Uncertainties (CRLB, microns for spatial)

• σ_x::T, σ_y::T: Position uncertainties (microns)
• σ_xy::T: Position covariance (microns²) - off-diagonal of Fisher matrix inverse
• σ_photons::T: Signal uncertainty (photons for IdealCamera, electrons for sCMOS)
• σ_bg::T: Background uncertainty (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

Goodness-of-Fit

• pvalue::T: P-value from χ² test (df = npixels - nparams)

Metadata

• frame::Int: Frame number
• dataset::Int: Dataset ID
• track_id::Int: Trajectory ID
• id::Int: Unique emitter ID

Emitter2DFitSigma{T} <: AbstractEmitter

2D emitter with fitted isotropic PSF width σ (for GaussianXYNBS).

Fields

Spatial (microns)

• x::T, y::T: Position in microns

Photometry

• photons::T: Total signal (photons for IdealCamera, electrons for sCMOS)
• bg::T: Background (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

PSF Parameter

• σ::T: Fitted PSF width (microns)

Uncertainties (CRLB)

• σ_x::T, σ_y::T: Position uncertainties (microns)
• σ_xy::T: Position covariance (microns²) - off-diagonal of Fisher matrix inverse
• σ_photons::T: Signal uncertainty (photons for IdealCamera, electrons for sCMOS)
• σ_bg::T: Background uncertainty (photons/pixel for IdealCamera, electrons/pixel for sCMOS)
• σ_σ::T: PSF width uncertainty (microns)

Goodness-of-Fit

• pvalue::T: P-value from χ² test (df = npixels - nparams)

Metadata

• frame::Int: Frame number
• dataset::Int: Dataset ID
• track_id::Int: Trajectory ID
• id::Int: Unique emitter ID

Emitter2DFitSigmaXY{T} <: AbstractEmitter

2D emitter with fitted anisotropic PSF widths σx, σy (for GaussianXYNBSXSY).

Fields

Spatial (microns)

• x::T, y::T: Position in microns

Photometry

• photons::T: Total signal (photons for IdealCamera, electrons for sCMOS)
• bg::T: Background (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

PSF Parameters

• σx::T, σy::T: Fitted PSF widths in x and y (microns)

Uncertainties (CRLB)

• σ_x::T, σ_y::T: Position uncertainties (microns)
• σ_xy::T: Position covariance (microns²) - off-diagonal of Fisher matrix inverse
• σ_photons::T: Signal uncertainty (photons for IdealCamera, electrons for sCMOS)
• σ_bg::T: Background uncertainty (photons/pixel for IdealCamera, electrons/pixel for sCMOS)
• σ_σx::T, σ_σy::T: PSF width uncertainties (microns)

Goodness-of-Fit

• pvalue::T: P-value from χ² test (df = npixels - nparams)

Metadata

• frame::Int: Frame number
• dataset::Int: Dataset ID
• track_id::Int: Trajectory ID
• id::Int: Unique emitter ID

Emitter3DFitGaussMLE{T} <: AbstractEmitter

3D emitter for astigmatic PSF (AstigmaticXYZNB) with goodness-of-fit.

Equivalent localization fields to SMLMData.Emitter3DFit, with an additional pvalue field.

Fields

Spatial (microns)

• x::T, y::T, z::T: Position in microns

Photometry

• photons::T: Total signal (photons for IdealCamera, electrons for sCMOS)
• bg::T: Background (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

Uncertainties (CRLB, microns for spatial)

• σ_x::T, σ_y::T, σ_z::T: Position uncertainties (microns)
• σ_xy::T, σ_xz::T, σ_yz::T: Position covariances (microns²) - off-diagonals of Fisher matrix inverse
• σ_photons::T: Signal uncertainty (photons for IdealCamera, electrons for sCMOS)
• σ_bg::T: Background uncertainty (photons/pixel for IdealCamera, electrons/pixel for sCMOS)

Goodness-of-Fit

• pvalue::T: P-value from χ² test (df = npixels - nparams)

Metadata

• frame::Int: Frame number
• dataset::Int: Dataset ID
• track_id::Int: Trajectory ID
• id::Int: Unique emitter ID

generate_roi_batch(camera, psf_model; kwargs...) → ROIBatch

Generate synthetic ROI data with camera-appropriate noise.

Arguments

• camera::AbstractCamera: Camera model (IdealCamera or SCMOSCamera)
• psf_model::PSFModel: PSF model determining parameter structure

Keywords

• n_rois::Int = 100: Number of ROIs to generate
• roi_size::Int = 11: Size of each ROI (square)
• true_params::Union{Nothing, Matrix} = nothing: Parameters or use PSF defaults
• corners::Union{Nothing, Matrix{Int32}} = nothing: ROI corners or auto-generate
• frame_indices::Union{Nothing, Vector{Int32}} = nothing: Frame indices or all frame 1
• xy_variation::Float32 = 1.0: Position variation (±pixels) when using defaults
• corner_mode::Symbol = :random: Corner generation mode (:random, :grid, :clustered)
• min_spacing::Int = 20: Requested pixel spacing for grid and best-effort random placement; random fallback may violate it. In clustered mode it controls offsets around cluster centers.
• seed::Union{Nothing, Int} = nothing: Random seed for reproducibility

Returns

• ROIBatch: Complete ROI batch with camera attached, ready for fitting