Default args, whitespace, docstrings (#41)

The only functional change here is to call `pairwise_consts` only if
*both* `pσ` and `pϕ` are `nothing`. The implementation discards any
user-supplied values, and this could lead to surprising results if the
user supplies one but not the other. Accepting the error when you try to
index `nothing` seems like the safer approach, as it will force the user
to supply both or neither.

Aside from that, this just cleans up whitespace and fixes some
docstrings.

Author: timholy

src/GaussianMixtureAlignment.jl

@@ -2,8 +2,8 @@
 GaussianMixtureAlignment.jl
 ===========================
 
-GaussianMixtureAlignment.jl is a package used to align Gaussian mixture models. In particular, it uses an implementation 
-of the [GOGMA algorithm (Campbell, 2016)](https://arxiv.org/abs/1603.00150) to find globally optimal alignments of mixtures of 
+GaussianMixtureAlignment.jl is a package used to align Gaussian mixture models. In particular, it uses an implementation
+of the [GOGMA algorithm (Campbell, 2016)](https://arxiv.org/abs/1603.00150) to find globally optimal alignments of mixtures of
 isotropic (spherical) Gaussian distributions.
 
 REPL help

src/gogma/overlap.jl

@@ -1,7 +1,7 @@
 """
     ovlp = overlap(distsq, s, w)
 
-Calculates the unnormalized overlap between two Gaussian distributions with width `s`, 
+Calculates the unnormalized overlap between two Gaussian distributions with width `s`,
 weight `w', and squared distance `distsq`.
 """
 function overlap(distsq::Real, s::Real, w::Real)
@@ -16,36 +16,30 @@ end
 Calculates the unnormalized overlap between two Gaussian distributions with variances
 `σx` and `σy`, weights `ϕx` and `ϕy`, and means separated by distance `dist`.
 """
-function overlap(dist::Real, σx::Real, σy::Real, ϕx::Real, ϕy::Real) 
+function overlap(dist::Real, σx::Real, σy::Real, ϕx::Real, ϕy::Real)
     return overlap(dist^2, σx^2 + σy^2, ϕx*ϕy)
 end
 
 """
-    ovlp = overlap(x::IsotropicGaussian, y::IsotropicGaussian, xtform=identity)
+    ovlp = overlap(x::IsotropicGaussian, y::IsotropicGaussian)
 
 Calculates the unnormalized overlap between two `IsotropicGaussian` objects.
 """
-function overlap(x::AbstractIsotropicGaussian, y::AbstractIsotropicGaussian, s=nothing, w=nothing)
-    if isnothing(s)
-        s = x.σ^2 + y.σ^2
-    end
-    if isnothing(w)
-        w = x.ϕ*y.ϕ
-    end
-    return overlap(sum(abs2, x.μ.-y.μ), s, w) 
+function overlap(x::AbstractIsotropicGaussian, y::AbstractIsotropicGaussian, s=x.σ^2+y.σ^2, w=x.ϕ*y.ϕ)
+    return overlap(sum(abs2, x.μ.-y.μ), s, w)
 end
 
 """
-    ovlp = overlap(x::AbstractSingleGMM, y::AbstractSingleGMM, xtform=identity)
+    ovlp = overlap(x::AbstractSingleGMM, y::AbstractSingleGMM)
 
 Calculates the unnormalized overlap between two `AbstractSingleGMM` objects.
 """
 function overlap(x::AbstractSingleGMM, y::AbstractSingleGMM, pσ=nothing, pϕ=nothing)
     # prepare pairwise widths and weights, if not provided
-    if isnothing(pσ) || isnothing(pϕ)
+    if isnothing(pσ) && isnothing(pϕ)
         pσ, pϕ = pairwise_consts(x, y)
     end
-    
+
     # sum overlaps for all pairwise combinations of Gaussians between x and y
     ovlp = zero(promote_type(numbertype(x),numbertype(y)))
     for (i,gx) in enumerate(x.gaussians)
@@ -57,16 +51,16 @@ function overlap(x::AbstractSingleGMM, y::AbstractSingleGMM, pσ=nothing, pϕ=no
 end
 
 """
-    ovlp = overlap(x::AbstractMultiGMM, y::AbstractMultiGMM, xtform=identity)
+    ovlp = overlap(x::AbstractMultiGMM, y::AbstractMultiGMM)
 
 Calculates the unnormalized overlap between two `AbstractMultiGMM` objects.
 """
 function overlap(x::AbstractMultiGMM, y::AbstractMultiGMM, mpσ=nothing, mpϕ=nothing, interactions=nothing)
     # prepare pairwise widths and weights, if not provided
-    if isnothing(mpσ) || isnothing(mpϕ)
+    if isnothing(mpσ) && isnothing(mpϕ)
         mpσ, mpϕ = pairwise_consts(x, y, interactions)
     end
-    
+
     # sum overlaps from each keyed pairs of GMM
     ovlp = zero(promote_type(numbertype(x),numbertype(y)))
     for k1 in keys(mpσ)
@@ -76,9 +70,9 @@ function overlap(x::AbstractMultiGMM, y::AbstractMultiGMM, mpσ=nothing, mpϕ=no
     end
     return ovlp
 end
-    
+
 """
-l2dist = distance(x, y)
+    l2dist = distance(x, y)
 
 Calculates the L2 distance between two GMMs made up of spherical Gaussian distributions.
 """
@@ -87,7 +81,7 @@ function distance(x::AbstractGMM, y::AbstractGMM)
 end
 
 """
-tani = tanimoto(x, y)
+    tani = tanimoto(x, y)
 
 Calculates the tanimoto distance based on Gaussian overlap between two GMMs.
 """

test/runtests.jl

@@ -50,8 +50,8 @@ const GMA = GaussianMixtureAlignment
     lb = gauss_l2_bounds(x,y,RotationRegion(π/2/sqrt3))[1]
     @test lb ≈ -GMA.overlap(5^2,2*σ^2,ϕ*ϕ)
     lb = gauss_l2_bounds(x,y,RotationRegion(RotationVec(0,0,π/4),SVector{3}(0.,0.,0.),π/4/(sqrt3)))[1]
-    @test lb ≈ -GMA.overlap(5^2,2*σ^2,ϕ*ϕ) 
-    
+    @test lb ≈ -GMA.overlap(5^2,2*σ^2,ϕ*ϕ)
+
     # translation distance, no rotation
     # translation region centered at origin
     lb, ub = gauss_l2_bounds(x,y,TranslationRegion(1/sqrt3))
@@ -61,7 +61,7 @@ const GMA = GaussianMixtureAlignment
     lb, ub = gauss_l2_bounds(x+SVector(1,0,0),y,TranslationRegion(1/sqrt3))
     @test lb ≈ -GMA.overlap(7^2,2*σ^2,ϕ*ϕ)
     @test ub ≈ -GMA.overlap(8^2,2*σ^2,ϕ*ϕ)
-    # centered with translation of 3 in +y 
+    # centered with translation of 3 in +y
     lb, ub = gauss_l2_bounds(x+SVector(0,3,0),y,TranslationRegion(1/sqrt3))
     @test lb ≈ -GMA.overlap((√(58)-1)^2,2*σ^2,ϕ*ϕ)
     @test ub ≈ -GMA.overlap(58,2*σ^2,ϕ*ϕ)
@@ -97,7 +97,7 @@ end
 
 @testset "bounds for shrinking searchspace around an optimum" begin
     # two sets of points, each forming a 3-4-5 triangle
-    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]] 
+    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]]
     ypts = [[1.,1.,1.], [1.,-2.,1.], [1.,1.,-3.]]
     σ = ϕ = 1.
     gmmx = IsotropicGMM([IsotropicGaussian(x, σ, ϕ) for x in xpts])
@@ -121,7 +121,7 @@ end
 
 @testset "GOGMA runs without errors" begin
     # two sets of points, each forming a 3-4-5 triangle
-    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]] 
+    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]]
     ypts = [[1.,1.,1.], [1.,-2.,1.], [1.,1.,-3.]]
     σ = ϕ = 1.
     gmmx = IsotropicGMM([IsotropicGaussian(x, σ, ϕ) for x in xpts])
@@ -175,7 +175,7 @@ end
 end
 
 @testset "GO-ICP and GO-IH run without errors" begin
-    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]] 
+    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]]
     ypts = [[1.,1.,1.], [1.,-2.,1.], [1.,1.,-3.]]
 
     xset = PointSet(xpts);
@@ -189,7 +189,7 @@ end
 end
 
 @testset "Kabsch" begin
-    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]] 
+    xpts = [[0.,0.,0.], [3.,0.,0.,], [0.,4.,0.]]
     ypts = [[1.,1.,1.], [1.,-2.,1.], [1.,1.,-3.]]
 
     xset = PointSet(xpts, ones(3))