setModel: Basic Description of Stochastic Differential Equations (SDE)

In yuima: The YUIMA Project Package for SDEs

Basic Description of Stochastic Differential Equations (SDE)

Description

'setModel' gives a description of stochastic differential equation with or without jumps of the following form:

dXt = a(t,Xt, alpha)dt + b(t,Xt,beta)dWt + c(t,Xt,gamma)dZt, X0=x0

All functions relying on the yuima package will get as much information as possible from the different slots of the yuima-class structure without replicating the same code twice. If there are missing pieces of information, some default values can be assumed.

Usage

setModel(drift = NULL, diffusion = NULL, hurst = 0.5, jump.coeff = NULL,
measure = list(), measure.type = character(), state.variable = "x",
jump.variable = "z", time.variable = "t", solve.variable, xinit,
model.class = NULL, observed.variable = NULL, unobserved.variable = NULL
)

Arguments

drift	a vector of expressions (the default value is 0 when drift=NULL).
diffusion	a matrix of expressions (the default value is 0 when diffusion=NULL).
hurst	the Hurst parameter of the gaussian noise. If h=0.5, the default, the process is Wiener otherwise it is fractional Brownian motion with that precise value of the Hurst index. Can be set to NA for further specification.
jump.coeff	a matrix of expressions for the jump component.
measure	Levy measure for jump variables.
measure.type	type specification for Levy measures.
state.variable	a vector of names of the state variables in the drift and diffusion coefficients.
jump.variable	a vector of names of the jump variables in the jump coefficient.
time.variable	the name of the time variable.
solve.variable	a vector of names of the variables in the left-hand-side of the equations in the model; solve.variable equals state.variable as long as we have no exogenous variable other than statistical parameters in the coefficients (drift and diffusion).
xinit	a vector of numbers identifying the initial value of the solve.variable.
model.class	a character string identifying the class of the model. Allowed values are "model", "stateSpaceModel", "linearStateSpaceModel" or NULL. If NULL, the class is inferred from the model specification.
observed.variable	a vector of names of the observed variables. See 'Details'.
unobserved.variable	a vector of names of the unobserved variables. See 'Details'.

Details

Please refer to the vignettes and examples or to the yuimadocs package.

The return class depends on the given model.class argument. If model.class is "model", the returned value is an object of class yuima.model-class. If model.class is "stateSpaceModel", the returned value is an object of class yuima.state_space_model-class. If model.class is "linearStateSpaceModel", the returned value is an object of class yuima.linear_state_space_model-class. If model.class is NULL, the class is inferred automatically. If neither observed.variable nor unobserved.variable is specified, a yuima.model object is returned. Otherwise, the linearity of the drift term is checked, and a yuima.state_space_model or yuima.linear_state_space_model object is returned accordingly.

If model.class is "stateSpaceModel" or "linearStateSpaceModel", only unobserved variables can be contained in expressions for the drift coefficients and the user must specify either observed.variable or unobserved.variable. If both are specified, they must be mutually exclusive, and their union must equal the state variables. In addition, if model.class is "linearStateSpaceModel", the drift coefficients must be linear in the unobserved variables.

An object of yuima.model-class contains several slots:

drift:

an R expression specifying the drift coefficient (a vector).

diffusion:

an R expression specifying the diffusion coefficient (a matrix).

jump.coeff:

the coefficient of the jump term.

measure:

the Levy measure of the driving Levy process.

measure.type:

specifies the type of the measure, such as CP, code, or density. See below.

parameter:

a short name for "parameters". It is an object of model.parameter-class, which is a list of vectors of names of parameters belonging to the single components of the model (drift, diffusion, jump, and measure), the names of common parameters, and the names of all parameters. For more details, see model.parameter-class documentation page.

solve.variable:

a vector of variable names, each element corresponding to the name of the solution variable (left-hand side) of each equation in the model, in the corresponding order.

state.variable:

identifies the state variables in the R expression. By default, it is assumed to be x.

jump.variable:

the variable for the jump coefficient. By default, it is assumed to be z.

time:

the time variable. By default, it is assumed to be t.

solve.variable:

used to identify the solution variables in the R expression, i.e., the variable with respect to which the stochastic differential equation has to be solved. By default, it is assumed to be x; otherwise, the user can choose any other model specification.

noise.number:

denotes the number of sources of noise, currently only for the Gaussian part.

equation.number:

denotes the dimension of the stochastic differential equation.

dimension:

the dimensions of the parameters in the parameter slot.

xinit:

denotes the initial value of the stochastic differential equation.

