GitHub

Library

SMLMData.SMLMData — Module
SMLMData

A Julia package for working with Single Molecule Localization Microscopy (SMLM) data.

Features

  • Type system for emitters, cameras, and localization data
  • Physical coordinate handling (microns) with camera pixel mappings
  • Filtering and ROI selection tools
  • SMITE format compatibility
  • Memory-efficient data structures

Basic Usage

using SMLMData

# Create a camera
cam = IdealCamera(1:512, 1:512, 0.1)  # 512x512 camera with 0.1 micron pixels

# Create some emitters
emitters = [
    Emitter2DFit{Float64}(1.0, 2.0, 1000.0, 10.0, 0.01, 0.01, 50.0, 2.0),
    Emitter2DFit{Float64}(3.0, 4.0, 1200.0, 12.0, 0.01, 0.01, 60.0, 2.0)
]

# Create SMLD object
smld = BasicSMLD(emitters, cam, 1, 1, Dict{String,Any}())

# Filter operations
roi = filter_roi(smld, 0.0:2.0, 1.0:3.0)
bright = @filter(smld, photons > 1000)
source
SMLMData.AbstractCamera — Type
AbstractCamera

Abstract base type for all camera implementations in single molecule localization microscopy (SMLM).

Interface Requirements

Any concrete subtype of AbstractCamera must provide:

  1. Field Requirements:

    • pixel_edges_x::Vector{<:Real}: Vector of pixel edge positions in x direction
    • pixel_edges_y::Vector{<:Real}: Vector of pixel edge positions in y direction

  2. Units:

    • All edge positions must be in physical units (microns)
    • Origin (0,0) corresponds to the top-left corner of the camera
    • For a camera with N×M pixels, there will be N+1 x-edges and M+1 y-edges

  3. Coordinate Convention:

    • Pixel (1,1) is centered at (pixelsizex/2, pixelsizey/2) microns
    • Edge positions define the boundaries of pixels in physical space
    • First edge position corresponds to the left/top edge of the first pixel
    • Last edge position corresponds to the right/bottom edge of the last pixel

Notes

  • Edge positions must be monotonically increasing
  • The number of edges must be one more than the number of pixels in each dimension
  • While pixels are typically uniform in size, this is not a requirement of the interface
source
SMLMData.AbstractEmitter — Type
AbstractEmitter

Abstract supertype for all emitter types in single molecule localization microscopy (SMLM). All spatial coordinates are specified in physical units (microns).

source
SMLMData.BasicSMLD — Type
BasicSMLD{T,E<:AbstractEmitter} <: SMLD

Basic container for single molecule localization data.

Fields

  • emitters::Vector{E}: Vector of localized emitters
  • camera::AbstractCamera: Camera used for acquisition
  • n_frames::Int: Total number of frames in acquisition
  • n_datasets::Int: Number of datasets in the acquisition
  • metadata::Dict{String,Any}: Additional dataset information

Type Parameters

  • T: Numeric type for coordinates (typically Float64)
  • E: Concrete emitter type

Example

# Create camera
cam = IdealCamera(1:512, 1:512, 0.1)

# Create some emitters
emitters = [
    Emitter2DFit{Float64}(1.0, 1.0, 1000.0, 10.0, 0.01, 0.01, 50.0, 2.0; frame=1),
    Emitter2DFit{Float64}(5.0, 5.0, 1200.0, 12.0, 0.01, 0.01, 60.0, 2.0; frame=2)
]

# Create metadata
metadata = Dict{String,Any}(
    "exposure_time" => 0.1,
    "timestamp" => now(),
    "sample" => "Test Sample"
)

# Create SMLD object
data = BasicSMLD(emitters, cam, 2, 1, metadata)
source
SMLMData.BasicSMLD — Method
BasicSMLD(emitters::Vector{E}, camera::AbstractCamera,
          n_frames::Int, n_datasets::Int,
          metadata::Dict{String,Any}=Dict{String,Any}()) where E<:AbstractEmitter

Construct a BasicSMLD from a vector of emitters and required metadata.

Arguments

  • emitters::Vector{E}: Vector of localized emitters
  • camera::AbstractCamera: Camera used for acquisition
  • n_frames::Int: Total number of frames in acquisition
  • n_datasets::Int: Number of datasets in acquisition
  • metadata::Dict{String,Any}=Dict{String,Any}(): Optional additional information

