Add pattern_ids tracking and update SMLMData compat to 0.6

- uniform2D/uniform3D now return pattern_ids indicating pattern membership
- apply_labeling preserves pattern_ids through expansion (with backward-compat overloads)
- Emitters now carry pattern id through simulation pipeline
- Update SMLMData compat to "0.5, 0.6"
- Update documentation for new return signatures

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kalidke

Project.toml

@@ -14,7 +14,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 [compat]
 Distributions = "0.25"
 MicroscopePSFs = "0.5"
-SMLMData = "0.5.1"
+SMLMData = "0.5, 0.6"
 julia = "1.6"
 
 [extras]

api_overview.md

@@ -512,21 +512,21 @@ rotate!(pattern3d, R)
 #### apply_labeling
 
 Apply labeling strategy to binding site coordinates, expanding each site to the
-appropriate number of fluorophore positions.
+appropriate number of fluorophore positions while preserving pattern IDs.
 
 ```julia
-# Generate binding site coordinates from pattern distribution
-x, y = uniform2D(1.0, Nmer2D(), 10.0, 10.0)  # ~100 binding sites
+# Generate binding site coordinates with pattern IDs from pattern distribution
+x, y, pattern_ids = uniform2D(1.0, Nmer2D(), 10.0, 10.0)
 
-# Apply Poisson labeling (average 1.5 fluorophores per site)
-x_labeled, y_labeled = apply_labeling((x, y), PoissonLabeling(1.5))
+# Apply labeling with pattern ID tracking (returns coords tuple and new IDs)
+(x_labeled, y_labeled), new_ids = apply_labeling((x, y), pattern_ids, PoissonLabeling(1.5))
 
-# Apply fixed labeling with efficiency
+# Backward-compatible: without pattern IDs (returns only coords)
 x_labeled, y_labeled = apply_labeling((x, y), FixedLabeling(1; efficiency=0.8))
 
 # Works with 3D coordinates too
-x, y, z = uniform3D(1.0, Nmer3D(), 10.0, 10.0)
-x_labeled, y_labeled, z_labeled = apply_labeling((x, y, z), BinomialLabeling(4, 0.8))
+x, y, z, pattern_ids = uniform3D(1.0, Nmer3D(), 10.0, 10.0)
+(x_labeled, y_labeled, z_labeled), new_ids = apply_labeling((x, y, z), pattern_ids, BinomialLabeling(4, 0.8))
 ```
 
 #### n_fluorophores
@@ -543,7 +543,8 @@ n = n_fluorophores(labeling)  # Returns Int (can be 0)
 
 ### Pattern Distribution
 
-Generate random pattern distributions in a field.
+Generate random pattern distributions in a field. Each function returns coordinates
+plus pattern instance IDs for tracking which emitters belong to the same pattern.
 
 ```julia
 # Create patterns
@@ -555,11 +556,12 @@ field_x = 10.0 # μm
 field_y = 10.0 # μm
 density = 1.0  # patterns per μm²
 
-# Get coordinates for 2D distribution
-x, y = uniform2D(density, pattern2d, field_x, field_y)
+# Get coordinates for 2D distribution (returns pattern IDs)
+x, y, pattern_ids = uniform2D(density, pattern2d, field_x, field_y)
+# pattern_ids[i] indicates which pattern instance point i belongs to
 
-# Get coordinates for 3D distribution
-x, y, z = uniform3D(density, pattern3d, field_x, field_y, zrange=[-2.0, 2.0])
+# Get coordinates for 3D distribution (returns pattern IDs)
+x, y, z, pattern_ids = uniform3D(density, pattern3d, field_x, field_y, zrange=[-2.0, 2.0])
 ```
 
 ## Common Workflows

docs/src/core/patterns.md

@@ -105,13 +105,16 @@ field_y = 10.0  # μm
 pattern = Nmer2D(n=6, d=0.2)
 density = 1.5   # patterns/μm²
 
-x, y = uniform2D(density, pattern, field_x, field_y)
+x, y, pattern_ids = uniform2D(density, pattern, field_x, field_y)
+# pattern_ids[i] indicates which pattern instance point i belongs to
 
 # Create custom distribution of 3D patterns
 pattern3d = Nmer3D(n=6, d=0.2)
