Skip to content

api_overview.md

Latest commit

 

History

History
134 lines (109 loc) · 5.25 KB

api_overview.md

File metadata and controls

134 lines (109 loc) · 5.25 KB

SMLMFrameConnection API Overview

Frame-connection for 2D SMLM data: linking localizations from the same fluorophore blinking event across consecutive frames into single, higher-precision localizations. Uses spatiotemporal LAP assignment to optimally connect temporally adjacent detections based on spatial proximity and estimated blinking kinetics.

Main Functions

frameconnect

# Kwargs form (most common)
(combined, info) = frameconnect(smld::BasicSMLD; kwargs...)

# Config form (reusable settings)
(combined, info) = frameconnect(smld::BasicSMLD, config::FrameConnectConfig)

Main entry point. Connects repeated localizations and combines them.

Returns tuple (combined, info):

  • combined::BasicSMLD: Main output - combined high-precision localizations
  • info::FrameConnectInfo: Track assignments and algorithm metadata

combinelocalizations

combinelocalizations(smld::BasicSMLD) -> BasicSMLD

Combines emitters sharing the same track_id using MLE weighted mean. Use when track_id is already populated.

defineidealFC

(smld_connected, smld_combined) = defineidealFC(smld::BasicSMLD; max_frame_gap::Int=5)

For simulated data where track_id indicates ground-truth emitter ID. Useful for validation/benchmarking.

Types

FrameConnectConfig

@kwdef struct FrameConnectConfig <: AbstractSMLMConfig
    n_density_neighbors::Int = 2   # Nearest preclusters for local density estimation
    max_sigma_dist::Float64 = 5.0    # Sigma multiplier for preclustering distance threshold
    max_frame_gap::Int = 5        # Maximum frame gap for temporal adjacency
    max_neighbors::Int = 2             # Maximum nearest-neighbors for precluster membership
end

Configuration parameters for frame connection. Use with frameconnect(smld, config) or pass fields as kwargs to frameconnect(smld; kwargs...).

Example:

# Create config with custom settings
config = FrameConnectConfig(max_frame_gap=10, max_sigma_dist=3.0)
(combined, info) = frameconnect(smld, config)

# Equivalent kwargs form
(combined, info) = frameconnect(smld; max_frame_gap=10, max_sigma_dist=3.0)

FrameConnectInfo{T}

struct FrameConnectInfo{T} <: AbstractSMLMInfo
    connected::BasicSMLD{T}       # Input with track_id assigned (uncombined)
    n_input::Int                  # Number of input localizations
    n_tracks::Int                 # Number of tracks formed
    n_combined::Int               # Number of output localizations
    k_on::Float64                 # Rate: dark → visible (1/frame)
    k_off::Float64                # Rate: visible → dark (1/frame)
    k_bleach::Float64             # Rate: photobleaching (1/frame)
    p_miss::Float64               # Probability of missed detection
    initial_density::Vector{Float64}  # Emitter density per cluster (emitters/μm²)
    elapsed_s::Float64            # Wall time in seconds
    algorithm::Symbol             # Algorithm used (:lap)
    n_preclusters::Int            # Number of preclusters formed
end

Access track assignments:

(combined, info) = frameconnect(smld)
track_ids = [e.track_id for e in info.connected.emitters]

ParamStruct

mutable struct ParamStruct
    initial_density::Vector{Float64}  # Emitter density per cluster (emitters/μm²)
    n_density_neighbors::Int            # Clusters for density estimation
    k_on::Float64                    # Rate: dark → visible (1/frame)
    k_off::Float64                   # Rate: visible → dark (1/frame)
    k_bleach::Float64                # Rate: photobleaching (1/frame)
    p_miss::Float64                  # Probability of missing localization when on
    max_sigma_dist::Float64               # Preclustering threshold multiplier
    max_frame_gap::Int                 # Max frame gap in preclusters
    max_neighbors::Int                      # Max nearest-neighbors for preclustering
end

Photophysics terms:

  • k_on: Transition rate from dark (non-fluorescent) to visible state
  • k_off: Transition rate from visible to dark state
  • k_bleach: Irreversible photobleaching rate
  • p_miss: Probability localization algorithm fails to detect an "on" fluorophore

Input Requirements

Input BasicSMLD must contain emitters with position uncertainties.

Required fields:

  • x, y: Position (microns)
  • σ_x, σ_y: Position uncertainties (microns) - must be > 0 for MLE
  • frame: Frame number (1-based)

Optional fields:

  • photons, σ_photons: Photon count (summed in output)
  • bg, σ_bg: Background
  • dataset: Dataset identifier (default: 1)
  • track_id: Set to 0 for input (populated by algorithm)

Output

Output combined contains emitters with:

  • Combined position via MLE weighted mean: x = Σ(x/σ²) / Σ(1/σ²)
  • Reduced uncertainties: σ = √(1/Σ(1/σ²))
  • Summed photons
  • track_id indicating connection group

Dependencies

  • SMLMData.jl (v0.7): BasicSMLD, Emitter types, AbstractSMLMConfig, AbstractSMLMInfo
  • Hungarian.jl: Linear assignment problem solver
  • NearestNeighbors.jl: Spatial clustering
  • Optim.jl: Parameter estimation

Algorithm Reference

Schodt & Lidke (2021), "Spatiotemporal Clustering of Repeated Super-Resolution Localizations via Linear Assignment Problem", Front. Bioinform. https://doi.org/10.3389/fbinf.2021.724325