The numeric type T is inferred from the camera's pixeledgesx type.

Example

# Create with minimal metadata
data = BasicSMLD(emitters, camera, 10, 1)

# Create with additional metadata
data = BasicSMLD(emitters, camera, 10, 1, Dict(
    "exposure_time" => 0.1,
    "timestamp" => now()
))
source
SMLMData.Emitter2D — Type
Emitter2D{T} <: AbstractEmitter

Represents a 2D emitter for SMLM simulations with position and brightness.

Fields

  • x::T: x-coordinate in microns
  • y::T: y-coordinate in microns
  • photons::T: number of photons emitted by the fluorophore
source
SMLMData.Emitter2DFit — Type
Emitter2DFit{T} <: AbstractEmitter

Represents fitted 2D localization results with uncertainties and temporal/tracking information.

Fields

  • x::T: fitted x-coordinate in microns
  • y::T: fitted y-coordinate in microns
  • photons::T: fitted number of photons
  • bg::T: fitted background in photons/pixel
  • σ_x::T: uncertainty in x position in microns
  • σ_y::T: uncertainty in y position in microns
  • σ_photons::T: uncertainty in photon count
  • σ_bg::T: uncertainty in background in photons/pixel
  • frame::Int: frame number in acquisition sequence
  • dataset::Int: identifier for specific acquisition/dataset
  • track_id::Int: identifier for linking localizations across frames (0 = unlinked)
  • id::Int: unique identifier within dataset
source
SMLMData.Emitter2DFit — Method
Emitter2DFit{T}(x, y, photons, bg, σ_x, σ_y, σ_photons, σ_bg;
                frame=0, dataset=1, track_id=0, id=0) where T

Convenience constructor for 2D localization fit results with optional identification parameters.

Arguments

Required

  • x::T: fitted x-coordinate in microns
  • y::T: fitted y-coordinate in microns
  • photons::T: fitted number of photons
  • bg::T: fitted background in photons/pixel
  • σ_x::T: uncertainty in x position in microns
  • σ_y::T: uncertainty in y position in microns
  • σ_photons::T: uncertainty in photon count
  • σ_bg::T: uncertainty in background level

Optional Keywords

  • frame::Int=0: frame number in acquisition sequence
  • dataset::Int=1: identifier for specific acquisition/dataset
  • track_id::Int=0: identifier for linking localizations across frames
  • id::Int=0: unique identifier within dataset

Example

# Create emitter with just required parameters
emitter = Emitter2DFit{Float64}(
    1.0, 2.0,        # x, y
    1000.0, 10.0,    # photons, background
    0.01, 0.01,      # σ_x, σ_y
    50.0, 2.0        # σ_photons, σ_bg
)

# Create emitter with specific frame and dataset
emitter = Emitter2DFit{Float64}(
    1.0, 2.0, 1000.0, 10.0, 0.01, 0.01, 50.0, 2.0;
    frame=5, dataset=2
)
source
SMLMData.Emitter3D — Type
Emitter3D{T} <: AbstractEmitter

Represents a 3D emitter for SMLM simulations with position and brightness.

Fields

  • x::T: x-coordinate in microns
  • y::T: y-coordinate in microns
  • z::T: z-coordinate in microns (axial position)
  • photons::T: number of photons emitted by the fluorophore
source
SMLMData.Emitter3DFit — Type
Emitter3DFit{T} <: AbstractEmitter

Represents fitted 3D localization results with uncertainties and temporal/tracking information.

Fields

  • x::T: fitted x-coordinate in microns
  • y::T: fitted y-coordinate in microns
  • z::T: fitted z-coordinate in microns
  • photons::T: fitted number of photons
  • bg::T: fitted background in photons/pixel
  • σ_x::T: uncertainty in x position in microns
  • σ_y::T: uncertainty in y position in microns
  • σ_z::T: uncertainty in z position in microns
  • σ_photons::T: uncertainty in photon count
  • σ_bg::T: uncertainty in background in photons/pixel
  • frame::Int: frame number in acquisition sequence
  • dataset::Int: identifier for specific acquisition/dataset
  • track_id::Int: identifier for linking localizations across frames (0 = unlinked)
  • id::Int: unique identifier within dataset