-x, y, z = uniform3D(density, pattern3d, field_x, field_y, zrange=[-2.0, 2.0])
+x, y, z, pattern_ids = uniform3D(density, pattern3d, field_x, field_y, zrange=[-2.0, 2.0])
 ```
 
+The `pattern_ids` array tracks which pattern instance each point belongs to. This is useful for analysis, visualization (coloring by pattern), or grouping emitters by their originating structure. The `id` field on emitters in the simulation output contains this pattern ID.
+
 ## Pattern Manipulation
 
 ### Rotation

src/core/labeling.jl

@@ -173,57 +173,102 @@ Apply Labeling to Coordinates
 ==========================================================================#
 
 """
-    apply_labeling(coords, labeling::AbstractLabeling)
+    apply_labeling(coords, pattern_ids, labeling::AbstractLabeling)
 
 Apply labeling strategy to binding site coordinates, expanding each site
-to the appropriate number of fluorophore positions.
+to the appropriate number of fluorophore positions while preserving pattern IDs.
 
 # Arguments
 - `coords`: Tuple of coordinate vectors `(x, y)` for 2D or `(x, y, z)` for 3D
+- `pattern_ids::Vector{Int}`: Pattern instance ID for each binding site
 - `labeling::AbstractLabeling`: Labeling strategy to apply
 
 # Returns
-- Tuple of coordinate vectors with fluorophore positions
+- `Tuple`: (coords, new_pattern_ids) where coords is a tuple of coordinate vectors
+  and new_pattern_ids preserves pattern membership for each fluorophore
 
 # Example
 ```julia
-# Original: 100 binding sites
-x, y = uniform2D(1.0, Nmer2D(), 10.0, 10.0)
+# Original: binding sites with pattern IDs
+x, y, pattern_ids = uniform2D(1.0, Nmer2D(), 10.0, 10.0)
 
-# After Poisson labeling: variable number of fluorophores
-x_labeled, y_labeled = apply_labeling((x, y), PoissonLabeling(1.5))
+# After Poisson labeling: variable number of fluorophores, pattern IDs preserved
+(x_labeled, y_labeled), new_ids = apply_labeling((x, y), pattern_ids, PoissonLabeling(1.5))
 ```
 """
-function apply_labeling(coords::Tuple{Vector{T}, Vector{T}}, labeling::AbstractLabeling) where T
+function apply_labeling(coords::Tuple{Vector{T}, Vector{T}}, pattern_ids::Vector{Int},
+                       labeling::AbstractLabeling) where T
     x, y = coords
     new_x = T[]
     new_y = T[]
+    new_ids = Int[]
 
     for i in eachindex(x)
         n = n_fluorophores(labeling)
         for _ in 1:n
             push!(new_x, x[i])
             push!(new_y, y[i])
+            push!(new_ids, pattern_ids[i])
         end
     end
 
-    return (new_x, new_y)
+    return (new_x, new_y), new_ids
 end
 
-function apply_labeling(coords::Tuple{Vector{T}, Vector{T}, Vector{T}}, labeling::AbstractLabeling) where T
+function apply_labeling(coords::Tuple{Vector{T}, Vector{T}, Vector{T}}, pattern_ids::Vector{Int},
+                       labeling::AbstractLabeling) where T
     x, y, z = coords
     new_x = T[]
     new_y = T[]
     new_z = T[]
+    new_ids = Int[]
 
     for i in eachindex(x)
         n = n_fluorophores(labeling)
         for _ in 1:n
             push!(new_x, x[i])
             push!(new_y, y[i])
             push!(new_z, z[i])
+            push!(new_ids, pattern_ids[i])
         end
     end
 
-    return (new_x, new_y, new_z)
+    return (new_x, new_y, new_z), new_ids
+end
+
+# Backward-compatible overloads without pattern_ids (returns only coords)
+"""
+    apply_labeling(coords, labeling::AbstractLabeling)
+
+Apply labeling strategy to binding site coordinates without pattern tracking.
+
+This is a convenience method that returns only the expanded coordinates
+(for backward compatibility).
+
+# Arguments
+- `coords`: Tuple of coordinate vectors `(x, y)` for 2D or `(x, y, z)` for 3D
+- `labeling::AbstractLabeling`: Labeling strategy to apply
+
+# Returns
+- Tuple of coordinate vectors with fluorophore positions
+
+# Example
+```julia
+# Apply labeling without pattern tracking
+x, y = [1.0, 2.0], [3.0, 4.0]
+new_x, new_y = apply_labeling((x, y), FixedLabeling(2))
+```
+"""
+function apply_labeling(coords::Tuple{Vector{T}, Vector{T}}, labeling::AbstractLabeling) where T
+    # Generate sequential IDs for backward compatibility
+    pattern_ids = collect(1:length(coords[1]))
+    result, _ = apply_labeling(coords, pattern_ids, labeling)
+    return result
+end
+
+function apply_labeling(coords::Tuple{Vector{T}, Vector{T}, Vector{T}}, labeling::AbstractLabeling) where T
+    # Generate sequential IDs for backward compatibility
+    pattern_ids = collect(1:length(coords[1]))
+    result, _ = apply_labeling(coords, pattern_ids, labeling)
+    return result
 end

src/core/patterns.jl

@@ -323,13 +323,14 @@ Create coordinate arrays for randomly placed and rotated 2D patterns.
 - `field_y::Float64`: Field height in microns
 
 # Returns
-- `Tuple{Vector{Float64}, Vector{Float64}}`: (x, y) coordinates in microns
+- `Tuple{Vector{Float64}, Vector{Float64}, Vector{Int}}`: (x, y, pattern_ids) where
+  pattern_ids indicates which pattern instance each point belongs to
 
 # Example
 ```julia
 # Generate coordinates for randomly placed Nmer2D patterns
 nmer = Nmer2D(; n=6, d=0.2)
