Merge pull request #135 from Marco-Congedo/dev

dev

Author: Marco-Congedo

Project.toml

@@ -1,7 +1,7 @@
 name = "PosDefManifoldML"
 uuid = "a07f4532-e2c9-11e9-2ea2-6d98fe4a1f21"
 authors = ["Marco-Congedo <marco.congedo@gmail.com>"]
-version = "0.5.15"
+version = "0.5.16"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

src/conditioners.jl

@@ -7,7 +7,7 @@
 
 # ? CONTENTS :
 #   This unit implements (pre) conditioners for fast Riemannian 
-#   machine learning classifier using package PosDefManifold.
+#   machine learning classifier using package PosDefManifoldML
 
 include("conditioners_lowlevel.jl")
 
@@ -30,14 +30,14 @@ This is because the learnt parameters will be needed for the transformation of t
     abstract type Equalizing  <: Conditioner end # Equalizing  (individual scaling)
     abstract type Shrinking   <: Conditioner end # Geodesic Shrinking
 ```
-Abstract types for **Conditioners**. Those are the elemntary pipes
+Abstract types for **Conditioners**. Those are the elementary pipes
 to build a [Pipeline](@ref). The available conditioners are
 
 - Tikhonov regularization (diagonal loading)
 - Recentering by whitening with or w/o dimensionality reduction
 - Compressing by global scaling
 - Equalizing by individual scaling
-- Shrinking by moving along geodesics towards the identity matrix
+- Shrinking by moving along geodesics with the identity matrix
 """
 =#
 
@@ -59,9 +59,9 @@ transform the set such as
 
  ``P_j+αI, \\ j=1,...,k``,
 
-where ``I`` is the identity matrix and ``α`` is a non-negative number.
+where ``I`` is the identity matrix and ``α`` is a non-negative scalar.
 
-This conditoner structure has two fields: 
+This conditioner structure has two fields: 
 
 - `.α`, which is written in the structure when it is fitted to some data.
 
@@ -136,7 +136,7 @@ the barycenter ``G``, like [`tsWeights`](@ref)
 does for computing the barycenter used for tangent space mapping.
 If the classes are balanced, the weighting has no effect.
 
-This conditoner structure has the following fields:
+This conditioner structure has the following fields:
 
 - `.metric`, of type  [Metric](https://marco-congedo.github.io/PosDefManifold.jl/dev/MainModule/#Metric::Enumerated-type-1), is to be specified by the user. It is the metric that will be adopted to compute the class means and the distances to the mean. default: `PosDefManifold.Euclidean`.
 
@@ -354,7 +354,7 @@ mutable struct Shrink <: Conditioner
 Mutable structure of the **geodesic shrinking** conditioner. 
 
 Given a set of points ``𝐏`` in the manifold of positive-definite matrices,
-this conditioner moves all points towards the identity matrix ``I`` along geodesics
+this conditioner moves all points towards or away from the identity matrix ``I`` along geodesics
 on the manifold defined in accordance to the specified `metric`. This effectively defines a ball
 centered at ``I``.
 
@@ -460,6 +460,7 @@ A pipeline holds a sequence of conditioners learned
 and (optionally) applied using [`fit!`](@ref). It can be 
 subsequently applied on other data as it has been learnt 
 using the [`transform!`](@ref) function.
+
 All `fit!` methods return a pipeline.
 
 Pipelines comprising a single conditioner are allowed.
@@ -491,7 +492,7 @@ macro pipeline(args...)
 
 Create a [`Pipeline`](@ref) chaining the provided expressions.
 
-As an example, the sintax is:
+As an example, the syntax is:
 
 ```julia
 p = @pipeline Recenter() → Compress → Shrink(Fisher; threaded=false)
@@ -956,7 +957,7 @@ includes(pipeline, Shrink) # true
 
 includes(pipeline, Shrink()) # true
 
-# same type, althoug a different instance
+# same type, although a different instance
 includes(pipeline, Shrink(Fisher; radius=0.1)) # true
 
 includes(pipeline, Compress) # false
