Multi-Target & I/O

MultiTargetResult

Result of a multi-target analysis. Holds per-channel AnalysisResult objects and the final SMLD vectors for composite rendering.

Fields

• labels::Vector{Symbol}: Channel labels in order
• smlds::Vector{SMLMData.BasicSMLD}: Per-channel final SMLDs, after the multi-target steps (aligned if an alignment step ran)
• channels::Dict{Symbol, AnalysisResult}: Per-channel results. .smld is the same final (aligned) data as smlds; .smld_connected is the channel's pre-alignment connected data and .drift_model its drift model
• step_infos::Vector{StepInfo}: Multi-target step history
• outdir::String: Output directory

Indexing

result[:IgG]         # Per-channel AnalysisResult (.smld == result.smlds[1])
keys(result)         # Channel labels
result.smlds         # Vector of all SMLDs

MultiTargetInfo <: AbstractSMLMInfo

Aggregated metadata from a multi-target analysis.

Fields

• elapsed_s::Float64: Total elapsed time in seconds
• channels::Dict{Symbol, AnalysisInfo}: Per-channel analysis info
• step_infos::Vector{StepInfo}: Multi-target step history (composite renders, alignment, etc.)

Look up a cross-channel step by name with the stepinfo / stepinfos accessors (these search step_infos, not the per-channel channels).

AbstractMultiTargetStep <: AbstractSMLMConfig

Abstract supertype for steps that operate on Vector{BasicSMLD} in the multi-target pipeline (composite rendering, cross-channel alignment, etc.).

CompositeRenderConfig <: AbstractMultiTargetStep

Configuration for a composite multi-channel render in the multi-target pipeline.

Fields

• strategy: Rendering strategy (default: GaussianRender())
• zoom: Zoom factor (default: 20.0)
• colors: Per-channel colors (nothing = inherit from MultiTargetConfig)
• clip_percentile: Intensity clipping. :auto (default) picks per strategy — saturate (no clip) for histogram, 0.99 for others. A Float64 clips at that percentile; nothing forces saturate mode.
• normalize_each: Per-channel normalization (nothing = auto: false for histogram, true for others)
• scalebar: Enable scale bar (default: true)
• scalebar_length: Scale bar length in μm (nothing = auto)
• scalebar_position: Scale bar corner (default: :br)
• scalebar_color: Scale bar color (default: :white)

CrossAlignConfig <: AbstractMultiTargetStep

Configuration for cross-channel alignment in the multi-target pipeline.

Wraps SMLMDriftCorrection.align_smld, which uses entropy-based or FFT cross-correlation alignment. Every alignment parameter lives on the upstream AlignConfig (re-exported), which is passed through unchanged — including its verbose field.

Fields