-x, y = uniform2D(1.0, nmer, 10.0, 10.0)
+x, y, pattern_ids = uniform2D(1.0, nmer, 10.0, 10.0)
 ```
 """
 function uniform2D(ρ::T1, p::Pattern2D, field_x::T2, field_y::T3) where {T1<:AbstractFloat, T2<:AbstractFloat, T3<:AbstractFloat}
@@ -348,7 +349,8 @@ function _uniform2D_impl(ρ::T, p::Pattern2D, field_x::T, field_y::T) where T <:
     # Initialize coordinate arrays
     x = Vector{T}(undef, ntotal)
     y = Vector{T}(undef, ntotal)
-    
+    pattern_ids = Vector{Int}(undef, ntotal)
+
     idx = 1
     for nn = 1:npatterns
         θ = 2 * pi * rand()
@@ -359,15 +361,16 @@ function _uniform2D_impl(ρ::T, p::Pattern2D, field_x::T, field_y::T) where T <:
             # Rotate and translate pattern points
             x[idx] = p.x[mm] * cos(θ) - p.y[mm] * sin(θ) + x0
             y[idx] = p.x[mm] * sin(θ) + p.y[mm] * cos(θ) + y0
+            pattern_ids[idx] = nn
             idx += 1
         end
     end
 
-    return x, y
+    return x, y, pattern_ids
 end
 
 """
-    uniform3D(ρ::Float64, p::Pattern3D, field_x::Float64, field_y::Float64; 
+    uniform3D(ρ::Float64, p::Pattern3D, field_x::Float64, field_y::Float64;
              zrange::Vector{Float64}=[-1.0, 1.0])
 
 Create coordinate arrays for randomly placed and rotated 3D patterns.
@@ -380,13 +383,14 @@ Create coordinate arrays for randomly placed and rotated 3D patterns.
 - `zrange::Vector{Float64}=[-1.0, 1.0]`: [min_z, max_z] range in microns
 
 # Returns
-- `Tuple{Vector{Float64}, Vector{Float64}, Vector{Float64}}`: (x, y, z) coordinates
+- `Tuple{Vector{Float64}, Vector{Float64}, Vector{Float64}, Vector{Int}}`: (x, y, z, pattern_ids) where
+  pattern_ids indicates which pattern instance each point belongs to
 
 # Example
 ```julia
 # Generate coordinates for randomly placed Nmer3D patterns
 nmer = Nmer3D(; n=6, d=0.2)