@@ -975,6 +976,7 @@ function dim(pipeline::Pipeline)
 ```
 Return the dimension determined by a fitted [`Recenter`](@ref) pre-conditioner 
 if the `pipeline` comprises such a pre-conditioner, `nothing` otherwise. 
+    
 This is used to adapt pipelines - see the documentation of the [`fit!`](@ref)
 function for ENLR machine learning models for an example.
 
@@ -983,7 +985,7 @@ function for ENLR machine learning models for an example.
 using PosDefManifoldML, PosDefManifold
 
 pipeline = @→ Recenter(; eVar=0.9) → Shrink()
-dim(pipeline) # return false, as it is not fitted
+dim(pipeline) # return `nothing`, as it is not fitted
 
 P = randP(10, 5)
 p = fit!(P, pipeline)

src/conditioners_lowlevel.jl

@@ -282,16 +282,15 @@ end
 
 # TRAINING:
 # Return 2-tuple (𝐏, γ), where 𝐏 is the set of input matrices 𝐏 shrinked in an open ball with given `radius` r 
-# according to the given `metric`, and γ ∈ (0, 1] is the the shrinking parameter. 
+# according to the given `metric`, and γ ∈ (0, 1] is the shrinking parameter. 
 # The radius r englobes the most distant point of set 𝐏 if `refpoint`=:max, the mean eccentricity
 # of the points in 𝐏 if `refpoint`=:mean. This letter option means that the points are shrinked so that r 
 # is equal to sqrt(1/n * mean(norm(P) for P in 𝐏).
-# The shrinking is done moving, for each matric P_k in the set, along the gedesic relying I to P_k,
-# acording to the given metric. The distance according to the given metric is evaluated for all matrices
+# The shrinking is done moving, for each matrix P_k in the set, along the gedesic relying I to P_k,
+# according to the given metric. The distance according to the given metric is evaluated for all matrices
 # in 𝐏 and γ is computed so as to set the maximum or mean eccentricity equal to r + ϵ,
 # where ϵ is the `epsilon` kwarg.
-# If the maximum or mean eccentricity is already in the ball of radius r, no shrinking is carried out 
-# and return 2-tuple (𝐏, 1).
+# The ball containing 𝐏 may also be increased (the opposite of shrinking).
 # For all metrics γ = (r*√n) / (δ(P, I) + ϵ). The defaults are r = 0.02 and ϵ = 0
 
 # Proof (for three metrics, see PosDefManifold.jl for available metrics supporting a geodesic equation):
@@ -363,10 +362,10 @@ function shrink!(metric::PosDefManifold.Metric, 𝐏::PosDefManifold.ℍVector,
             d = threaded ? Folds.sum(funcLC, 𝐋)/length(𝐋) : sum(funcLC, 𝐋)/length(𝐋)
         end
 
-        if d ≥ radius # d is the maximal or mean logCholesky distance squared to I
+        # if d ≥ radius # d is the maximal or mean logCholesky distance squared to I
             γ = (radius * sqrt(n)) / (sqrt(d) + epsilon)
             0 ≤ γ || throw(ArgumentError("Shrink conditioner with $(metric) metric; shrinkage parameter γ≤0"))
-            γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
+            # γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
 
             # move on the logCholesky geodesic relying I to 𝐏[i] with step-size γ
             if transform
@@ -380,28 +379,28 @@ function shrink!(metric::PosDefManifold.Metric, 𝐏::PosDefManifold.ℍVector,
                     end
                 end
             end # if transform
-        else
-            verbose && @warn "Shrink conditioner with method $(metric): no shrinking is necessary" d radius
-        end
+        # else
+            # verbose && @warn "Shrink conditioner with method $(metric): no shrinking is necessary" d radius
+        # end
 
     elseif metric == PosDefManifold.Fisher
         #eltype(𝐏[1]) <: Complex && throw(ArgumentError("The metric Fisher for function shrink! and shrink is defined only for real matrices"))
         𝛌, 𝐔 = evds(𝐏; threaded)
 
-        # here the eigenvalues could be normalized to costant variance
+        # here the eigenvalues could be normalized to constant variance
 
         funcF(λ) = sqrt(sum(x -> real(log(x))^2, λ)) # norm
         if refpoint==:max
             d = threaded ? Folds.maximum(funcF, 𝛌) : maximum(funcF, 𝛌)
         else
-            d = threaded ? Folds.sum(funcF, 𝛌)/length(𝛌) : sum(funcF, 𝛌)/length(𝛌) # average eccentricity
+            d = threaded ? Folds.sum(funcF, 𝛌)/length(𝛌) : sum(funcF, 𝛌)/length(𝛌) # average norm
         end
 
-        if d ≥ radius # γ is the Fisher distance to I
-            γ = (radius * sqrt(n)) / (d + epsilon)
+        # if d ≥ radius 
+            γ = (radius * sqrt(n)) / (d + epsilon) # γ is the Fisher distance to I
             #            println("γ, d ", γ, " ", d)
             0 ≤ γ || throw(ArgumentError("Shrink conditioner with $(metric) metric; computed shrinkage parameter γ≤0"))
-            γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
+            # γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
 
             # move on the Fisher geodesic relying I to 𝐏[i] with step-size γ
             # and re-recenter the eigenvalues if recenter=true         
@@ -442,9 +441,9 @@ function shrink!(metric::PosDefManifold.Metric, 𝐏::PosDefManifold.ℍVector,
                     end
                 end
             end # if transform
-        else
-            verbose && @warn "Shrink conditioner with method $(metric): no shrinking was necessary" d radius
-        end
+        # else
+            # verbose && @warn "Shrink conditioner with method $(metric): no shrinking was necessary" d radius
+        # end
 
     else # all other supported metrics
         func(P) = distance(metric, P) # distance
@@ -454,10 +453,10 @@ function shrink!(metric::PosDefManifold.Metric, 𝐏::PosDefManifold.ℍVector,
             d = threaded ? Folds.sum(func, 𝐏)/length(𝐏) : sum(func, 𝐏)/length(𝐏)
         end
 
-        if d ≥ radius # γ is the metric distance to I
+        # if d ≥ radius # γ is the metric distance to I
             γ = (radius * sqrt(n)) / (d + epsilon)
             0 ≤ γ || throw(ArgumentError("Shrink conditioner with $(metric) metric; computed shrinkage parameter γ≤0"))
-            γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
+            #γ < 1 || @warn "Shrink conditioner with $(metric) metric; shrinkage parameter γ≥1" γ radius
 
             if transform
                 #0 < γ ≤ 1 || throw(ArgumentError("shrink! or shrink function with $(metric) metric; shrinkage parameter γ ∉(0, 1]"))
@@ -473,9 +472,9 @@ function shrink!(metric::PosDefManifold.Metric, 𝐏::PosDefManifold.ℍVector,
                     end
                 end
             end # if transform
-        else
-            verbose && @warn "Shrink conditioner with metric $(metric): no shrinking was necessary" d radius
-        end
+        # else
+            # verbose && @warn "Shrink conditioner with metric $(metric): no shrinking was necessary" d radius
+        # end
     end
 
     return (𝐏, γ, m, sd)