better link interface and docs (#34)

guilhermebodin · web-flow · commit 2a1170310e39 · 2019-11-28T13:58:50.000-03:00
diff --git a/docs/src/manual.md b/docs/src/manual.md
@@ -1,3 +1,21 @@
 # Manual
 
-TODO
+## Links
+
+### Types of links
+
+The abstract type `Link` subsumes any type of link that can be expressed.
+
+```@docs
+ScoreDrivenModels.IdentityLink
+ScoreDrivenModels.LogLink
+```
+
+### Link functions
+
+```@docs
+ScoreDrivenModels.link
+ScoreDrivenModels.unlink
+ScoreDrivenModels.jacobian_link
+```
+
diff --git a/src/distributions/README.md b/src/distributions/README.md
@@ -7,8 +7,8 @@ Each distribution must have the following methods:
 * fisher information
 * log likelihood
 * link interface
-    * param_to_param_tilde
-    * param_tilde_to_param
+    * link
+    * unlink
     * jacobian_link
 * update_dist
 * num_params
diff --git a/src/distributions/beta.jl b/src/distributions/beta.jl
@@ -34,22 +34,22 @@ function log_likelihood(::Type{Beta}, y::Vector{T}, param::Vector{Vector{T}}, n:
 end
 
 # Links
-function param_to_param_tilde(::Type{Beta}, param::Vector{T}) where T 
+function link(::Type{Beta}, param::Vector{T}) where T 
     return [
-        param_to_param_tilde(ExponentialLink, param[1], zero(T));
-        param_to_param_tilde(ExponentialLink, param[2], zero(T))
+        link(LogLink, param[1], zero(T));
+        link(LogLink, param[2], zero(T))
     ]
 end
-function param_tilde_to_param(::Type{Beta}, param_tilde::Vector{T}) where T 
+function unlink(::Type{Beta}, param_tilde::Vector{T}) where T 
     return [
-        param_tilde_to_param(ExponentialLink, param_tilde[1], zero(T));
-        param_tilde_to_param(ExponentialLink, param_tilde[2], zero(T))
+        unlink(LogLink, param_tilde[1], zero(T));
+        unlink(LogLink, param_tilde[2], zero(T))
     ]
 end
 function jacobian_link(::Type{Beta}, param_tilde::Vector{T}) where T 
     return Diagonal([
-        jacobian_link(ExponentialLink, param_tilde[1], zero(T));
-        jacobian_link(ExponentialLink, param_tilde[2], zero(T))
+        jacobian_link(LogLink, param_tilde[1], zero(T));
+        jacobian_link(LogLink, param_tilde[2], zero(T))
     ])
 end
 
diff --git a/src/distributions/common_interface.jl b/src/distributions/common_interface.jl
@@ -17,11 +17,11 @@ end
 function fisher_information(D::Type{<:Distribution}, param::Vector{T}) where T
     return error("fisher_information not implemented for $D distribution")
 end
-function param_to_param_tilde(D::Type{<:Distribution}, param::Vector{T}) where T 
-    return error("param_to_param_tilde not implemented for $D distribution")
+function link(D::Type{<:Distribution}, param::Vector{T}) where T 
+    return error("link not implemented for $D distribution")
 end
-function param_tilde_to_param(D::Type{<:Distribution}, param_tilde::Vector{T}) where T 
-    return error("param_tilde_to_param not implemented for $D distribution")
+function unlink(D::Type{<:Distribution}, param_tilde::Vector{T}) where T 
+    return error("unlink not implemented for $D distribution")
 end
 function jacobian_link(D::Type{<:Distribution}, param_tilde::Vector{T}) where T 
     return error("jacobian_link not implemented for $D distribution")
diff --git a/src/distributions/gamma.jl b/src/distributions/gamma.jl
@@ -31,22 +31,22 @@ function log_likelihood(::Type{Gamma}, y::Vector{T}, param::Vector{Vector{T}}, n
 end
 
 # Links
-function param_to_param_tilde(::Type{Gamma}, param::Vector{T}) where T 
+function link(::Type{Gamma}, param::Vector{T}) where T 
     return [
-        param_to_param_tilde(ExponentialLink, param[1], zero(T));
-        param_to_param_tilde(ExponentialLink, param[2], zero(T))
+        link(LogLink, param[1], zero(T));
+        link(LogLink, param[2], zero(T))
     ]
 end
-function param_tilde_to_param(::Type{Gamma}, param_tilde::Vector{T}) where T 
+function unlink(::Type{Gamma}, param_tilde::Vector{T}) where T 
     return [
-        param_tilde_to_param(ExponentialLink, param_tilde[1], zero(T));
-        param_tilde_to_param(ExponentialLink, param_tilde[2], zero(T))
+        unlink(LogLink, param_tilde[1], zero(T));
+        unlink(LogLink, param_tilde[2], zero(T))
     ]
 end
 function jacobian_link(::Type{Gamma}, param_tilde::Vector{T}) where T 
     return Diagonal([
-        jacobian_link(ExponentialLink, param_tilde[1], zero(T));
-        jacobian_link(ExponentialLink, param_tilde[2], zero(T))
+        jacobian_link(LogLink, param_tilde[1], zero(T));
+        jacobian_link(LogLink, param_tilde[2], zero(T))
     ])
 end
 
diff --git a/src/distributions/log_normal.jl b/src/distributions/log_normal.jl
@@ -5,7 +5,7 @@ parametrized in \\mu and \\sigma^2
 function score(y::T, ::Type{LogNormal}, param::Vector{T}) where T
     return [
         (log(y) - param[1])/param[2] ;
-        -0.5/param[2] + 0.5*(log(y) - param[1])^2/param[2]^2
+        -(0.5/param[2]) * (1 - ((log(y) - param[1])^2)/param[2])
     ]
 end
 
@@ -28,22 +28,22 @@ function log_likelihood(::Type{LogNormal}, y::Vector{T}, param::Vector{Vector{T}
 end
 
 # Links
-function param_to_param_tilde(::Type{LogNormal}, param::Vector{T}) where T 
+function link(::Type{LogNormal}, param::Vector{T}) where T 
     return [
-        param_to_param_tilde(IdentityLink, param[1]);
-        param_to_param_tilde(ExponentialLink, param[2], zero(T))
+        link(IdentityLink, param[1]);
+        link(LogLink, param[2], zero(T))
     ]
 end
-function param_tilde_to_param(::Type{LogNormal}, param_tilde::Vector{T}) where T 
+function unlink(::Type{LogNormal}, param_tilde::Vector{T}) where T 
     return [
-        param_tilde_to_param(IdentityLink, param_tilde[1]);
-        param_tilde_to_param(ExponentialLink, param_tilde[2], zero(T))
+        unlink(IdentityLink, param_tilde[1]);
+        unlink(LogLink, param_tilde[2], zero(T))
     ]
 end
 function jacobian_link(::Type{LogNormal}, param_tilde::Vector{T}) where T 
     return Diagonal([
         jacobian_link(IdentityLink, param_tilde[1]);
-        jacobian_link(ExponentialLink, param_tilde[2], zero(T))
+        jacobian_link(LogLink, param_tilde[2], zero(T))
     ])
 end
 
diff --git a/src/distributions/normal.jl b/src/distributions/normal.jl
@@ -31,22 +31,22 @@ function log_likelihood(::Type{Normal}, y::Vector{T}, param::Vector{Vector{T}},
 end
 
 # Links
-function param_to_param_tilde(::Type{Normal}, param::Vector{T}) where T 
+function link(::Type{Normal}, param::Vector{T}) where T 
     return [
-        param_to_param_tilde(IdentityLink, param[1]);
-        param_to_param_tilde(ExponentialLink, param[2], zero(T))
+        link(IdentityLink, param[1]);
+        link(LogLink, param[2], zero(T))
     ]
 end
-function param_tilde_to_param(::Type{Normal}, param_tilde::Vector{T}) where T 
+function unlink(::Type{Normal}, param_tilde::Vector{T}) where T 
     return [
-        param_tilde_to_param(IdentityLink, param_tilde[1]);
-        param_tilde_to_param(ExponentialLink, param_tilde[2], zero(T))
+        unlink(IdentityLink, param_tilde[1]);
+        unlink(LogLink, param_tilde[2], zero(T))
     ]
 end
 function jacobian_link(::Type{Normal}, param_tilde::Vector{T}) where T 
     return Diagonal([
         jacobian_link(IdentityLink, param_tilde[1]);
-        jacobian_link(ExponentialLink, param_tilde[2], zero(T))
+        jacobian_link(LogLink, param_tilde[2], zero(T))
     ])
 end
 
diff --git a/src/distributions/poisson.jl b/src/distributions/poisson.jl
@@ -24,9 +24,9 @@ function log_likelihood(::Type{Poisson}, y::Vector{Int}, param::Vector{Vector{T}
 end
 
 # Links
-param_to_param_tilde(::Type{Poisson}, param::Vector{T}) where T = param_to_param_tilde.(ExponentialLink, param, zero(T))
-param_tilde_to_param(::Type{Poisson}, param_tilde::Vector{T}) where T = param_tilde_to_param.(ExponentialLink, param_tilde, zero(T))
-jacobian_link(::Type{Poisson}, param_tilde::Vector{T}) where T = Diagonal(jacobian_link.(ExponentialLink, param_tilde, zero(T)))
+link(::Type{Poisson}, param::Vector{T}) where T = link.(LogLink, param, zero(T))
+unlink(::Type{Poisson}, param_tilde::Vector{T}) where T = unlink.(LogLink, param_tilde, zero(T))
+jacobian_link(::Type{Poisson}, param_tilde::Vector{T}) where T = Diagonal(jacobian_link.(LogLink, param_tilde, zero(T)))
 
 # utils
 function update_dist(::Type{Poisson}, param::Vector{T}) where T
diff --git a/src/distributions/weibull.jl b/src/distributions/weibull.jl
@@ -28,22 +28,22 @@ function log_likelihood(::Type{Weibull}, y::Vector{T}, param::Vector{Vector{T}},
 end
 
 # Links
-function param_to_param_tilde(::Type{Weibull}, param::Vector{T}) where T 
+function link(::Type{Weibull}, param::Vector{T}) where T 
     return [
-        param_to_param_tilde(ExponentialLink, param[1], zero(T));
-        param_to_param_tilde(ExponentialLink, param[2], zero(T))
+        link(LogLink, param[1], zero(T));
+        link(LogLink, param[2], zero(T))
     ]
 end
-function param_tilde_to_param(::Type{Weibull}, param_tilde::Vector{T}) where T 
+function unlink(::Type{Weibull}, param_tilde::Vector{T}) where T 
     return [
-        param_tilde_to_param(ExponentialLink, param_tilde[1], zero(T));
-        param_tilde_to_param(ExponentialLink, param_tilde[2], zero(T))
+        unlink(LogLink, param_tilde[1], zero(T));
+        unlink(LogLink, param_tilde[2], zero(T))
     ]
 end
 function jacobian_link(::Type{Weibull}, param_tilde::Vector{T}) where T 
     return Diagonal([
-        jacobian_link(ExponentialLink, param_tilde[1], zero(T));
-        jacobian_link(ExponentialLink, param_tilde[2], zero(T))
+        jacobian_link(LogLink, param_tilde[1], zero(T));
+        jacobian_link(LogLink, param_tilde[2], zero(T))
     ])
 end
 
diff --git a/src/gas/simulate.jl b/src/gas/simulate.jl
@@ -27,22 +27,22 @@ function simulate(gas::GAS{D, T}, n::Int, initial_param_tilde::Vector{Vector{T}}
     # initial_values  
     for i in 1:biggest_lag
         param_tilde[i] = initial_param_tilde[i]
-        param[i] = param_tilde_to_param(D, initial_param_tilde[i])
+        param[i] = unlink(D, initial_param_tilde[i])
         # Sample
-        updated_dist = update_dist(D, param_tilde_to_param(D, param_tilde[i]))
+        updated_dist = update_dist(D, unlink(D, param_tilde[i]))
         serie[i] = sample_observation(updated_dist)
         scores_tilde[i] = score_tilde(serie[i], D, param[i], param_tilde[i], gas.scaling)
     end
     
     update_param_tilde!(param_tilde, gas.ω, gas.A, gas.B, scores_tilde, biggest_lag)
-    updated_dist = update_dist(D, param_tilde_to_param(D, param_tilde[biggest_lag + 1]))
+    updated_dist = update_dist(D, unlink(D, param_tilde[biggest_lag + 1]))
     serie[biggest_lag + 1] = sample_observation(updated_dist)
 
     for i in biggest_lag + 1:n-1
         # update step
         univariate_score_driven_update!(param, param_tilde, scores_tilde, serie[i], gas, i)
         # Sample from the updated distribution
-        updated_dist = update_dist(D, param_tilde_to_param(D, param_tilde[i + 1]))
+        updated_dist = update_dist(D, unlink(D, param_tilde[i + 1]))
         serie[i + 1] = sample_observation(updated_dist)
     end
     update_param!(param, param_tilde, D, n)
diff --git a/src/gas/univariate_score_driven_recursion.jl b/src/gas/univariate_score_driven_recursion.jl
@@ -22,7 +22,7 @@ function score_driven_recursion(gas::GAS{D, T}, observations::Vector{T}, initial
     # initial_values  
     for i in 1:biggest_lag
         param_tilde[i] = initial_param_tilde[i]
-        param[i] = param_tilde_to_param(D, initial_param_tilde[i])
+        param[i] = unlink(D, initial_param_tilde[i])
         scores_tilde[i] = score_tilde(observations[i], D, param[i], param_tilde[i], gas.scaling)
     end
     
@@ -49,7 +49,7 @@ function univariate_score_driven_update!(param::Vector{Vector{T}}, param_tilde::
 end
 
 function update_param!(param::Vector{Vector{T}}, param_tilde::Vector{Vector{T}}, D::Type{<:Distribution}, i::Int) where T
-    param[i] = param_tilde_to_param(D, param_tilde[i])
+    param[i] = unlink(D, param_tilde[i])
     # Some treatments 
     NaN2zero!(param[i])
     big_threshold!(param[i], 1e10)
diff --git a/src/link_functions.jl b/src/link_functions.jl
@@ -1,20 +1,51 @@
 abstract type Link end
 
+"""
+    link(args...)
+
+The link function is a map that brings a parameter ``f`` in a subspace ``\\mathcal{F} \\subset \\mathbb{R}`` to ``\\mathbb{R}``.
+"""
+function link end
+
+"""
+    unlink(args...)
+
+The unlink function is the inverse map of [`link`](@ref link). It brings ``\\tilde f`` in ``\\mathbb{R}`` to the subspace ``\\mathcal{F} \\subset \\mathbb{R}``.
+"""
+function unlink end
+
+"""
+    jacobian_link(args...)
+
+Evaluates the derivative of the [`link`](@ref link) with respect to the parameter ``f``.
+"""
+function jacobian_link end
+
+"""
+    IdentityLink <: Link
+
+Define the map ``\\ \\tilde f = f`` where ``\\ \\tilde f \\in \\mathbb{R}`` and ``\\ \\tilde f \\in \\mathbb{R}``
+"""
 struct IdentityLink <: Link end
 
-param_to_param_tilde(::Type{IdentityLink}, param::T) where T = param
-param_tilde_to_param(::Type{IdentityLink}, param_tilde::T) where T = param_tilde
+link(::Type{IdentityLink}, param::T) where T = param
+unlink(::Type{IdentityLink}, param_tilde::T) where T = param_tilde
 jacobian_link(::Type{IdentityLink}, param_tilde::T) where T = one(T)
 
-struct ExponentialLink <: Link end
+"""
+    LogLink <: Link
+
+Define the map ``\\ \\tilde f = \\ln(f - a)`` where ``\\ f \\in [a, \\infty), a \\in \\mathbb{R}`` and ``\\ \\tilde f \\in \\mathbb{R}``
+"""
+struct LogLink <: Link end
 
-param_to_param_tilde(::Type{ExponentialLink}, param::T, lower_bound::T) where T = log(param - lower_bound)
-param_tilde_to_param(::Type{ExponentialLink}, param_tilde::T, lower_bound::T) where T = exp(param_tilde) + lower_bound
-jacobian_link(::Type{ExponentialLink}, param_tilde::T, lower_bound::T) where T = 1/(param_tilde - lower_bound)
+link(::Type{LogLink}, param::T, lower_bound::T) where T = log(param - lower_bound)
+unlink(::Type{LogLink}, param_tilde::T, lower_bound::T) where T = exp(param_tilde) + lower_bound
+jacobian_link(::Type{LogLink}, param_tilde::T, lower_bound::T) where T = 1/(param_tilde - lower_bound)
 
 struct LogitLink <: Link end
 
 const LINKS = [
     IdentityLink;
-    ExponentialLink
+    LogLink
 ]
diff --git a/test/test_links.jl b/test/test_links.jl
@@ -5,11 +5,11 @@
     rtol = 1e-7
 
     link = SDM.IdentityLink
-    @test SDM.param_to_param_tilde(link, SDM.param_tilde_to_param(link, x)) ≈ x atol = atol rtol = rtol
+    @test SDM.link(link, SDM.unlink(link, x)) ≈ x atol = atol rtol = rtol
 
-    link = SDM.ExponentialLink
+    link = SDM.LogLink
     lb = 1.0
-    @test SDM.param_to_param_tilde(link, SDM.param_tilde_to_param(link, x, lb), lb) ≈ x atol = atol rtol = rtol
+    @test SDM.link(link, SDM.unlink(link, x, lb), lb) ≈ x atol = atol rtol = rtol
     lb = 0.0
-    @test SDM.param_to_param_tilde(link, SDM.param_tilde_to_param(link, x, lb), lb) ≈ x atol = atol rtol = rtol
+    @test SDM.link(link, SDM.unlink(link, x, lb), lb) ≈ x atol = atol rtol = rtol
 end