source
SMLMData.Emitter3DFit — Method
Emitter3DFit{T}(x, y, z, photons, bg, σ_x, σ_y, σ_z, σ_photons, σ_bg;
                frame=0, dataset=1, track_id=0, id=0) where T

Convenience constructor for 3D localization fit results with optional identification parameters.

Arguments

Required

  • x::T: fitted x-coordinate in microns
  • y::T: fitted y-coordinate in microns
  • z::T: fitted z-coordinate in microns
  • photons::T: fitted number of photons
  • bg::T: fitted background in photons/pixel
  • σ_x::T: uncertainty in x position in microns
  • σ_y::T: uncertainty in y position in microns
  • σ_z::T: uncertainty in z position in microns
  • σ_photons::T: uncertainty in photon count
  • σ_bg::T: uncertainty in background level

Optional Keywords

  • frame::Int=0: frame number in acquisition sequence
  • dataset::Int=1: identifier for specific acquisition/dataset
  • track_id::Int=0: identifier for linking localizations across frames
  • id::Int=0: unique identifier within dataset

Example

# Create emitter with just required parameters
emitter = Emitter3DFit{Float64}(
    1.0, 2.0, -0.5,  # x, y, z
    1000.0, 10.0,    # photons, background
    0.01, 0.01, 0.02,# σ_x, σ_y, σ_z
    50.0, 2.0        # σ_photons, σ_bg
)

# Create emitter with specific frame and tracking
emitter = Emitter3DFit{Float64}(
    1.0, 2.0, -0.5, 1000.0, 10.0, 0.01, 0.01, 0.02, 50.0, 2.0;
    frame=5, track_id=1
)
source
SMLMData.IdealCamera — Type
IdealCamera{T} <: AbstractCamera

Represents an ideal camera with regularly spaced pixels defined by their edges in physical units (microns).

Fields

  • pixel_edges_x::Vector{T}: Physical positions of pixel edges in x direction (microns)
  • pixel_edges_y::Vector{T}: Physical positions of pixel edges in y direction (microns)

The edges are computed from pixel centers, where pixel (1,1) is centered at (pixelsizex/2, pixelsizey/2) in physical coordinates.

source
SMLMData.IdealCamera — Method
IdealCamera(pixel_centers_x::AbstractUnitRange, pixel_centers_y::AbstractUnitRange, 
            pixel_size::Tuple{T, T}) where T<:Real

Construct an IdealCamera with rectangular pixels given pixel center positions and x,y pixel sizes.

Arguments

  • pixel_centers_x::AbstractUnitRange: Range of pixel center indices in x (typically 1:N)
  • pixel_centers_y::AbstractUnitRange: Range of pixel center indices in y (typically 1:M)
  • pixel_size::Tuple{T, T}: Tuple of (xsize, ysize) in microns

Returns

IdealCamera{T} where T matches the type of the pixel sizes

Type Parameters

  • T: Numeric type for all spatial measurements (e.g., Float64, Float32)

Example

# Create a 512x256 camera with rectangular pixels (0.1 x 0.15 microns)
cam = IdealCamera(1:512, 1:256, (0.1, 0.15))

# Create with Float32 precision
cam32 = IdealCamera(1:512, 1:256, (0.1f0, 0.15f0))

Note: Pixel (1,1) is centered at (pixelsize[1]/2, pixelsize[2]/2) in physical coordinates.

source
SMLMData.IdealCamera — Method
IdealCamera(pixel_centers_x::AbstractUnitRange, pixel_centers_y::AbstractUnitRange, pixel_size::T) where T<:Real

Construct an IdealCamera with square pixels given pixel center positions and a scalar pixel size.

Arguments

  • pixel_centers_x::AbstractUnitRange: Range of pixel center indices in x (typically 1:N)
  • pixel_centers_y::AbstractUnitRange: Range of pixel center indices in y (typically 1:M)
  • pixel_size::Real: Size of pixels in microns

Returns

IdealCamera{T} where T matches the type of pixel_size

Type Parameters

  • T: Numeric type for all spatial measurements (e.g., Float64, Float32)

Example

# Create a 512x512 camera with 0.1 micron square pixels
cam = IdealCamera(1:512, 1:512, 0.1)