• align::AlignConfig: upstream alignment config (default: AlignConfig(), i.e. upstream's defaults)

Example

CrossAlignConfig()                                        # entropy (CC + entropy refinement)
CrossAlignConfig(align=AlignConfig(method=:fft))          # CC only

CrossCorrConfig <: AbstractMultiTargetStep

Configuration for pair cross-correlation g(r) between two channels.

Fields

• r_max: Maximum correlation distance in μm (default: 1.0)
• dr: Radial bin width in μm (default: 0.01)
• edge_correction: Apply Ripley's isotropic edge correction (default: true)
• channels: Which channels to correlate, as 1-based indices (default: (1, 2))

CompositeRenderInfo <: AbstractSMLMInfo

Info from a multi-channel composite render step.

CrossAlignInfo <: AbstractSMLMInfo

Info from cross-channel alignment step.

CrossCorrInfo <: AbstractSMLMInfo

Info from pair cross-correlation g(r) step.

Fields

• r::Vector{Float64}: Bin centers (μm)
• g::Vector{Float64}: g(r) values
• n_a::Int: Emitter count in channel A
• n_b::Int: Emitter count in channel B
• area::Float64: FOV area (μm²)
• r_max::Float64: Maximum correlation distance (μm)
• dr::Float64: Bin width (μm)
• channel_a::Symbol: Label for channel A
• channel_b::Symbol: Label for channel B
• elapsed_s::Float64: Elapsed time (s)

save_smld(filepath::String, smld::BasicSMLD;
          source_file::Union{String,Nothing}=nothing,
          drift_model=nothing,
          compression::Int=3)

Save BasicSMLD to HDF5 file with full metadata for reproducibility.

Supports all emitter types including GaussMLE types with fitted PSF widths:

• Emitter2DFitSigma: saves fitted σ (isotropic PSF width)
• Emitter2DFitSigmaXY: saves fitted σx, σy (anisotropic PSF widths)

Arguments

• filepath: Output .h5 file path
• smld: BasicSMLD object to save
• source_file: Original data file path (for provenance tracking)
• drift_model: Optional drift correction model (LegendrePolynomial, etc.)
• compression: HDF5 compression level 0-9 (default: 3)

File Structure

/metadata           - Format version, package info, timestamps
/emitters           - Columnar emitter data (x, y, z, photons, psf_sigma_x, etc.)
/camera             - Camera type and calibration
/drift_correction   - Drift model coefficients (if provided)
/provenance         - Source file info
/user_metadata      - smld.metadata values: strings, numbers, numeric/string arrays,
                      polygons (Vector{NTuple{2,Float64}}) and Vector{CellPolygon}
                      (edge-classify geometry); other types are skipped with a warning

Example

save_smld("results.h5", smld; source_file="/data/experiment.h5", drift_model=dm)

load_smld(filepath::String) -> BasicSMLD

Load BasicSMLD from HDF5 file.

Returns a BasicSMLD with the saved emitters, camera, and metadata. Automatically reconstructs the correct emitter type (including GaussMLE types with PSF width fields).

Drift correction info is stored in metadata["drift_correction"] if present.

Example

smld = load_smld("results.h5")

smld_info(filepath::String)

Print summary info about an SMLD HDF5 file without loading all data.

load_smart_h5(filepath::String; frame_range=nothing)

Load image data from a SMART microscope HDF5 file.

Arguments

• filepath::String: Path to the HDF5 file
• frame_range: Optional range of frames to load (e.g., 1:1000), or a single frame index (e.g., 5), which returns that one frame as a Matrix. If nothing, loads all frames.

Returns

• data::Array{UInt16, 3}: Image data (width, height, frames) for a range or nothing; Matrix{UInt16} (width, height) for a single frame index.

Example

# Load all frames
data = load_smart_h5("data/experiment.h5")

# Load first 1000 frames
data = load_smart_h5("data/experiment.h5", frame_range=1:1000)

# Load a single frame
frame5 = load_smart_h5("data/experiment.h5", frame_range=5)

load_smart_h5_info(filepath::String)

Load metadata about a SMART microscope HDF5 file without reading the full dataset.

Returns a NamedTuple with:

• filepath: Full path to the file
• width, height, nframes: Image dimensions
• dtype: Data type of the images
• filesizegb: Approximate file size in GB

Example

info = load_smart_h5_info("path/to/smart_data.h5")
println("File contains ", info.nframes, " frames of size ", info.width, "x", info.height)

smart_h5_to_array(filepath::String; max_frames=nothing)

Load SMART microscope data as a properly formatted array for SMLM processing.

This function transposes the data from (width, height, frames) to (height, width, frames) to match standard image conventions where the first dimension is rows (y) and second is columns (x).

Arguments

• filepath::String: Path to the HDF5 file
• max_frames: Optional maximum number of frames to load

Returns

• data::Array{UInt16, 3}: Image data in (rows, cols, frames) format
• info::NamedTuple: File metadata

Example

data, info = smart_h5_to_array("data/experiment.h5", max_frames=1000)
println("Loaded ", size(data, 3), " frames of size ", size(data, 1), "x", size(data, 2))

load_mic_h5(filepath; max_frames=nothing, max_blocks=nothing) -> images, dataset_indices

Load MIC dSTORM H5 file. Each block becomes a "dataset".

Returns:

• images: 3D array (height × width × n_frames)
• dataset_indices: Vector{Int} mapping each frame to its block (1-indexed)

load_mic_h5_info(filepath) -> NamedTuple

Get info about MIC H5 file without loading all data.

Returns NamedTuple with fields:

• height, width: image dimensions
• n_frames: total frames across all blocks
• n_blocks: number of data blocks (datasets)
• framesperblock: Vector of frame counts per block
• has_calibration: whether calibration data exists

load_mic_h5_block(filepath, block_num::Int) -> Array{Float32,3}

Load a single data block from MIC H5 file. block_num is 1-indexed.

load_mic_h5_calibration(filepath) -> NamedTuple

Load raw calibration data from a MIC H5 file, in SMITE's stored units (unconverted).

Returns NamedTuple with (offset, variance, gain) as 2D arrays:

• offset: per-pixel dark offset, ADU
• variance: per-pixel dark variance, ADU² (Calibration/CCDVar)
• gain: per-pixel gain as STORED, ADU/e⁻ (SMITE convention: RawData = gain*photons + offset)

Use load_mic_h5_calibration_for_scmos() to convert these to SCMOSCamera's units.

load_mic_h5_calibration_for_scmos(filepath) -> NamedTuple

Load calibration data and convert from SMITE's stored units to SCMOSCamera's convention.

Returns NamedTuple with:

• offset: per-pixel offset, ADU (unchanged)
• readnoise: per-pixel readnoise, e⁻ rms = sqrt(variance) / gain_stored (SMITE converts read noise variance from ADU² to e⁻² via CCDVar ./ Gain.^2; this is the rms of that)
• gain: per-pixel gain, e⁻/ADU = 1 / gain_stored (inverted from the stored ADU/e⁻ value)

build_camera_from_mic_h5(filepath; pixel_size, qe=1.0) -> SCMOSCamera

Build an SCMOSCamera from MIC H5 per-pixel calibration data: offset (ADU), readnoise (e⁻ rms), and gain (e⁻/ADU), converted from the file's stored units by load_mic_h5_calibration_for_scmos.

Pixel size and QE are not stored in MIC H5 files and must be provided.

Arguments

• filepath: Path to MIC H5 file with Calibration/ group
• pixel_size: Pixel size in μm (required)
• qe: Quantum efficiency 0-1 (default: 1.0)

step_name(cfg::AbstractSMLMConfig) -> String

Derive step name from config type (e.g., FilterConfig → "filter", DriftConfig → "drift").

step_outdir(outdir, step_number, cfg) -> Union{String, Nothing}

Compute output directory for a step: outdir/02_filter/. Returns nothing if outdir is nothing.