Merge pull request #22 from JuliaSMLM/refactor-new-smlmdata-psfs

Refactor new smlmdata psfs

Author: kalidke

.github/workflows/CI.yml

@@ -10,7 +10,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.6'
+          - '1.11'
           - 'nightly'
         os:
           - ubuntu-latest

CLAUDE.md

@@ -0,0 +1,23 @@
+# SMLMSim.jl Development Guide
+
+## Build, Test & Run Commands
+- Install dependencies: `julia --project -e "using Pkg; Pkg.instantiate()"`
+- Run all tests: `julia --project -e "using Pkg; Pkg.test()"`
+- Run specific test: `julia --project -e "using Pkg; Pkg.test(\"SMLMSim\", test_args=[\"Patterns\"])"`
+- Build docs: `julia --project=docs/ docs/make.jl`
+- Run benchmark: `julia --project=dev/ dev/benchmark.jl`
+
+## Code Style Guidelines
+- Use physical units consistently (μm for space, seconds for time)
+- Follow Julia naming conventions: lowercase for functions, CamelCase for types
+- Organize imports: standard library first, then external packages
+- Place exports at module level, grouped by functionality
+- Type parameters should be explicit for functions with multiple dispatch
+- Error handling: use descriptive errors with parameter names and constraints
+- Documentation: include docstrings with examples and physical units
+- Re-export SMLMData types rather than redefining them
+- Follow existing patterns for defining new molecule or pattern types
+- Tests should use the `@test` macro with appropriate tolerances for floating-point comparisons
+
+## Module Structure
+Functions should be organized in appropriate submodules: core, static, or diffusion.

Project.toml

@@ -1,22 +1,21 @@
 name = "SMLMSim"
 uuid = "5a0a87e4-02d4-41f5-bf26-b8c94c784a04"
 authors = ["klidke@unm.edu"]
-version = "0.2.1"
+version = "0.3.0"
 
 [deps]
-CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MicroscopePSFs = "de9ac726-48a4-48ab-84b0-1c03c7c18929"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 SMLMData = "5488f106-40b8-4660-84c5-84a168990d1b"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
-CairoMakie = "0.10, 0.11"
 Distributions = "0.25"
-Images = "0.26"
-MicroscopePSFs = "0.3, 0.4"
-SMLMData = "0.1"
+Printf = "1.11.0"
+SMLMData = "0.2"
+Statistics = "1.11.1"
 julia = "1.6"
 
 [extras]

README.md