-x, y, z = uniform3D(1.0, nmer, 10.0, 10.0; zrange=[-2.0, 2.0])
+x, y, z, pattern_ids = uniform3D(1.0, nmer, 10.0, 10.0; zrange=[-2.0, 2.0])
 ```
 """
 function uniform3D(ρ::T1, p::Pattern3D, field_x::T2, field_y::T3;
@@ -405,7 +409,7 @@ function _uniform3D_impl(ρ::T, p::Pattern3D, field_x::T, field_y::T;
     if length(zrange) != 2 || zrange[1] >= zrange[2]
         throw(ArgumentError("zrange must be a vector of two values [min_z, max_z] where min_z < max_z"))
     end
-    
+
     # Generate random number of patterns (note: ρ is 2D density)
     npatterns = rand(Poisson(field_x * field_y * ρ))
     ntotal = npatterns * p.n
@@ -414,7 +418,8 @@ function _uniform3D_impl(ρ::T, p::Pattern3D, field_x::T, field_y::T;
     x = Vector{T}(undef, ntotal)
     y = Vector{T}(undef, ntotal)
     z = Vector{T}(undef, ntotal)
-    
+    pattern_ids = Vector{Int}(undef, ntotal)
+
     idx = 1
     for nn = 1:npatterns
         # Random position
@@ -425,12 +430,12 @@ function _uniform3D_impl(ρ::T, p::Pattern3D, field_x::T, field_y::T;
         # Generate random 3D rotation using quaternions
         # This gives uniform rotation in 3D space
         u1, u2, u3 = rand(3)
-        
+
         q0 = sqrt(1 - u1) * sin(2π * u2)
         q1 = sqrt(1 - u1) * cos(2π * u2)
         q2 = sqrt(u1) * sin(2π * u3)
         q3 = sqrt(u1) * cos(2π * u3)
-        
+
         # Convert quaternion to rotation matrix
         R = [
             1-2*(q2^2 + q3^2)  2*(q1*q2 - q0*q3)  2*(q1*q3 + q0*q2);
@@ -444,11 +449,12 @@ function _uniform3D_impl(ρ::T, p::Pattern3D, field_x::T, field_y::T;
             x[idx] = pos[1] + x0
             y[idx] = pos[2] + y0
             z[idx] = pos[3] + z0
+            pattern_ids[idx] = nn
             idx += 1
         end
     end
 
-    return x, y, z
+    return x, y, z, pattern_ids
 end
 
 #==========================================================================

src/core/photophysics.jl

@@ -221,7 +221,8 @@ function kinetic_model(smld::BasicSMLD, f::Molecule, nframes::Int, framerate::Re
                     σ_xy=0.0,            # x-y covariance (0 for symmetric PSF)
                     frame=frame,
                     dataset=dd,
-                    track_id=pos.track_id
+                    track_id=pos.track_id,
+                    id=pos.id
                 )
             elseif emitter_type <: Emitter3DFit
                 emitter = Emitter3DFit{Float64}(
@@ -233,7 +234,8 @@ function kinetic_model(smld::BasicSMLD, f::Molecule, nframes::Int, framerate::Re
                     σ_xy=0.0,             # x-y covariance (0 for symmetric PSF)
                     frame=frame,
                     dataset=dd,
-                    track_id=pos.track_id
+                    track_id=pos.track_id,
+                    id=pos.id
                 )
             else
                 error("Unsupported emitter type: $emitter_type")

src/static/simulation.jl

@@ -139,14 +139,18 @@ function simulate(params::StaticSMLMParams;
         field_y = maximum(centers_y) - minimum(centers_y)
 
         # Generate binding site coordinates based on pattern type
-        coords = if pattern isa Pattern2D
-            uniform2D(params.density, pattern, field_x, field_y)
+        # uniform2D/uniform3D now return pattern_ids as well
+        coords_with_ids = if pattern isa Pattern2D
+            x, y, pattern_ids = uniform2D(params.density, pattern, field_x, field_y)
+            ((x, y), pattern_ids)
         else
-            uniform3D(params.density, pattern, field_x, field_y; zrange=params.zrange)
+            x, y, z, pattern_ids = uniform3D(params.density, pattern, field_x, field_y; zrange=params.zrange)
+            ((x, y, z), pattern_ids)
         end
+        coords, pattern_ids = coords_with_ids
 
         # Apply labeling to expand binding sites to fluorophore positions
-        coords = apply_labeling(coords, labeling)
+        coords, pattern_ids = apply_labeling(coords, pattern_ids, labeling)
 
         # Create emitters for true positions
         emitters = if pattern isa Pattern2D
@@ -160,7 +164,8 @@ function simulate(params::StaticSMLMParams;
                 σ_xy=0.0,            # x-y covariance (0 for symmetric PSF)
                 frame=1,
                 dataset=1,
-                track_id=i
+                track_id=i,
+                id=pattern_ids[i]
             ) for i in 1:length(x)]
         else
             x, y, z = coords
@@ -173,7 +178,8 @@ function simulate(params::StaticSMLMParams;
                 σ_xy=0.0,            # x-y covariance (0 for symmetric PSF)
                 frame=1,
                 dataset=1,
-                track_id=i
+                track_id=i,
+                id=pattern_ids[i]
             ) for i in 1:length(x)]
         end