# Create with Float32 precision
cam32 = IdealCamera(1:512, 1:512, 0.1f0)

Note: Pixel (1,1) is centered at (pixelsize/2, pixelsize/2) in physical coordinates.

source
SMLMData.IdealCamera — Method
IdealCamera(n_pixels_x::Integer, n_pixels_y::Integer, pixel_size::Tuple{T, T}) where T<:Real

Construct an IdealCamera with rectangular pixels directly from the number of pixels and x,y pixel sizes.

Arguments

  • n_pixels_x::Integer: Number of pixels in x dimension
  • n_pixels_y::Integer: Number of pixels in y dimension
  • pixel_size::Tuple{T, T}: Tuple of (xsize, ysize) in microns

Returns

IdealCamera{T} where T matches the type of the pixel sizes

Example

# Create a 512x256 camera with rectangular pixels (0.1 x 0.15 microns)
cam = IdealCamera(512, 256, (0.1, 0.15))

# Create with Float32 precision
cam32 = IdealCamera(512, 256, (0.1f0, 0.15f0))
source
SMLMData.IdealCamera — Method
IdealCamera(n_pixels_x::Integer, n_pixels_y::Integer, pixel_size::T) where T<:Real

Construct an IdealCamera with square pixels directly from the number of pixels and pixel size.

Arguments

  • n_pixels_x::Integer: Number of pixels in x dimension
  • n_pixels_y::Integer: Number of pixels in y dimension
  • pixel_size::Real: Size of pixels in microns

Returns

IdealCamera{T} where T matches the type of pixel_size

Example

# Create a 512x512 camera with 0.1 micron square pixels
cam = IdealCamera(512, 512, 0.1)

# Create with Float32 precision
cam32 = IdealCamera(512, 512, 0.1f0)
source
SMLMData.SMLD — Type
SMLD

Abstract type representing Single Molecule Localization Data (SMLD).

Interface Requirements

Any concrete subtype of SMLD must provide:

  • emitters::Vector{<:AbstractEmitter}: Vector of localized emitters

Additional fields may include:

  • Camera information
  • Acquisition parameters
  • Analysis metadata

Note: All emitter coordinates must be in physical units (microns).

source
SMLMData.SmiteSMD — Type
SmiteSMD

Helper structure for loading Smite SMD .mat files.

Fields

  • filepath::String: Path to the directory containing the .mat file
  • filename::String: Name of the .mat file
  • varname::String: Variable name in the .mat file (default: "SMD")

Example

# Load from default "SMD" variable
smd = SmiteSMD("path/to/data", "localizations.mat")

# Load from custom variable name
smd = SmiteSMD("path/to/data", "localizations.mat", "CustomSMD")
source
SMLMData.SmiteSMLD — Type
SmiteSMLD{T,E<:AbstractEmitter} <: SMLD

SMLD type compatible with the Smite SMD (Single Molecule Data) format.

Fields

  • emitters::Vector{E}: Vector of localized emitters
  • camera::AbstractCamera: Camera used for acquisition
  • n_frames::Int: Total number of frames in acquisition
  • n_datasets::Int: Number of datasets in the acquisition
  • metadata::Dict{String,Any}: Additional dataset information

Type Parameters

  • T: Numeric type for coordinates (typically Float64)
  • E: Concrete emitter type (typically Emitter2DFit or Emitter3DFit)
source
Base.iterate — Method
Base.iterate(smld::SMLD)
Base.iterate(smld::SMLD, state)

Enable iteration over emitters in an SMLD object.

source
Base.length — Method
Base.length(smld::SMLD)

Return the number of emitters in the SMLD object.

source
SMLMData.cat_smld — Method
cat_smld(smlds::Vector{<:SMLD})
cat_smld(smlds::SMLD...)

Concatenate multiple SMLD objects into a single SMLD.

Arguments

  • smlds: Vector of SMLD objects or multiple SMLD arguments

Returns

New SMLD containing all emitters from inputs

Notes

  • Camera must be identical across all SMLDs
  • n_frames is set to maximum frame number across all inputs
  • n_datasets is set to maximum dataset number across all inputs
  • Metadata from first SMLD is used, with conflicts noted in metadata

Examples

# Concatenate two SMLDs
combined = cat_smld(smld1, smld2)

# Concatenate multiple SMLDs
combined = cat_smld(smld1, smld2, smld3)

