Add examples to docs

src/arma.jl

@@ -139,6 +139,27 @@ and the inverse Fourier transform.
 - `arma::ARMA`: Instance of `ARMA` type
 - `;num_autocov::Integer(16)` : The number of autocovariances to calculate
 
+##### Returns
+
+- `acov::Vector{Float64}`: `acov[j]` is the autocovariance between two elements with a lag j.
+
+##### Examples
+
+```julia
+using Plots
+
+# AR(2) process
+ar = ARMA([0.8 , 0.5], Vector{Float64}(),1)
+ar_acov = autocovariance(ar)
+plot(1:length(ar_acov),ar_acov,color=:blue, lw=2, marker=:circle, markersize=3, label = "autocovariance")
+
+# ARMA(2,2) process
+lp = ARMA([0.8, 0.5], [0.7, 0.3], 0.5)
+lp_acov = autocovariance(lp, num_autocov = 50)
+plot(1:length(lp_acov),lp_acov,color=:blue, lw=2, marker=:circle, markersize=3, label = "autocovariance")
+
+```
+
 """
 function autocovariance(arma::ARMA; num_autocov::Integer=16)
     # Compute the autocovariance function associated with ARMA process arma
@@ -163,6 +184,21 @@ Get the impulse response corresponding to our model.
 - `psi::Vector{Float64}`: `psi[j]` is the response at lag j of the impulse
   response. We take `psi[1]` as unity.
 
+##### Examples
+
+```julia
+using Plots
+
+lp1 = ARMA([0.5],[0.5],1)
+response1 = impulse_response(lp1)
+plot(1:length(response1),response1,color=:blue, lw=2, marker=:circle, markersize=3)
+
+lp2 = ARMA([0.8, 0.5], [0.7, 0.3], 0.5)
+response2 = impulse_response(lp2,impulse_length = 50)
+plot(1:length(response2),response2,color=:blue, lw=2, marker=:circle, markersize=3)
+
+```
+
 """
 function impulse_response(arma::ARMA; impulse_length=30)
     # Compute the impulse response function associated with ARMA process arma

src/markov/mc_tools.jl

@@ -27,6 +27,19 @@ state transitions.
 
 - `p::AbstractMatrix` : The transition matrix. Must be square, all elements must be nonnegative, and all rows must sum to unity.
 - `state_values::AbstractVector` : Vector containing the values associated with the states.
+
+##### Examples
+
+```julia
+# Without labelling states
+p1 = [1 0 0; 0 1 0; 0 0 1]
+mc1 = MarkovChain(p1)
+
+#Including labels for states
+p2 = [0.3 0.7; 0.25 0.75]
+states = ["unemployed", "employed"]
+mc2 = MarkovChain(p2, states)
+```
 """
 mutable struct MarkovChain{T, TM<:AbstractMatrix{T}, TV<:AbstractVector}
     p::TM # valid stochastic matrix
@@ -187,6 +200,20 @@ Indicate whether the Markov chain `mc` is irreducible.
 
 - `::Bool`
 
+##### Examples
+
+```jlcon
+julia> P1 = [0 0.5 0.5; 0.3 0 0.7; 0 0 1]
+
+julia> is_irreducible(MarkovChain(P1))
+false
+
+julia> P2 = [0 1 0; 0 0 1; 1 0 0]
+
+julia> is_irreducible(MarkovChain(P2))
+true
+```
+
 """
 is_irreducible(mc::MarkovChain) =  is_strongly_connected(DiGraph(mc.p))
 
@@ -201,6 +228,20 @@ Indicate whether the Markov chain `mc` is aperiodic.
 
 - `::Bool`
 
+##### Examples
+
+```jlcon
+julia> P1 = [1 0; 0 1]
+
+julia> is_aperiodic(MarkovChain(P1))
+true
+
+julia> P1 = [0 1 0 0; 1 0 0 0; 0 0 0 1; 0 0 1 0]
+
+julia> is_aperiodic(MarkovChain(P1))
+false
+```
+
 """
 is_aperiodic(mc::MarkovChain) = period(mc) == 1
 
@@ -360,6 +401,23 @@ The resulting vector has the state values of `mc` as elements.
 
 - `X::Vector` : Vector containing the sample path, with length
   ts_length
+
+### Examples
+
+```jlcon
+julia> P = [0.3 0.7; 0.75 0.25];
+
+julia> mc = MarkovChain(P,["Umemployed", "Employed"]);
+
+julia> simulate(mc,5,init=2)
+5-element Array{String,1}:
+ "Employed"
+ "Umemployed"
+ "Employed"
+ "Umemployed"
+ "Employed"
+```
+
 """
 function simulate(mc::MarkovChain, ts_length::Int;
                   init::Int=rand(1:n_states(mc)))
@@ -384,6 +442,26 @@ same as the type of the state values of `mc`
     - vector: cycle through the elements, applying each as an
       initial condition until all columns have an initial condition
       (allows for more columns than initial conditions)
