SMLMMetrics

efficiency(a::Array{<:Real}, b::Array{<:Real}, cutoff::Vector{<:Real}, α::Union{Nothing, Vector{<:Real}}=nothing)

Calculate the efficiency metric between two sets a and b using a maximum connection distance of cutoff for the Jaccard Index, and a dimensional weighting α for the RMSE. The efficiency is defined as:

$E = 1 - \sqrt{(1 - JI)^2 + α^2 * RMSE^2}$

a and b are d x n, and d x m arrays, where d is the number of dimensions. cutoff contains the maximum matching distance for each dimension for the Jaccard Index. α contains the dimensional weighting for the RMSE.

Lateral and axial efficiencies are calculated separately and then averaged to obtain the overall efficiency. The first two dimensions are considered lateral and the third dimension is considered axial. The default alpha values are α = 1 × 10^{-2} nm^{-1} for lateral and α = 0.5 × 10^{-2} nm^{-1} for axial. The units of α should be the inverse of the units of a and b.

Detection accuracy is expressed in units of 0 to 1. The efficiency ranges up to 100% for a perfect fitting algorithm.

efficiency(a::SMLMData.SMLD2D, b::SMLMData.SMLD2D, cutoff::Vector{<:Real}; α::Vector{<:Real} = (default is [1e-2, 1e-2, 5e-2]))

Calculate the efficiency between two sets of 2D SMLM data a and b using a maximum connection distance of cutoff. α is an optional argument that provides weights for each dimension. (default is [1e-2 1e-2 5e-2])

The function first converts the data from the SMLD2D format into coordinate arrays, and then calculates the efficiency using the provided cutoff and α parameters.

Returns the calculated efficiency value.

Examples

efficiency(data1, data2, [1.0, 1.0])
efficiency(data1, data2, [1.0, 1.0], [0.5, 0.5])

efficiency(a::SMLMData.SMLD3D, b::SMLMData.SMLD3D, cutoff::Vector{<:Real}; α::Vector{<:Real} = ones(3))

Calculate the efficiency between two sets of 3D SMLM data a and b using a maximum connection distance of cutoff. α is an optional argument that provides weights for each dimension.

The function first converts the data from the SMLD3D format into coordinate arrays, and then calculates the efficiency using the provided cutoff and α parameters.

Returns the calculated efficiency value.

Examples

efficiency(data1, data2, [1.0, 1.0, 1.0])
efficiency(data1, data2, [1.0, 1.0, 1.0], [0.5, 0.5, 0.5])

jaccard(a, b, cutoff)

Calculate the Jaccard Index between the two sets a and b using a maximum connection distance of cutoff.

The Jaccard index is defined as:

J(A,B) =  |A ∩ B| / |A ∪ B|

The intersecting elements of A and B found by building and minimizing a cost matrix whose elements are:

\[C_{i,j} = \begin{cases} \left\| A_{i,:} - B_{j,:} \right\| & \text{if all } A_{i,k} - B_{j,k} < d_k \\ \infty & \text{otherwise} \end{cases}\]

where d is a vector of cutoff values for each dimension of the data.

jaccard(a::Array{<:Real}, b::Array{<:Real}, cutoff::Vector{<:Real})

a and b are d x n, and d x m arrays, where d is the number of dimensions

cutoff contains the maximum matching distance for each dimension.

jaccard(a::SMLMData.SMLD2D, b::SMLMData.SMLD2D, cutoff::Vector{<:Real})

Computes the Jaccard index for two sets of 2D localizations represented by SMLD2D structures a and b.

Arguments

• a::SMLMData.SMLD2D: First set of localizations
• b::SMLMData.SMLD2D: Second set of localizations
• cutoff::Vector{<:Real}: A vector of cutoff distances for each dimension

Returns

• Float64: Jaccard index between the two sets of localizations

jaccard(a::SMLMData.SMLD3D, b::SMLMData.SMLD3D, cutoff::Vector{<:Real})

Computes the Jaccard index for two sets of 3D localizations represented by SMLD3D structures a and b.

Arguments

• a::SMLMData.SMLD3D: First set of localizations
• b::SMLMData.SMLD3D: Second set of localizations
• cutoff::Vector{<:Real}: A vector of cutoff distances for each dimension

Returns

• Float64: Jaccard index between the two sets of localizations

match(a::Array{<:Real}, b::Array{<:Real}, cutoff::Vector{<:Real})

Find the best matching pairs of points between a and b based on Euclidean distance, with a specified maximum acceptable distance for each dimension defined in cutoff.

The function uses the Hungarian algorithm to find the optimal assignment that minimizes the total distance between pairs.

Parameters:

• a and b are d x n and d x m arrays, respectively, where d is the number of dimensions.
• cutoff is a d-dimensional vector, specifying the maximum acceptable distance in each dimension.

The function returns a n-dimensional vector, where the ith element is the index of the point in b that is matched with the ith point in a. If the ith point in a has no match in b (i.e., the distance to all points in b is larger than the cutoff), then the ith element of the returned vector is 0.

The function uses a cost matrix approach, where the cost is the Euclidean distance between points. If the distance between a pair of points exceeds the cutoff, the cost is set to a large value to effectively eliminate that pairing from consideration. The Hungarian algorithm is then used to find the assignment that minimizes the total cost. The cost matrix and the assignment are adjusted such that pairs with a cost equal to the large value are unassigned (i.e., set to 0 in the assignment vector).

function rmse(a, b)

Calculate the root mean square error between a and b.

rmse(a::Array{<:Real}, b::Array{<:Real}, α::Vector{<:Real}, assignment::Vector{Int})

Calculate the root mean square error using a dimensional weighting α, only for the matched pairs.

a and b are d x n, and d x m arrays, where d is the number of dimensions

$RMSE = \sqrt{\frac{1}{d}\frac{1}{N}\sum_{k=1}^{d}\alpha_k^2\sum_{n=1}^N (a_{k,i}-b_{k,assignment[i]})^2}$

assignment is the output from the match function, and assignment[i] gives the index in b that matches with the ith element in a. If assignment[i] == 0, then the ith element in a has no match in b.

function rmse(a::Array{<:Real}, b::Array{<:Real}, α::Vector{<:Real})

Calculate the root mean square error using a dimensional weighting α.

a and b are d x n, and d x m arrays, where d is the number of dimensions

$RMSE = (\frac{1}{d}\frac{1}{N}\Sigma_{k=1}^{d}\alpha_k^2\Sigma_{n=1}^N (a_{k,i}-b_{k,i})^2)^{1/2}$

rmse(a::SMLMData.SMLD2D, b::SMLMData.SMLD2D; α::Vector{<:Real} = ones(2))

Computes the root mean squared error (RMSE) for two sets of 2D localizations represented by SMLD2D structures a and b.

Arguments

• a::SMLMData.SMLD2D: First set of localizations
• b::SMLMData.SMLD2D: Second set of localizations
• α::Vector{<:Real}: Optional weight vector for each dimension (default is ones(2))

Returns

• Float64: RMSE between the two sets of localizations

rmse(a::SMLMData.SMLD3D, b::SMLMData.SMLD3D; α::Vector{<:Real} = [1e-2, 1e-2, 5e-2])

Computes the root mean squared error (RMSE) for two sets of 3D localizations represented by SMLD3D structures a and b.

Arguments

• a::SMLMData.SMLD3D: First set of localizations
• b::SMLMData.SMLD3D: Second set of localizations
• α::Vector{<:Real}: Optional weight vector for each dimension (default is [1e-2, 1e-2, 5e-2])

Returns

• Float64: RMSE between the two sets of localizations