diff --git a/src/arma.jl b/src/arma.jl index 31216ce1..1bf3cc0a 100644 --- a/src/arma.jl +++ b/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 diff --git a/src/markov/mc_tools.jl b/src/markov/mc_tools.jl index 869076aa..9fca5b91 100644 --- a/src/markov/mc_tools.jl +++ b/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))) diff --git a/src/modeltools/utility.jl b/src/modeltools/utility.jl index 797ba7e0..19f26c0a 100644 --- a/src/modeltools/utility.jl +++ b/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 diff --git a/src/util.jl b/src/util.jl index 4cf568e7..f64dc31c 100644 --- a/src/util.jl +++ b/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 diff --git a/src/zeros.jl b/src/zeros.jl index 9c4f08c0..5b14b48e 100644 --- a/src/zeros.jl +++ b/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++