# Concatenate vector of SMLDs
combined = cat_smld([smld1, smld2, smld3])
source
SMLMData.compute_bin_edges — Method
compute_bin_edges(centers_x::AbstractUnitRange, centers_y::AbstractUnitRange, pixel_size::Tuple{Real, Real})

Compute pixel edges in both dimensions for rectangular pixels.

Arguments

  • centers_x::AbstractUnitRange: Range of pixel center indices in x
  • centers_y::AbstractUnitRange: Range of pixel center indices in y
  • pixel_size::Tuple{Real, Real}: Tuple of (xsize, ysize) in microns

Returns

Tuple{Vector{Float64}, Vector{Float64}}: (edgesx, edgesy) in physical units (microns)

source
SMLMData.compute_bin_edges — Method
compute_bin_edges(centers_x::AbstractUnitRange, centers_y::AbstractUnitRange, pixel_size::T) where T

Compute pixel edges in both dimensions. Returns vectors with same type as pixel_size.

source
SMLMData.compute_edges_1d — Method
compute_edges_1d(centers::AbstractUnitRange, pixel_size::T) where T<:Real

Compute pixel edges in one dimension. Maintains the numeric type of pixelsize. The first edge starts at 0 and each pixel has width pixelsize.

Arguments

  • centers::AbstractUnitRange: Range of pixel center indices
  • pixel_size::T: Size of pixels in microns

Returns

Vector{T}: Edge positions in physical units (microns), starting at 0

source
SMLMData.filter_frames — Method
filter_frames(smld::SMLD, frame::Integer)
filter_frames(smld::SMLD, frames::Union{AbstractVector,AbstractRange})

Efficiently select emitters from specified frames.

Arguments

  • smld::SMLD: Input SMLD structure
  • frames: Single frame number, vector of frame numbers, or range of frames

Returns

New SMLD containing only emitters from specified frames

Examples

# Single frame
frame_5 = filter_frames(smld, 5)

# Range of frames
early = filter_frames(smld, 1:10)

# Multiple specific frames
selected = filter_frames(smld, [1,3,5,7])
source
SMLMData.filter_roi — Method
filter_roi(smld::SMLD, x_range, y_range)
filter_roi(smld::SMLD, x_range, y_range, z_range)

Efficiently select emitters within a region of interest.

Arguments

  • smld::SMLD: Input SMLD structure
  • x_range: Range or tuple for x coordinates (microns)
  • y_range: Range or tuple for y coordinates (microns)
  • z_range: Optional range or tuple for z coordinates (microns)

Returns

New SMLD containing only emitters within the specified ROI

Examples

# 2D ROI
region = filter_roi(smld, 1.0:5.0, 2.0:6.0)
region = filter_roi(smld, (1.0, 5.0), (2.0, 6.0))

# 3D ROI
volume = filter_roi(smld, 1.0:5.0, 2.0:6.0, -1.0:1.0)
source
SMLMData.get_pixel_centers — Method
get_pixel_centers(cam::AbstractCamera)

Calculate the physical coordinates of all pixel centers for any camera type.

For each dimension, the center positions are computed as the midpoint between consecutive edge positions. This works for both regular (uniform pixel size) and irregular (varying pixel size) cameras.

Arguments

  • cam::AbstractCamera: Any camera type that implements the AbstractCamera interface with pixeledgesx and pixeledgesy fields in physical units (microns)

Returns

Tuple{Vector, Vector}: (centersx, centersy) where each vector contains the physical coordinates (in microns) of pixel centers along that dimension

Example

# For a 512x512 camera with 0.1 micron pixels
cam = IdealCamera(1:512, 1:512, 0.1)
centers_x, centers_y = get_pixel_centers(cam)

# First pixel center should be at (0.05, 0.05) microns
@assert centers_x[1] ≈ 0.05
@assert centers_y[1] ≈ 0.05
source
SMLMData.load_smite_2d — Method
load_smite_2d(smd::SmiteSMD)

Load a 2D Smite SMD .mat file and convert it to SmiteSMLD format.

Arguments

  • smd::SmiteSMD: SmiteSMD object specifying the file to load

Returns

SmiteSMLD containing 2D localizations

Notes

  • All spatial coordinates are converted to microns
  • If PixelSize is not specified in the file, defaults to 0.1 microns