The yuima.model-class structure assumes that the user either uses the default names for state.variable, jump.variable, solution.variable, and time.variable, or specifies their own names. All the remaining terms in the R expressions are considered as parameters and identified accordingly in the parameter slot.

An object of yuima.state_space_model-class extends an object of yuima.model-class with the following slot:

is.observed:

a logical vector of length equal to the number of state variables, indicating whether each state variable is observed.

An object of yuima.linear_state_space_model-class extends an object of yuima.state_space_model-class with the following slots:

drift.slope:

a list of expressions.

drift.intercept:

a list of expressions.

In the case of yuima.linear_state_space_model-class, the drift term of the model is assumed to be affine in the unobserved variables, i.e., drift = drift.slope * unobserved.variable + drift.intercept.

Value

model

The class of the returned object depends on the value of model.class. If model.class is specified, the returned value is an object of the specified class. If model.class is NULL, the returned value is inferred from the model specification. See Details for more information.

Note

There may be missing information in the model description. Please contribute with suggestions and fixings.

Author(s)

The YUIMA Project Team

Examples

# Ex 1. (One-dimensional diffusion process)
# To describe
# dXt = -3*Xt*dt + (1/(1+Xt^2+t))dWt,
# we set
mod1 <- setModel(drift = "-3*x", diffusion = "1/(1+x^2+t)", solve.variable = c("x"))
# We may omit the solve.variable; then the default variable x is used
mod1 <- setModel(drift = "-3*x", diffusion = "1/(1+x^2+t)")
# Look at the model structure by
str(mod1)

# Ex 2. (Two-dimensional diffusion process with three factors)
# To describe
# dX1t = -3*X1t*dt + dW1t +X2t*dW3t,
# dX2t = -(X1t + 2*X2t)*dt + X1t*dW1t + 3*dW2t,
# we set the drift coefficient
a <- c("-3*x1","-x1-2*x2")
# and also the diffusion coefficient
b <- matrix(c("1","x1","0","3","x2","0"),2,3)
# Then set
mod2 <- setModel(drift = a, diffusion = b, solve.variable = c("x1","x2"))
# Look at the model structure by
str(mod2)
# The noise.number is automatically determined by inputting the diffusion matrix expression.
# If the dimensions of the drift differs from the number of the rows of the diffusion, 
# the error message is returned.

# Ex 3. (Process with jumps (compound Poisson process))
# To describe
# dXt = -theta*Xt*dt+sigma*dZt
mod3 <- setModel(drift=c("-theta*x"), diffusion="sigma",
jump.coeff="1", measure=list(intensity="1", df=list("dnorm(z, 0, 1)")),
measure.type="CP", solve.variable="x")
# Look at the model structure by
str(mod3)

# Ex 4. (Process with jumps (stable process))
# To describe
# dXt = -theta*Xt*dt+sigma*dZt
mod4 <- setModel(drift=c("-theta*x"), diffusion="sigma",
jump.coeff="1", measure.type="code",measure=list(df="rstable(z,1,0,1,0)"), solve.variable="x")
# Look at the model structure by
str(mod4)
# See rng about other candidate of Levy noises.

# Ex 5. (Two-dimensional stochastic differenatial equation with Levy noise)
# To describe
# dX1t = (1 - X1t - X2t)*dt+dZ1t 
# dX2t = (0.5 - X1t - X2t)*dt+dZ2t
beta<-c(.5,.5)
mu<-c(0,0)
Lambda<-matrix(c(1,0,0,1),2,2)
mod5 <- setModel(drift=c("1 - x1-x2",".5 - x1-x2"), 
solve.variable=c("x1","x2"), jump.coeff=Lambda, measure.type="code",
measure=list(df="rNIG(z, alpha, beta, delta0, mu, Lambda)"))
# Look at the model structure by
str(mod5)

# Ex 6. (Process with fractional Gaussian noise)
# dYt = 3*Yt*dt + dWt^h
mod6 <- setModel(drift="3*y", diffusion=1, hurst=0.3, solve.variable=c("y"))
# Look at the model structure by
str(mod6)

# Ex 7. (Linear state-space model)
# dXt = -theta*Xt*dt + sigma*dZt (unobserved)
# Yt = Xt + dVt (observed)
drift <- c("-theta*x", "1")
diffusion <- matrix(c("sigma", "0", "0", "1"), 2, 2)
mod7 <- setModel(
  drift=drift, diffusion=diffusion, solve.variable=c("x", "y"),
  state.variable=c("x", "y"), observed.variable="y"
)

yuima documentation built on April 16, 2025, 5:12 p.m.