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 SMLD results (may be aligned)
• channels::Dict{Symbol, AnalysisResult}: Per-channel results
• step_infos::Vector{StepInfo}: Multi-target step history
• outdir::String: Output directory

Indexing

result[:IgG]         # Access per-channel AnalysisResult
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.)
• steps::Dict{Symbol, Any}: Step name → info mapping for convenience

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.

Fields

• method: Alignment method — :entropy (CC + entropy refinement) or :fft (CC only)
• maxn: Maximum neighbors for entropy calculation (default: 100)
• histbinsize: Histogram bin size in μm for cross-correlation (default: 0.05)

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

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.

save_pipeline_state(path::String, result::AnalysisResult;
                    smld_raw=nothing, step_infos=StepInfo[], camera=nothing)

Save pipeline state to JLD2 for cross-session resume.

Example

(result, info) = analyze(image_stacks, config)
save_pipeline_state("output/checkpoint.jld2", result;
    step_infos=info.step_infos, camera=config.camera)

load_pipeline_state(path::String) -> NamedTuple

Load pipeline state from JLD2.

Returns a NamedTuple with fields: smld, smldraw, smldconnected, driftmodel, stepinfos, camera.

Example

state = load_pipeline_state("output/checkpoint.jld2")
smld = state.smld
# Continue pipeline from here
(smld, info) = analyze(smld, FilterConfig(photons=(500.0, Inf)))

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). If nothing, loads all frames.

Returns

• data::Array{UInt16, 3}: Image data (width, height, frames)

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_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)

load_smart_h5_frame(filepath::String, frame::Int)

Load a single frame from a SMART microscope HDF5 file.

Arguments

• filepath::String: Path to the HDF5 file
• frame::Int: Frame number to load (1-indexed)

Returns

• frame_data::Matrix{UInt16}: Single frame image

Example

frame1 = load_smart_h5_frame("data/experiment.h5", 1)

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 calibration data from MIC H5 file.

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

NOTE: The gain in MIC H5 files is INVERTED compared to our convention. Our convention: ADU = photons * gain, so gain ≈ 0.24 e-/ADU MIC H5: gain stored as ~4, which is 1/gain in our convention Use loadmich5calibrationfor_scmos() to get corrected values.

load_mic_h5_calibration_for_scmos(filepath) -> NamedTuple

Load calibration data and convert to SCMOSCamera convention.

Returns NamedTuple with:

• offset: per-pixel offset (unchanged)
• readnoise: per-pixel readnoise (sqrt of variance)
• gain: per-pixel gain (INVERTED from stored value)

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

Build an SCMOSCamera from MIC H5 per-pixel calibration data (offset, readnoise, gain).

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)

crop_camera(camera::AbstractCamera, roi_x::UnitRange, roi_y::UnitRange)

Crop camera to specified pixel ROI while preserving physical coordinates.

Returns a new camera with:

• pixeledgesx/y sliced to cover ROI (preserves original μm positions)
• For SCMOSCamera: offset/gain/readnoise/qe matrices cropped accordingly

Arguments

• camera: Original camera
• roi_x: Pixel range in x (columns), e.g., 100:300
• roi_y: Pixel range in y (rows), e.g., 50:200

Example

cam = IdealCamera(512, 512, 0.1)
cam_cropped = crop_camera(cam, 100:300, 50:200)
# cam_cropped.pixel_edges_x[1] = 10.0 μm (not 0!)

crop_images(images::AbstractArray{T,3}, roi_x::UnitRange, roi_y::UnitRange) where T

Crop image stack to specified pixel ROI.

Arguments

• images: 3D array (y, x, frames) - Julia convention: [row, col]
• roi_x: Pixel range in x (columns)
• roi_y: Pixel range in y (rows)

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.

n_datasets(ds::DataSource) -> Int

Number of datasets in this data source.

n_frames_per_dataset(ds::DataSource) -> Int

Frames per dataset. For Vector{Array}, uses first element.