source
SMLMData.load_smite_3d — Method
load_smite_3d(smd::SmiteSMD)

Load a 3D Smite SMD .mat file and convert it to SmiteSMLD format.

Arguments

  • smd::SmiteSMD: SmiteSMD object specifying the file to load

Returns

SmiteSMLD containing 3D localizations

Notes

  • All spatial coordinates are converted to microns
  • If PixelSize is not specified in the file, defaults to 0.1 microns
source
SMLMData.merge_smld — Method
merge_smld(smlds::Vector{<:SMLD}; adjust_frames=false, adjust_datasets=false)
merge_smld(smlds::SMLD...; adjust_frames=false, adjust_datasets=false)

Merge multiple SMLD objects with options to adjust frame and dataset numbering.

Arguments

  • smlds: Vector of SMLD objects or multiple SMLD arguments
  • adjust_frames: If true, adjusts frame numbers to be sequential
  • adjust_datasets: If true, adjusts dataset numbers to be sequential

Returns

New SMLD containing all emitters with adjusted numbering if requested

Notes

  • Camera must be identical across all SMLDs
  • When adjust_frames=true, frame numbers are made sequential across all inputs
  • When adjust_datasets=true, dataset numbers are made sequential
  • Metadata includes information about the merge operation

Examples

# Simple merge
merged = merge_smld(smld1, smld2)

# Merge with frame number adjustment
merged = merge_smld(smld1, smld2, adjust_frames=true)

# Merge multiple with both adjustments
merged = merge_smld([smld1, smld2, smld3], 
                   adjust_frames=true, 
                   adjust_datasets=true)
source
SMLMData.physical_to_pixel — Method
physical_to_pixel(x::Real, y::Real, pixel_size::Real)

Convert physical coordinates (in microns) to pixel coordinates.

Arguments

  • x::Real: x coordinate in microns (0,0 is top-left of image)
  • y::Real: y coordinate in microns (0,0 is top-left of image)
  • pixel_size::Real: size of a pixel in microns

Returns

Tuple{Float64, Float64}: (px,py) pixel coordinates where (1,1) is center of top-left pixel

Example

# For a camera with 0.1 micron pixels
px, py = physical_to_pixel(0.05, 0.05, 0.1)  # Point 0.05,0.05 microns from origin
# Returns (1.0, 1.0) - center of first pixel
source
SMLMData.physical_to_pixel_index — Method
physical_to_pixel_index(x::Real, y::Real, pixel_size::Real)

Convert physical coordinates (in microns) to integer pixel indices. Returns the pixel that contains the given physical coordinate.

Arguments

  • x::Real: x coordinate in microns (0,0 is top-left of image)
  • y::Real: y coordinate in microns (0,0 is top-left of image)
  • pixel_size::Real: size of a pixel in microns

Returns

Tuple{Int, Int}: (px,py) pixel indices where (1,1) is top-left pixel

Example

# For a camera with 0.1 micron pixels
px, py = physical_to_pixel_index(0.05, 0.05, 0.1)  # Point at center of first pixel
# Returns (1, 1)
source
SMLMData.pixel_to_physical — Method
pixel_to_physical(px::Real, py::Real, pixel_size::T) where T

Convert pixel coordinates to physical coordinates (in microns). Returns coordinates with the same type as pixel_size.

source
SMLMData.save_smite — Method
save_smite(smld::SmiteSMLD, filepath::String, filename::String)

Save SmiteSMLD data back to SMITE's SMD .mat format.

Arguments

  • smld::SmiteSMLD: SMLD object to save
  • filepath::String: Directory path where to save the file
  • filename::String: Name of the output .mat file

Notes

  • Saves in MATLAB v7.3 format
  • Preserves all metadata fields
source
SMLMData.@filter — Macro
@filter(smld, condition)

Filter SMLD emitters using a natural condition syntax. Transforms expressions at compile time into efficient filtering operations.

Examples

# Simple conditions
bright = @filter(smld, photons > 1000)
early = @filter(smld, frame < 10)

# Compound conditions
good_fits = @filter(smld, σ_x < 0.02 && σ_y < 0.02)
roi = @filter(smld, 1.0 <= x <= 5.0 && 1.0 <= y <= 5.0)
source