API Reference

GaussMLEConfig{P,PC}

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<:ParameterConstraints: Parameter bounds and step limits
• 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, GaussMLEResults, PSFModel, CameraModel

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: Optional sCMOS variance map (will override fitter's camera model)

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(), 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 (uses defaults if nothing)
• 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

# 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

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 photon count
4. bg: background per pixel

Fields

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

Example

psf = GaussianXYNB(0.13f0)  # σ = 130 nm (typical ~500nm emission, 100nm pixels)
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 photon count
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 photon count
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 (fitted in pixels, output in microns)
4. N: total photon count
5. bg: background per pixel

Fields (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

All spatial parameters in physical units (microns) for camera-independence. Internally converted to pixels based on camera pixel size during fitting.

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.

Identical to SMLMData.Emitter2DFit but adds p-value and covariance fields.

Fields

Spatial (microns)

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

Photometry

• photons::T: Total photon count
• bg::T: Background level

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, σ_bg::T: Photometry uncertainties

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 photon count
• bg::T: Background level

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, σ_bg::T: Photometry uncertainties
• σ_σ::T: PSF width uncertainty (microns)

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 photon count
• bg::T: Background level

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, σ_bg::T: Photometry uncertainties
• σ_σx::T, σ_σy::T: PSF width uncertainties (microns)

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.

Identical to SMLMData.Emitter3DFit but adds p-value and covariance fields.

Fields

Spatial (microns)

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

Photometry

• photons::T: Total photon count
• bg::T: Background level

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, σ_bg::T: Photometry uncertainties

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: Minimum pixel spacing between ROIs
• seed::Union{Nothing, Int} = nothing: Random seed for reproducibility

Returns

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