+
+### Examples
+
+```jlcon
+julia> using Plots
+
+julia> P = [0 0.5 0.5; 0.5 0 0.5; 0.5 0.5 0];
+
+julia> mc = MarkovChain(P);
+
+julia> X = zeros(15,4);
+
+julia> simulate!(X,mc,init = 1);
+
+julia> series = plot(1:15, X[:,1], lw=2, ylim = (0,4), label = "Sample path 1", size=(800,550))
+
+julia> for i in 2:4
+           plot!(1:15,X[:,i], lw=2, label = "Sample path \$i")
+       end
+```
 """
 function simulate!(X::Union{AbstractVector,AbstractMatrix},
                    mc::MarkovChain; init=rand(1:n_states(mc), size(X, 2)))
@@ -414,6 +492,19 @@ The resulting vector has the indices of the state values of `mc` as elements.
 
 - `X::Vector{Int}` : Vector containing the sample path, with length
   ts_length
+
+### Examples
+
+```jlcon
+julia> P = [0.3 0.7; 0.75 0.25];
+
+julia> mc = MarkovChain(P,["Umemployed", "Employed"]);
+
+julia> X = simulate_indices(mc,10,init=1);
+
+julia> plot(1:10,X,lw=2,label="Sample Path",ylim=[1,2])
+```
+
 """
 function simulate_indices(mc::MarkovChain, ts_length::Int;
                           init::Int=rand(1:n_states(mc)))

src/modeltools/utility.jl

@@ -15,6 +15,27 @@ Additionally, this code assumes that if c < 1e-10 then
 
 u(c) = log(1e-10) + 1e10*(c - 1e-10)
 
+##### Examples
+
+```jlcon
+julia> u1 = LogUtility()
+
+julia> u1(10.)
+2.302585092994046
+
+julia> u1.([1.e-15, 1.e15])
+2-element Array{Float64,1}:
+ -24.025840929940458
+  34.538776394910684
+
+julia> u2 = LogUtility(10)
+
+julia> u2.([10., 1.e-15])
+2-element Array{Float64,1}:
+   23.02585092994046
+ -240.25840929940458
+```
+
 """
 struct LogUtility <: AbstractUtility
     ξ::Float64

src/util.jl

@@ -28,6 +28,33 @@ ckron(arrays::AbstractArray...) = reduce(kron, arrays)
 
 Repeatedly apply kronecker products to the arrays. Equilvalent to
 `reduce(kron, arrays)`
+
+##### Example
+
+```jlcon
+julia> A = [10 16 11; 5 3 7]
+
+julia> B = B = [0.25 0.5; 0.15 0.4]
+
+julia> C = [120 100; 375 240; 540 650]
+
+julia> ckron(A,B,C)
+12×12 Array{Float64,2}:
+  300.0    250.0   600.0   500.0   480.0   …   330.0    275.0   660.0   550.0
+  937.5    600.0  1875.0  1200.0  1500.0      1031.25   660.0  2062.5  1320.0
+ 1350.0   1625.0  2700.0  3250.0  2160.0      1485.0   1787.5  2970.0  3575.0
+  180.0    150.0   480.0   400.0   288.0       198.0    165.0   528.0   440.0
+  562.5    360.0  1500.0   960.0   900.0       618.75   396.0  1650.0  1056.0
+  810.0    975.0  2160.0  2600.0  1296.0   …   891.0   1072.5  2376.0  2860.0
+  150.0    125.0   300.0   250.0    90.0       210.0    175.0   420.0   350.0
+  468.75   300.0   937.5   600.0   281.25      656.25   420.0  1312.5   840.0
+  675.0    812.5  1350.0  1625.0   405.0       945.0   1137.5  1890.0  2275.0
+   90.0     75.0   240.0   200.0    54.0       126.0    105.0   336.0   280.0
+  281.25   180.0   750.0   480.0   168.75  …   393.75   252.0  1050.0   672.0
+  405.0    487.5  1080.0  1300.0   243.0       567.0    682.5  1512.0  1820.0
+
+```
+
 """
 ckron
 
@@ -191,12 +218,13 @@ along each dimension can be obtained by `simplex_grid(m, n) / n`.
 
 ##### Examples
 
->>> simplex_grid(3, 4)
-
+```jlcon
+julia> simplex_grid(3,4)
 3×15 Array{Int64,2}:
  0  0  0  0  0  1  1  1  1  2  2  2  3  3  4
  0  1  2  3  4  0  1  2  3  0  1  2  0  1  0
  4  3  2  1  0  3  2  1  0  2  1  0  1  0  0
+```
 
 ##### References
 
@@ -354,6 +382,23 @@ array fits within the range of `T`; a sufficient condition for it is
 # Returns
 
 - `idx::T`: Ranking of `a`.
+
+##### Examples
+
+```jlcon
+julia> k_array_rank([2,3,5,8])
+42
+
+julia> typeof(k_array_rank([2,3,5,8]))
+Int64
+
+julia> typeof(k_array_rank(Int128,[2,3,5,8]))
+Int128
+
+julia> typeof(k_array_rank(BigInt,[2,3,5,8]))
+BigInt
+```
+
 """
 function k_array_rank(T::Type{<:Integer}, a::Vector{<:Integer})
     if T != BigInt

src/zeros.jl

@@ -114,6 +114,18 @@ sequentially with any bracketing pairs that are found.
 - `x1b::Vector{T}`: `Vector` of lower borders of bracketing intervals
 - `x2b::Vector{T}`: `Vector` of upper borders of bracketing intervals
 
+##### Examples
+
+```julia
+x1a, x2a = divide_bracket(sin, -100., 100.)
+
+function poly(x)
+    return x^2 - 2x + 1
+end
+x1b, x2b = divide_bracket(poly, -1., 1., 100)
+
+```
+
 ##### References
 
 This is `zbrack` from Numerical Recepies Recepies in C++