API Reference

SMLMAnalysis

High-level integration package for the JuliaSMLM ecosystem.

Provides a unified analyze() API for SMLM analysis. The config type determines the operation via multiple dispatch:

Quick Start

using SMLMAnalysis

# Full pipeline with AnalysisConfig
config = AnalysisConfig(
    camera = cam,
    steps = [
        DetectFitConfig(
            boxer=BoxerConfig(boxsize=9, psf_sigma=0.130),
            fitter=GaussMLEConfig(psf_model=GaussianXYNBS(), iterations=20)),
        FilterConfig(photons=(500.0, Inf)),
        FrameConnectConfig(max_frame_gap=5),
        DriftConfig(degree=2, dataset_mode=:registered),
        RenderConfig(zoom=20, colormap=:inferno),
    ],
    outdir = "output/",
)
(result, info) = analyze(image_stacks, config)

# Individual steps via analyze() dispatch
(smld, info) = analyze(image_stacks, DetectFitConfig(
    camera=cam, boxer=BoxerConfig(boxsize=9, psf_sigma=0.130)))
(smld, info) = analyze(smld, FilterConfig(photons=(500.0, Inf)))
(smld, info) = analyze(smld, FrameConnectConfig(max_frame_gap=5))
(smld, info) = analyze(smld, DriftConfig(degree=2))
# RenderConfig is a pass-through step: it returns (smld, StepInfo) and writes the
# image to outdir. For the image in-memory, call SMLMRender.render(smld, cfg) directly.
(smld, info) = analyze(smld, RenderConfig(zoom=20, colormap=:inferno))

Re-exported Types

Key types from ecosystem packages are re-exported for convenience:

• SMLMData: AbstractCamera, IdealCamera, SCMOSCamera, BasicSMLD, Emitter types
• GaussMLE: GaussMLEConfig, PSF models, ROIBatch
• SMLMFrameConnection: FrameConnectConfig
• SMLMDriftCorrection: DriftConfig
• SMLMRender: render strategies

analyze(data, cfg::DetectFitConfig; kwargs...) -> (smld, StepInfo)

Run combined detection and fitting. Camera must be set in cfg.camera.

File-based dispatch for pipeline use: analyze(nothing, DetectFitConfig(path=...)). Routes to file-based analyze(cfg::DetectFitConfig) when no data is provided.

analyze(cfg::DetectFitConfig; kwargs...) -> (smld, StepInfo)

File-based detection and fitting. Requires cfg.path or cfg.paths and cfg.camera.

analyze(smld, cfg::FilterConfig; kwargs...) -> (filtered_smld, StepInfo)

Filter localizations by quality criteria.

analyze(smld, cfg::SMLMFrameConnection.FrameConnectConfig; kwargs...) -> (combined_smld, StepInfo)

Run frame connection on localizations.

analyze(smld, cfg::SMLMDriftCorrection.DriftConfig; kwargs...) -> (corrected_smld, StepInfo)

Run drift correction on localizations.

analyze(smld, cfg::DensityFilterConfig; kwargs...) -> (filtered_smld, StepInfo)

Filter localizations by neighbor density.

analyze(smld, cfg::IntensityFilterConfig; kwargs...) -> (filtered_smld, StepInfo)

Filter localizations by intensity-based multi-emitter rejection.

analyze(smld, cfg::RenderConfig; kwargs...) -> (smld, StepInfo)

Render localizations to a super-resolution image. The image is saved to disk (via renderstep); the smld passes through so subsequent pipeline steps can operate on it. Use `rendersteporSMLMRender.render` directly to get the image.

analyze(smlds::Vector{BasicSMLD}, cfg::CompositeRenderConfig; kwargs...) -> (smlds, StepInfo)

Multi-target dispatch: composite render. SMLDs pass through.

analyze(smlds::Vector{BasicSMLD}, cfg::CrossAlignConfig; kwargs...) -> (aligned_smlds, StepInfo)

Multi-target dispatch: cross-channel alignment. Modifies SMLDs.

analyze(smlds::Vector{BasicSMLD}, cfg::CrossCorrConfig; kwargs...) -> (smlds, StepInfo)

Multi-target dispatch: pair cross-correlation. SMLDs pass through.

analyze(smld, cfg::BaGoLConfig; kwargs...) -> (bagol_smld, StepInfo)

Group localizations into emitters via Bayesian inference (BaGoL).

analyze(smld, cfg::AbstractClusterConfig; kwargs...) -> (smld_out, StepInfo)