@@ -5,26 +5,243 @@
 [![Build Status](https://github.com/JuliaSMLM/SMLMSim.jl/workflows/CI/badge.svg)](https://github.com/JuliaSMLM/SMLMSim.jl/actions)
 [![Coverage](https://codecov.io/gh/JuliaSMLM/SMLMSim.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaSMLM/SMLMSim.jl)
 
-Generate simulated SMLM coordinate data.  Patterns, Cameras, Fluorophores, and SMLD data organization can be configured. 
+## Overview
 
-Simulation parameters use physical units. Resulting `SMLMData.SMLD` structures are in units of pixels and frames. 
+SMLMSim is a Julia package for simulating Single Molecule Localization Microscopy (SMLM) data with realistic physical properties. The package builds upon SMLMData, reexporting essential types and functions so you typically don't need to import SMLMData directly.
 
+The package provides tools for:
 
-The high level interface for simulating SMLM super-resolution coordinate data is the `SMLMSim.sim()` function.   
+- Generating spatial patterns of fluorophores in 2D and 3D
+- Simulating fluorophore photophysics with stochastic kinetic models
+- Adding realistic localization uncertainty based on photon counts
+- Simulating diffusion and interactions between molecules
+- Generating microscope images with configurable PSFs
 
+All simulations use physical units, with coordinates in microns and time in seconds. The resulting data is organized into `SMLMData.SMLD` structures compatible with the broader JuliaSMLM ecosystem.
+
+## Installation
+
+```julia
+using Pkg
+Pkg.add("SMLMSim")
 ```
+
+## Basic Usage
+
+The high-level interface for simulating SMLM super-resolution coordinate data is the `simulate()` function with a `StaticSMLMParams` object.
+
+```julia
 using SMLMSim
-using SMLMData
 
-smld_true, smld_model, smld_noisy = SMLMSim.sim(;
-    ρ=1.0,
-    σ_PSF=0.13, 
-    minphotons=50,
-    ndatasets=10,
-    nframes=1000,
-    framerate=50.0, # 1/s
-    pattern=SMLMSim.Nmer2D(),
-    molecule=SMLMSim.GenericFluor(; q=[0 50; 1e-2 0]), #1/s 
-    camera=SMLMSim.IdealCamera(; ypixels=256, xpixels=128, pixelsize=0.1) #pixelsize is microns
+# Basic simulation with default parameters
+camera = IdealCamera(1:128, 1:128, 0.1)  # 128×128 pixels, 100nm pixels
+params = StaticSMLMParams()  # Default parameters
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    camera=camera
+)
+```
+
+This basic example creates a 2D simulation using default parameters:
+- 8-molecule circular patterns (Nmer2D with n=8, d=0.1μm)
+- 1 pattern per square micron (ρ=1.0)
+- PSF width of 130nm (σ_psf=0.13μm)
+- Two-state fluorophore kinetics with realistic blinking behavior
+- 1000 frames at 50 frames per second
+- Minimum photon threshold of 50 for detection
+
+The function returns three SMLD objects with SMLM coordinates:
+- `smld_true`: Ground truth emitter positions (spatial coordinates only)
+- `smld_model`: Positions with simulated blinking kinetics (subset of true positions appearing in different frames)
+- `smld_noisy`: Positions with both blinking and localization uncertainty (realistic SMLM data with position errors)
+
+For more control, you can customize the parameters:
+
+```julia
+# More customized simulation
+params = StaticSMLMParams(
+    ρ=1.0,                # emitters per μm²
+    σ_psf=0.13,           # PSF width in μm (130nm)
+    minphotons=50,        # minimum photons for detection
+    ndatasets=10,         # number of independent datasets
+    nframes=1000,         # frames per dataset
+    framerate=50.0        # frames per second
+)
+
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=Nmer2D(n=6, d=0.2),  # hexamer with 200nm diameter
+    molecule=GenericFluor(; q=[0 50; 1e-2 0]),  # rates in 1/s
+    camera=IdealCamera(1:256, 1:128, 0.1)  # 128×256 pixels, 100nm pixels
+)
+```
+
+This customized example:
+- Creates hexagonal patterns (6 molecules in a 200nm circle)
+- Uses 10 independent datasets of 1000 frames each
+- Simulates fluorophores with specific on/off transition rates
+- Uses a rectangular camera field of view (128×256 pixels)
+
+In both cases, the output SMLD objects contain emitter information (x, y coordinates, photon counts, frame numbers, etc.) that can be used for further analysis or visualization.
+
+## Pattern Types
+
+SMLMSim includes several built-in pattern types for positioning fluorophores:
+
+### 2D Patterns
+
+```julia
+# N molecules arranged in a circle
+nmer = Nmer2D(n=8, d=0.1)  # 8 molecules in a 100nm diameter circle
+
+# Linear pattern with random positions
+line = Line2D(λ=5.0, endpoints=[(-2.0, 0.0), (2.0, 0.0)])  # 5 molecules per μm along line
+```
+
+### 3D Patterns
+
+```julia
+# N molecules arranged in a circle at z=0
+nmer3d = Nmer3D(n=8, d=0.1)  # 8 molecules in a 100nm diameter circle
+
+# 3D line with random positions
+line3d = Line3D(λ=5.0, endpoints=[(-1.0, 0.0, -0.5), (1.0, 0.0, 0.5)])
+```
+
+## Molecule Models
+
+SMLMSim supports different fluorophore photophysical models:
+
+```julia
+# Generic fluorophore with two-state kinetics
+fluor = GenericFluor(
+    γ=10000.0,           # photon emission rate in Hz
+    q=[0 10; 1e-2 0]     # transition rate matrix: state 1 ↔ state 2
 )
 ```
+
+## Diffusion and Interaction Simulation
+
+The package includes tools for simulating diffusion and interactions between molecules:
+
+```julia
+# Set up parameters for Smoluchowski diffusion simulation
+params = SmoluchowskiParams(
+    density = 0.5,        # molecules per μm²
+    box_size = 10.0,      # μm
+    diff_monomer = 0.1,   # μm²/s
+    diff_dimer = 0.05,    # μm²/s
+    k_off = 0.2,          # s⁻¹
+    r_react = 0.01,       # μm
+    d_dimer = 0.05,       # μm
+    dt = 0.01,            # s
+    t_max = 10.0          # s
+)
+
+# Run simulation
+systems = simulate(params)
+
+# Visualize the simulation
+visualize_sequence(systems, filename="diffusion.mp4", framerate=round(Int64,1/params.dt))
+
+# Generate microscope images
+psf = Gaussian2D(0.15)  # 150nm PSF width
+images = gen_image_sequence(
+    psf, 
+    systems,
+    frame_integration=10
+)
+
+# Extract only dimers
+dimer_systems = get_dimers(systems)
+dimer_images = gen_image_sequence(
+    psf, 
+    dimer_systems, 
+    frame_integration=10
+)
+```
+
+## Example Workflows
+
+### 2D Simulation with Visualization
+
+```julia
+using SMLMSim
+using CairoMakie
+
+# Create camera with physical pixel size
+camera = IdealCamera(1:128, 1:256, 0.1)  # 128×256 pixels, 100nm pixels
+
+# Create simulation parameters
+params = StaticSMLMParams(
+    ρ=1.0,                # emitters per μm²
+    σ_psf=0.13            # PSF width in μm
+)
+
+# Run simulation
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=Nmer2D(n=6, d=0.2),  # hexamer with 200nm diameter
+    camera=camera
+)
+
+# Extract coordinates from emitters
+x_noisy = [e.x for e in smld_noisy.emitters]
+y_noisy = [e.y for e in smld_noisy.emitters]
+photons = [e.photons for e in smld_noisy.emitters]
+
+# Create figure and plot results
+fig = Figure(size=(800, 600))
+ax = Axis(fig[1, 1], 
+    title="Simulated SMLM Localizations",
+    xlabel="x (μm)",
+    ylabel="y (μm)",
+    aspect=DataAspect(),
+    yreversed=true  # This makes (0,0) at top-left
+)
+
+# Scatter plot with photon counts as color
+scatter!(ax, x_noisy, y_noisy, 
+    color=photons,
+    colormap=:viridis,
+    markersize=4,
+    alpha=0.6
+)
+
+Colorbar(fig[1, 2], colormap=:viridis, label="Photons")
+
+# Show or save the figure
+display(fig)
+# save("smlm_simulation.png", fig)
+```
+
+### 3D Simulation
+
+```julia
+using SMLMSim
+
+# Create camera with physical pixel size
+camera = IdealCamera(1:128, 1:256, 0.1)  # 128×256 pixels, 100nm pixels
+
+# Create 3D simulation parameters
+params = StaticSMLMParams(
+    ρ=0.5,                # emitters per μm²
+    ndims=3,              # 3D simulation
+    zrange=[-2.0, 2.0]    # 4μm axial range
+)
+
+# Run simulation
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=Nmer3D(n=8, d=0.3),  # 3D pattern
+    camera=camera
+)
+```
+
+## Contributors
+
+- [JuliaSMLM Team](https://github.com/JuliaSMLM)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. The MIT License is a permissive license that allows for reuse with few restrictions. It permits use, modification, distribution, and private use while preserving copyright and license notices.

dev/Project.toml

@@ -1,8 +1,6 @@
-
 [deps]
-CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
-ImageView = "86fae568-95e7-573e-a6b2-d8a6b900c9ef"
-Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 MicroscopePSFs = "de9ac726-48a4-48ab-84b0-1c03c7c18929"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 SMLMSim = "5a0a87e4-02d4-41f5-bf26-b8c94c784a04"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"

dev/basic_sim_test.jl

@@ -0,0 +1,55 @@
+using Pkg
+Pkg.activate("dev")
+
+using Revise
+using SMLMSim
+using SMLMData
+using MicroscopePSFs
+using CairoMakie
+
+# 2D Example
+camera = IdealCamera(1:512, 1:512, 0.1)
+pattern = SMLMSim.Nmer2D(n=6, d=0.2)
+params = StaticSMLMParams(ρ=1.0, nframes = 100)
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=pattern,
+    camera=camera
+)
+
+# generate images
+psf = AiryPSF(1.2, .555)
+psf_spline = SplinePSF(psf, -1:.1:1, -1:.1:1)
+img = gen_images(smld_model, psf_spline; dataset=1,  support = 1.0)
+
+image(img[:, :, 1])
+
+
+
+
+# 3D Example
+pattern3d = SMLMSim.Nmer3D(n=8, d=0.3)
+params3d = StaticSMLMParams(
+    ρ=1.0,
+    ndims=3,
+    zrange=[-2.0, 2.0]
+)
+smld_true, smld_model, smld_noisy = simulate(
+    params3d,
+    pattern=pattern3d,
+    camera=camera
+)
+
+# Complex Pattern Example
+line3d = SMLMSim.Line3D(λ=5.0, endpoints=[(-1.0, 0.0, -0.5), (1.0, 0.0, 0.5)])
+params_line = StaticSMLMParams(
+    ρ=0.5,
+    σ_psf=0.15,
+    ndims=3
+)
+smld_true, smld_model, smld_noisy = simulate(
+    params_line,
+    pattern=line3d,
+    camera=camera
+)
+

dev/benchmark.jl

@@ -7,7 +7,7 @@ using BenchmarkTools
 γ=10000.0
 q=[0 10
    1e-1 0]
-f=SMLMSim.GenericFluor(γ,q)
+f=SMLMSim.GenericFluor(photons=γ, k_off=10.0, k_on=0.1)
 
 ## Simulate intensity trace