BiMOL.density: Approximate the Transition Density of a Bivariate Diffusion...
In DiffusionRimp: Inference and Analysis for Diffusion Processes via Data Imputation and Method of Lines

Description Usage Arguments Value Interface Warning Note Author(s) References See Also Examples

BiMOL.density approximates the transition density of a bivariate diffusion on a lattice [xlims[1],xlims[2]] x [ylims[1],ylims[2]] x [s,t] with N x N spatial nodes and time discretization delt, via the method of lines. The method of lines approximates the solution of the Fokker-Planck equation by an N x N-dimensional system of ordinary differential equations (ODEs) evaluated on [s,t].

1
2
3

BiMOL.density(Xs, Ys, s , t , xlims, ylims, N, delt, mu1, mu2, 
             sig11, sig12, sig21, sig22, final.only = FALSE, 
             show.lattice = FALSE)

`Xs`	Starting/Initial X-coordinate for the diffusion process (see note [1] and warning [1]).
`Ys`	Starting/Initial Y-coordinate for the diffusion process (see note [1] and warning [1]).
`s`	Starting time for the diffusion process.
`t`	Value (>s) giving the terminal point for the transition horizon (the final time at which to evaluate the transition density).
`xlims`	X-limits for the spatial nodes of the lattice. These limits should be wide enough for the transition density to be negligibly small at the endpoints (see note [2]).
`ylims`	Y-limits for the spatial nodes of the lattice. These limits should be wide enough for the transition density to be negligibly small at the endpoints (see note [2]).
`N`	The number of nodes in each spatial domain at which to evaluate the transitional density. Increase `N` for more accurate approximations (see note [3] and warning [2]).
`mu1`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`mu2`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`sig11`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`sig12`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`sig21`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`sig22`	Optional (if drift and diffusion coefficients are already defined) arguments giving the drift and diffusion coefficients as text expressions (See Interface below).
`delt`	Step size for the time domain of the lattice (see note [4]).
`final.only`	Should the transition density on the entire lattice be returned (`FALSE`) or only the at the terminal point of the transition horizon `t` (`TRUE`). Default = `FALSE`.
`show.lattice`	If `=TRUE` (default) then the X-Y lattice is drawn and the initial value is indicated in red.

`density`	3D array containing the density approximation (matrix if `final.only = TRUE`).
`Xt`	Vector of X-coordinates at which approximation was carried out.
`Yt`	Vector of Y-coordinates at which approximation was carried out.
`time`	Vector of time nodes at which the approximation was evaluated.

BiMOL.density uses a function-input interface whereby the drift and diffusion components of the stochastic differential equation (SDE)

dX_t = mu_1(X_t, Y_t, t)dt+sigma_1(X_t, Y_t, t)dW_t^1

dY_t = mu_2(X_t, Y_t, t)dt+sigma_2(X_t, Y_t, t)dW_t^2,

are defined as R-functions in the current workspace. That is by defining the drift and diffusion components

mu1=function(X,Y,t){some expression i.t.o. X, Y and t}

mu2=function(X,Y,t){some expression i.t.o. X, Y and t}

sig11=function(X,Y,t){some expression i.t.o. X, Y and t}

sig22=function(X,Y,t){some expression i.t.o. X, Y and t}

further analysis may be conducted by calling the function BiMOL.density().

Warning [1]: Note that if the lattice is shifted, degeneracies may occur for certain drift/volatility specifications if the shifted lattice moves into non-nonsensical values of the drift/volatility functions' domains.

Warning [2]: Although increasing the spatial resolution of the lattice by increasing N improves approximations, instabilities will occur if delt is not sufficiently small. This tends to manifest as jagged/spiked solutions that oscillate between positive and negative values.

Note [1]: Although the spatial limits of the lattice is defined by the user using xlims, if the initial value Xs does not fall on one of the lattice nodes, then the lattice is shifted accordingly.

Note [2]: The approximation assumes that the entire density of the process falls on a finite interval. Thus the algorithm may breakdown for certain problems. Depending on the parameters of the process, the limits may be very far apart or near. Some experimentation may be required. Otherwise, set autofind = TRUE to find useful limits. Note also that larger N may be required for wider limits.

Note [3]: Increasing N will likely require smaller delt, thus increasing computation time. For some problems, slight increases in N will require much smaller delt.

Note [4]: delt is used as the step size for a 10(8)-th order Runge-Kutta method for solving the resulting system of ODEs. Note again the inter-play between N and delt (see note [3]).

Etienne A.D. Pienaar etiennead@gmail.com

Hamdi, S., Schiesser, W. E. and Griffiths, G. W. 2007 Method of lines. Scholarpedia, 2(7):2859. Revision #124335.

Feagin, T. 2007 A tenth-order Runge-Kutta method with error estimate. In Proceedings of the IAENG Conf. on Scientifc Computing.

MOL.passage, MOL.density.

#===============================================================================

 # For detailed notes and examples on how to use the BiMOL.density() function, see
 # the following vignette:

 RShowDoc('Part_2_Transition_Densities',type='html','DiffusionRimp')

#===============================================================================