Label each localization with a cluster id via SMLMClustering. The backend is selected by the concrete type of cfg (DBSCANConfig, HDBSCANConfig, VoronoiConfig, HierarchicalConfig). The input SMLD is not modified — a deep-copied, labeled SMLD is returned and threaded onward (emitter.id: 0 = noise, 1..K = cluster). See the SMLMClustering documentation for the algorithm details and per-backend configuration.

analyze(smld, cfg::AbstractStatisticsConfig; kwargs...) -> (smld, StepInfo)

Compute a read-only spatial statistic via SMLMClustering — e.g. Hopkins clustering tendency (HopkinsConfig) or Voronoi density (VoronoiDensityConfig). The SMLD is returned unchanged; the result scalar and any per-emitter/per-dataset vectors live in the step's ClusterStatisticsInfo (info.statistic, info.extras).

analyze(smld, cfg::AbstractEdgeClassifyConfig; kwargs...) -> (smld_out, StepInfo)

Classify each localization as :interior / :membrane / :outside against the cell mask(s) carved by SMLMClustering. The method is selected by the concrete type of cfg (KdeValleyConfig — the dSTORM-tuned default — or OuterPolygonConfig). The emitters are not modified and are shared into the returned SMLD; only the cell-mask geometry is mirrored into metadata (edge_cells, edge_outer_polygon) for downstream steps. The authoritative per-emitter class and the full geometry live in the step's EdgeClassifyInfo (info.class / interior_mask(info)).

analyze(data, config::AnalysisConfig) -> (AnalysisResult, AnalysisInfo)

Run SMLM analysis pipeline defined by config.

Returns a tuple of (AnalysisResult, AnalysisInfo) following the JuliaSMLM tuple-pattern.

Arguments

• data: Image data - one of:
  • Vector{AbstractArray{<:Real,3}}: Multiple datasets (primary path)
  • AbstractArray{<:Real,3}: Single dataset
• config: AnalysisConfig with camera, steps, and output settings

Example

config = AnalysisConfig(
    camera = cam,
    steps = [
        DetectFitConfig(boxer=BoxerConfig(boxsize=9)),
        FilterConfig(photons=(500.0, Inf)),
        DriftConfig(degree=2),
        RenderConfig(zoom=20, colormap=:inferno),
    ],
    outdir = "output/",
)
(result, info) = analyze(image_stacks, config)
result.smld               # Final SMLD
info.steps[:detectfit]    # DetectFit step info
info.steps[:driftcorrect] # Drift step info

analyze(data, steps::AbstractSMLMConfig...; camera, kwargs...) -> (AnalysisResult, AnalysisInfo)

Convenience varargs form. Builds AnalysisConfig from positional step configs and keyword arguments.

Example

(result, info) = analyze(image_stacks,
    DetectFitConfig(boxer=BoxerConfig(boxsize=9)),
    FilterConfig(photons=(500.0, Inf)),
    DriftConfig(degree=2);
    camera=cam, outdir="output/")

analyze(config::AnalysisConfig) -> (AnalysisResult, AnalysisInfo)

Run analysis from file paths specified in DetectFitConfig. No image data argument needed - data is loaded from files.

Example

config = AnalysisConfig(
    camera = cam,
    steps = [
        DetectFitConfig(path="data.h5"),
        FilterConfig(photons=(500.0, Inf)),
    ],
    outdir = "output/",
)
(result, info) = analyze(config)

analyze(channels::Vector{<:Tuple}, config::MultiTargetConfig) -> (MultiTargetResult, MultiTargetInfo)

Run independent analysis pipelines for each channel, then execute multi-target steps (composite rendering, cross-channel alignment, etc.) via dispatch.

Each element of channels is a (data, AnalysisConfig) tuple where data is an image stack (or Vector of stacks) or file path. The config.labels must match the number of channels.

Arguments

• channels: Vector of (data, AnalysisConfig) tuples, one per target/color
• config: MultiTargetConfig with labels, colors, steps, and output settings

Returns

(MultiTargetResult, MultiTargetInfo) tuple following the JuliaSMLM convention.

Example

mt = MultiTargetConfig(
    labels = [:IgG, :C1q],
    steps = [
        CompositeRenderConfig(zoom=20.0, strategy=GaussianRender()),
        CrossAlignConfig(method=:entropy),
        CompositeRenderConfig(zoom=20.0, strategy=GaussianRender()),
    ],
    outdir = "output/cell1/",
)

