Functions

SB{TR<:Real, TS<:Real, TO<:Real, AV<:AbstractVector, AM<:AbstractMatrix, AAM<:AbstractMatrix}

Defines a discrete multivariate distribution SB using a latent Gaussian process.

For now, the latent covarience matrix is definied by the parameters of a Matern covariance function :

C(h) = σ² * 2^(1-ν) / Γ(ν) * (sqrt(2*ν) * h / ρ)^ν * K_ν(sqrt(2*ν) * h / ρ)

The marginal Bernoulli probabilities are given by λ.

Arguments

• range::Real : Value of ρ, rate of decay. Represents the spatial scale of the process.
• sill::Real: Value of variance σ² - values different than 1 are deprecated.
• order::Real : Value of ν, shape of the Matérn covariance function; recall that a value of 0.5 is the exponential covariance function.
• λ::AbstractVector : Vector of marginal rain probabilities. Expected to be of length D the number of spatial components.
• h::AbstractMatrix : Matrix of distances between all spatial locations. Expected size D*D.
• ΣU::AbstractMatrix : Covariance matrix contructed from the covariance function and distance matrix.

Returns

SB(range,sill,order,λ,h,ΣU)

TODO : make a structure SB(covfun(θ...), h, ΣU) instead for more flexibility where.

SB(range, sill, order, λ, h)

Constructor for a discrete multivariate distribution SB. The constructor uses the distance matrix to compute the covariance matrix.

fit_mle(d::SB, Y::AbstractArray{<:Real}[,wp::AbstractMatrix{<:Real}, w::AbstractVector{<:Real}];  solver, m = 1000*length(d), return_sol = false, solkwargs...)

Return the (weighted) MLE for the distribution d::SB.

• solver choice of solver
• solkwargs any keywords arguments that can be put inside the solve functions e.g. fit_mle(d, Y; maxiters = 2)
• w not necessary, used for using weighted loglikelihood instead of loglikelihood
• wp not technically necessary, used for using pairwise loglikelihood instead of true loglikelihood.

logpdf(d::SB, y::AbstractVector{<:Real}[, wp::AbstractMatrix{<:Real}]; m=length(d) * 100, return_error=false,,a=zeros(length(d)), b=zeros(length(d)), finite_bounds=zeros(length(d)),   zerosvec=fill(0, length(d)))
- Computes logpdf(d,y) with model d.
- If argument `wp` is used, pairwise log-likelihood is used instead of full log-likelihood, with weights matrix `wp`.
- `a`, `b` , `finite_bounds`, `zerosvec` preallocations can only be used for full log-likelihood, as well as `return_error`.

pdf(d::SB, y::AbstractVector{<:Real}; m=length(d) * 100, return_error=false,a=zeros(length(d)), b=zeros(length(d)), finite_bounds=zeros(length(d)),   zerosvec=fill(0, length(d)))

Computes pdf(d::SB, y).

It is recommended by MvNormalCDF.jl to use m= length(d)100. Using m=length(d)100 can be a good starting point.

Possible uses :

• pdf(d,y::AbstractVector{<:Real})
• pdf(d,y,m=3000) ... etc

Arguments

• d::SB : Spatial Bernoulli model
• y::AbstractVector{<:Real} : one realisation of the model.

Arguments that have a default value

• m::Int: number of samples in QMC computation
• return_error::Bool : Should the error of QMC computation be given, or not ?
• a, b , finite_bounds, zerosvec : pre-allocated vectors for the integral boundaries. When using n times the pdf function, it allows one single reused allocation instead of n allocations.

rand!(rng::AbstractRNG, d::SB, x::AbstractVector{T})

Definition of random sampling of d::SB. As SB <: MultivariateDistribution, Distributions.jl provides a generic fallback for other rand calls.

Possible uses

• In-place sampling rand!(rng::AbstractRNG, d::SB, x::AbstractVector{T}) where x is pre-allocated and the random generator is fixed
• In-place sampling rand!(d::SB, x::AbstractVector{T}) where x is pre-allocated
• Sampling x= rand(rng::AbstractRNG, d::SB) where the random generator is fixed
• Sampling x= rand( d::SB)
• Sampling x= rand( d::SB, n::Int) for n realisations.
• Sampling x= rand(rng::AbstractRNG, d::SB, n::Int) for n realisations.

expkernel(h;range,sill)

Redefines the exponential kernel C(h) = σ²exp(-h/ρ)

Arguments

• h::AbstractMatrix or h::Real: Values of distance at which the covariance must be computed.
• range::Real : Value of ρ, rate of decay. Represents the spatial scale of the process.
• sill::Real: Value of variance σ²

fit_mle_vfast(d::SB, Y::AbstractArray{<:Real}[,wp::AbstractMatrix{<:Real}, w::AbstractVector{<:Real}];  solver, return_sol = false, solkwargs...)

Return the (weighted) MLE for the distribution d::SB using the very fast approximation.

loglikelihood_vfast(d::SB, Y::AbstractArray{<:Real}[, wp::AbstractMatrix{<:Real}, w::AbstractVector{<:Real}])

Computes the pairwise (possibly weighted) loglikelihood using the approximation of [Tsay (2023)](https://doi.org/10.1080/03610918.2021.1884718)

• w not necessary, used for using weighted loglikelihood instead of loglikelihood.
• wp is necessary, used for using pairwise loglikelihood.

Arguments

• d::SB
• Y :: AbstractArray{<:Real} with length(d) lines, each column is a realization of d.
• w::AbstractVector{<:Real} is an optional vector of weights to compute weighted log-likelihood as sum(w_i llh(yi)), used in EM algorithms for example.
• wp::AbstractMatrix{<:Real}: weights matrix

matern(h; range, sill, order)

Redefines the Matern covariance kernel to ensure the use of the BesselK.jl package.

Arguments

• h::AbstractMatrix or h::Real: Values of distance at which the covariance must be computed.
• range::Real : Value of ρ, rate of decay. Represents the spatial scale of the process.
• sill::Real: Value of variance σ²
• order::Real : Value of ν, shape of the Matérn covariance function

 norm_cdf_2d_vfast(x₁, x₂, ρ)

Computes the bivariate standard normal cumulative distribution function (CDF) Φ₂(x₁, x₂, ρ) ,

where (X₁,X₂) ~ N(0, [ 1 ρ ρ 1 ])

Arguments

• x₁::Real
• x₂::Real
• ρ::Real : correlation value between -1 and 1

Returns

Φ₂(x₁, x₂, ρ) = P(X₁<x₁,X₂<x₂)

Source

Converted from https://github.com/david-cortes/approxcdf https://github.com/david-cortes/approxcdf/blob/master/src/other.cpp

loglikelihood(d::SB, Y::AbstractArray{<:Real}[, wp::AbstractMatrix{<:Real}, w::AbstractVector{<:Real}]; m=length(d) * 500)

Computes the (possibly pairwise) (possibly weighted) loglikelihood

• w not necessary, used for using weighted loglikelihood instead of loglikelihood.
• wp not technically necessary, used for using pairwise loglikelihood instead of true loglikelihood.

Arguments

• d::SB
• Y :: AbstractArray{<:Real} with length(d) lines, each column is a realization of d.
• m::Int: number of samples in QMC computation
• w::AbstractVector{<:Real} is an optional vector of weights to compute weighted log-likelihood as sum(w_i llh(yi)), used in EM algorithms for example.
• wp::AbstractMatrix{<:Real}: weights matrix in the pairwise case.