Add table with distributions and docs for common interface (#90)

guilhermebodin · web-flow · commit a80f48074bfc · 2020-03-02T18:24:31.000-03:00
* add table with distributions and docs for common interface

* fix docs

* more appropriate notation
diff --git a/docs/src/manual.md b/docs/src/manual.md
@@ -18,7 +18,7 @@ All optimization methods can receive the following keyword arguments
 * `LB` - Lower bound of the initial points. Default is `0.0`.
 * `UB` - Upper bound of the initial points. Default is `0.6`.
 
-The [ScoreDrivenModels.IPNewton](@ref) allows users to perform box-constrained optimization.
+[`ScoreDrivenModels.IPNewton`](@ref) allows users to perform box-constrained optimization.
 
 ```@docs
 ScoreDrivenModels.NelderMead
@@ -77,19 +77,38 @@ forecasts or ensembles of scenarios. Point forecasts are obtained using the func
 and ensembles of scenarios are obtained using the function `simulate`.
 
 ```@docs
-forecast
 forecast_quantiles
 simulate
 ```
 
 ## ScoreDrivenModels distributions
 
-The following section presents how every distribution is parametrized, its score, fisher information
+The following section presents how every distribution is parametrized, its score, Fisher information
 and the `time_varying_params` map. Every distribution is originally imported to ScoreDrivenModels.jl
-from [Distributions.jl](https://github.com/JuliaStats/Distributions.jl).
+from [Distributions.jl](https://github.com/JuliaStats/Distributions.jl). Some distributions may have different
+parametrizations from [Distributions.jl](https://github.com/JuliaStats/Distributions.jl),
+this is handled internally.
+
+| Distribution | Identity scaling | Inverse and inverse square root scalings |
+| :------- |:---------------:|:--------------------:|
+|[`Beta`](@ref)| ✓ | ✓  |
+|[`BetaLocationScale`](@ref)| ✓ |  x  |
+|[`Chi`](@ref)| ✓ | ✓  |
+|[`Chisq`](@ref)| ✓ | ✓  |
+|[`Exponential`](@ref)| ✓ | ✓  |
+|[`Gamma`](@ref)| ✓ | ✓  |
+|[`LogitNormal`](@ref)| ✓ | ✓  |
+|[`LogNormal`](@ref)| ✓ | ✓  |
+|[`Normal`](@ref)| ✓ | ✓  |
+|[`Poisson`](@ref)| ✓ | ✓  |
+|[`TDist`](@ref)| ✓ | ✓  |
+|[`TDistLocationScale`](@ref)| ✓ | ✓  |
+|[`Weibull`](@ref)| ✓ |  x  |
+
 
 ```@docs
 ScoreDrivenModels.Beta
+ScoreDrivenModels.BetaLocationScale
 ScoreDrivenModels.Chi
 ScoreDrivenModels.Chisq
 ScoreDrivenModels.Exponential
@@ -108,21 +127,34 @@ ScoreDrivenModels.Weibull
 If you want to add a new distribution please feel free to make a pull request.
 
 Each distribution must have the following methods:
-* `score`
-* `fisher information`
-* `log likelihood`
-* `link interface`
-    * `link`
-    * `unlink`
-    * `jacobian_link`
-* `update_dist`
-* `num_params`
+* [`ScoreDrivenModels.score!`](@ref)
+* [`ScoreDrivenModels.fisher_information!`](@ref)
+* [`ScoreDrivenModels.log_likelihood`](@ref)
+* link interface
+    * [`ScoreDrivenModels.link!`](@ref)
+    * [`ScoreDrivenModels.unlink!`](@ref)
+    * [`ScoreDrivenModels.jacobian_link!`](@ref)
+* [`ScoreDrivenModels.update_dist`](@ref)
+* [`ScoreDrivenModels.params_sdm`](@ref)
+* [`ScoreDrivenModels.num_params`](@ref)
 
 The details of the new distribution must be documented following the example in
 [`Normal`](@ref) and added to the [ScoreDrivenModels distributions](@ref) section.
 The new implemented distribution must also be added to the constant `DISTS` and exported in the
 `distributions/common_interface.jl` file.
 
+```@docs
+ScoreDrivenModels.score!
+ScoreDrivenModels.fisher_information!
+ScoreDrivenModels.log_likelihood
+ScoreDrivenModels.link!
+ScoreDrivenModels.unlink!
+ScoreDrivenModels.jacobian_link!
+ScoreDrivenModels.update_dist
+ScoreDrivenModels.params_sdm
+ScoreDrivenModels.num_params
+```
+
 # Reference
 
 ```@docs
diff --git a/src/distributions/common_interface.jl b/src/distributions/common_interface.jl
@@ -29,6 +29,12 @@ export Beta,
     TDistLocationScale,
     Weibull
 
+"""
+    score!(score_til::Matrix{T}, y::T, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T
+
+Fill `score_til` with the score of distribution `D` with parameters `param[:, t]` considering
+the observation `y`.
+"""
 function score!(score_til::Matrix{T}, y::T, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T
     return error("score! not implemented for $D distribution")
 end
@@ -37,22 +43,48 @@ function score!(score_til::Matrix{T}, y::Int, D::Type{<:Distribution}, param::Ma
     return error("score! not implemented for $D distribution")
 end
 
+"""
+    fisher_information!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T
+
+Fill `aux` with the fisher information of distribution `D` with parameters `param[:, t]`.
+"""
 function fisher_information!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T
     return error("fisher_information! not implemented for $D distribution")
 end
 
+"""
+    log_likelihood(D::Type{<:Distribution}, y::Vector{T}, param::Matrix{T}, n::Int) where T
+
+Evaluate the log-likelihood of the distribution `D` considering the time-varying parameters
+`param` and the observations `y`.
+"""
 function log_likelihood(D::Type{<:Distribution}, y::Vector{T}, param::Matrix{T}, n::Int) where T
     return error("log_likelihood not implemented for $D distribution")
 end
 
+"""
+    link!(param_tilde::Matrix{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T 
+
+Fill `param_tilde` after the unlinking procedure of `param`.
+"""
 function link!(param_tilde::Matrix{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T 
     return error("link! not implemented for $D distribution")
 end
 
+"""
+    unlink!(param::Matrix{T}, D::Type{<:Distribution}, param_tilde::Matrix{T}, t::Int) where T 
+
+Fill `param` after the unlinking procedure of `param_tilde`.
+"""
 function unlink!(param::Matrix{T}, D::Type{<:Distribution}, param_tilde::Matrix{T}, t::Int) where T 
     return error("unlink! not implemented for $D distribution")
 end
 
+"""
+    jacobian_link!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T 
+
+Write the jacobian of the link map in `aux`.
+"""
 function jacobian_link!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T 
     return error("jacobian_link! not implemented for $D distribution")
 end
diff --git a/src/simulate.jl b/src/simulate.jl
@@ -1,16 +1,16 @@
 export simulate, forecast_quantiles
 
 """
-    simulate(series::Vector{T}, gas::Model{D, T}, N::Int, S::Int, kwargs...) where {D, T}
+    simulate(series::Vector{T}, gas::Model{D, T}, H::Int, S::Int, kwargs...) where {D, T}
 
-Generate scenarios for the future of a time series by updating the GAS recursion `N` times and taking
+Generate scenarios for the future of a time series by updating the GAS recursion `H` times and taking
 a sample of the distribution until it generates `S` scenarios.
 
 By default this method uses the `stationary_initial_params` method to perform the 
 score driven recursion. If you estimated the model with a different set of `initial_params`
 use them here to maintain the coherence of your estimation.
 """
-function simulate(series::Vector{T}, gas::Model{D, T}, N::Int, S::Int;
+function simulate(series::Vector{T}, gas::Model{D, T}, H::Int, S::Int;
                     initial_params::Matrix{T} = stationary_initial_params(gas)) where {D, T}
     # Filter params estimated on the time series
     params = score_driven_recursion(gas, series; initial_params = initial_params)
@@ -19,9 +19,9 @@ function simulate(series::Vector{T}, gas::Model{D, T}, N::Int, S::Int;
 
     params_simulation = params[(end - biggest_lag):(end - 1), :]
     # Create scenarios matrix
-    scenarios = Matrix{T}(undef, N, S)
+    scenarios = Matrix{T}(undef, H, S)
     for scenario in 1:S
-        sim, param = simulate_recursion(gas, N + biggest_lag + 1; initial_params = params_simulation)
+        sim, param = simulate_recursion(gas, H + biggest_lag + 1; initial_params = params_simulation)
         scenarios[:, scenario] = sim[biggest_lag + 2:end]
     end
 
@@ -30,9 +30,9 @@ end
 
 
 """
-    forecast_quantiles(series::Vector{T}, gas::Model{D, T}, N::Int; kwargs...) where {D, T}
+    forecast_quantiles(series::Vector{T}, gas::Model{D, T}, H::Int; kwargs...) where {D, T}
 
-Forecast quantiles for future values of a time series by updating the GAS recursion `N` times and 
+Forecast quantiles for future values of a time series by updating the GAS recursion `H` times and 
 using Monte Carlo method as in Blasques, Francisco, Siem Jan Koopman,
 Katarzyna Lasak and Andre Lucas (2016): "In-Sample Confidence Bounds and Out-of-Sample Forecast
 Bands for Time-Varying Parameters in Observation Driven Models", 
@@ -47,11 +47,11 @@ By default this method uses the `stationary_initial_params` method to perform th
 score driven recursion. If you estimated the model with a different set of `initial_params`
 use them here to maintain the coherence of your estimation.
 """
-function forecast_quantiles(series::Vector{T}, gas::Model{D, T}, N::Int;
+function forecast_quantiles(series::Vector{T}, gas::Model{D, T}, H::Int;
                       initial_params::Matrix{T} = stationary_initial_params(gas),
-                      quantiles::Vector{T} = T.([0.025, 0.5, 0.975]), S::Int = 1000) where {D, T}
+                      quantiles::Vector{T} = T.([0.025, 0.5, 0.975]), S::Int = 10_000) where {D, T}
 
-    scenarios = simulate(series, gas, N, S; initial_params = initial_params)
+    scenarios = simulate(series, gas, H, S; initial_params = initial_params)
 
     return get_quantiles(quantiles, scenarios)
 end