(result, info) = analyze([
    (image_stacks_647, config_647),
    (image_stacks_568, config_568),
], mt)

result.smlds              # Vector{BasicSMLD}
result[:IgG].smld         # Per-channel access
info.channels[:IgG]       # Per-channel AnalysisInfo

AnalysisConfig <: AbstractSMLMConfig

Complete description of an SMLM analysis pipeline.

The steps vector contains upstream package configs (BoxerConfig, GaussMLEConfig, etc.) and SMLMAnalysis-specific configs (FilterConfig, DensityFilterConfig). The pipeline executes steps in order.

Fields

• camera::AbstractCamera: Camera model (required, no default)
• steps::Vector{SMLMData.AbstractSMLMConfig}: Ordered pipeline steps
• roi::Union{NamedTuple, Nothing}: Optional ROI as (x=100:300, y=50:200) to crop images/camera
• outdir::Union{String, Nothing}: Output directory for results
• verbose::Int: Verbosity level (default: STANDARD)

Example

config = AnalysisConfig(
    camera = cam,
    steps = [
        DetectFitConfig(
            boxer=BoxerConfig(boxsize=9, psf_sigma=0.130),
            fitter=GaussMLEConfig(psf_model=GaussianXYNBS(), iterations=20)),
        FilterConfig(photons=(500.0, Inf)),
        DriftConfig(degree=2, dataset_mode=:registered),
        RenderConfig(zoom=20, colormap=:inferno),
    ],
    outdir = "output/",
)
(result, info) = analyze(image_stacks, config)

AnalysisResult

Immutable result from analyze(). Replaces the old mutable Analysis struct.

Fields

• smld::BasicSMLD: Final SMLD after all steps
• smld_connected::Union{BasicSMLD, Nothing}: Connected SMLD (if frameconnect was run)
• drift_model::Any: Drift model (if driftcorrect was run)

Access

(result, info) = analyze(image_stacks, config)
result.smld               # Final SMLD
result.drift_model        # Drift model for plotting
result.smld_connected     # Connected SMLD for track analysis
info.steps[:driftcorrect] # Step info from upstream packages

AnalysisInfo <: AbstractSMLMInfo

Aggregated metadata from all analysis steps, following the tuple-pattern.

Fields

• elapsed_s::Float64: Total elapsed time in seconds
• steps::Dict{Symbol, Any}: Step name → upstream info struct mapping
• step_infos::Vector{StepInfo}: Full step history with timing and config

StepInfo <: AbstractSMLMInfo

Record of a completed pipeline step, stored in AnalysisInfo.

Fields

• number::Int: Step number in the pipeline
• name::String: Step name (derived from config type, e.g. "filter")
• config::AbstractSMLMConfig: The config used for this step
• timestamp::DateTime: When the step completed
• elapsed_s::Float64: Elapsed time in seconds
• summary::Dict{Symbol, Any}: Summary statistics (counts, acceptance rates, etc.)
• info::Union{AbstractSMLMInfo, Nothing}: Typed upstream info struct (DriftInfo, FrameConnectInfo, etc.)

DataSource

Lazy loading wrapper for SMLM image data. Supports:

• Single 3D array (one dataset)
• Vector of 3D arrays (multiple datasets, boundaries encoded in data structure)
• File path for deferred loading

Constructors

DataSource(images)                          # From single 3D array (1 dataset)
DataSource(image_stacks)                    # From Vector{Array} (N datasets)
DataSource(path; frame_range=nothing)       # From file path (lazy)

Checkpoint

Checkpoint level controls per-step SMLD persistence to disk for downstream iteration without re-running upstream pipeline steps. Mirrors the Verbosity pattern: a single integer level passed via checkpoint= kwarg or AnalysisConfig.checkpoint. Each step's analyze() dispatch decides what the level means for itself by inlining if checkpoint >= Checkpoint.X checks (symmetric with how verbose >= Verbosity.STANDARD works).

Levels

• NONE = 0: no SMLD checkpoints written
• END = 1: orchestrator writes only the final SMLD-producing step's output
• EXPENSIVE = 2 (default): expensive steps (DetectFit, FrameConnect, Drift, BaGoL) write their output SMLD; cheap filters do not
• ALL = 3: every SMLD-producing step writes its output

Default

The default is EXPENSIVE. This guarantees that no expensive step ever runs producing only image/diagnostic outputs — the SMLD is always on disk for downstream iteration.