fptdApprox (version 2.5)

FPTL: First-Passage-Time Location Function

Description

FPTL computes values of the First-Passage-Time Location (FPTL) function of a diffusion process for a continuous boundary.

is.fptl tests if its argument is an object of class “fptl”.

print.fptl shows an object of class “fptl”.

Usage

FPTL(dp, t0, T, x0, S, env = NULL, n = 4000)
is.fptl(obj)
# S3 method for fptl
print(x, ...)

Value

The function FPTL computes and returns an object of class “fptl”. It is a two-component list:

x

a sequence of n values from t0 to T.

y

the corresponding values of the FPTL function for the x sequence.

It also includes three additional attributes:

Call	the unevaluated function call, substituting each name in this call for its value when
	the latter has length 1.
dp	the object used as dp argument in the function call.
vars	NULL or a list containing the values of names in the function call for those names
	with values of length greater than 1.

is.fptl returns TRUE or FALSE depending on whether its argument is an object of class “fptl” or not.

Since n is usually large, the print.fptl function does not display an object of class “fptl” as a list, but in its ‘basic’

structure instead. However, each component can be displayed separately in the usual way.

Arguments

dp

an object of class “diffproc” defining a family of diffusion processes.

obj

an R object to be tested.

x

an object of class “fptl”, a result of a call to this function.

t0, T

lower and upper limits of the considered time interval. Must be finite.

x0

fixed initial value of process in the time instant specified in the t0 argument.

S

numerical value of a constant boundary or character string with the mathematical expression of a time-dependent boundary.

env

a named list of objects of numeric or character type specifying the values of names which occur in the mathematical expressions in objects dp and S, or of names which occur in the specification of the previous values. Defaults to NULL, interpreted as an empty list.

n

number of points at which the FPTL function is evaluated.

...

additional arguments potentially passed (currently none is considered).

Author

Patricia Román-Román, Juan J. Serrano-Pérez and Francisco Torres-Ruiz.

Details

The FPTL function for the problem of the first-passage-time of a diffusion process \(\{X(t), t_0 \leq t \leq T \}\), conditioned to \(X(t_0) = x_0\), through a continuous boundary \(S(t)\) is defined as $$FPTL(t) = \left\{ \begin{array}{lll} P[ X(t)>S(t) \, | \, X(t_0)=x_0] = 1 - F(S(t),t \, | \, x_0,t_0) & & if \ x_0 < S(t_0) \\[7pt] P[ X(t)<S(t) \, | \, X(t_0)=x_0] = F(S(t),t \, | \, x_0,t_0) & & if \ x_0 > S(t_0) \end{array} \right. ,$$ where \(F(x,t|y,s)\) is the transition probability distribution function of the process.

Initially, the FPTL function is evaluated at a sequence of n equally spaced values from t0 to T. Then the FPTL function makes an internal call to the growth.intervals function in order to study the growth of the evaluation vector. Finally, the FPTL function is evaluated at a more adequate sequence of values from t0 to T according to the abovementioned study.

The mathematical expression of the boundary S should be a function of \(t\) and may include arguments t0, x0 and the parameters specified in the env argument. The FPTL function checks if the mathematical expression shows syntax errors and if R can compute its symbolic derivative with respect to \(t\).

The env argument is a list of tagged values in name = value form with name other than \(x\), \(t\), \(y\) and \(s\). To name the expression of a function \(h(u)\) as a character string we can use `h(u)` = value if we want to show its dependence on \(u\), or h = value otherwise.

The env argument is copied into a temporary environment for evaluating the mathematical expressions in objects dp and S. R looks for the objects not found into this temporary environment in the parent.frame() environment.

References

Román, P., Serrano, J. J., Torres, F. (2008) First-passage-time location function: Application to determine first-passage-time densities in diffusion processes. Comput. Stat. Data Anal., 52, 4132--4146.

P. Román-Román, J.J. Serrano-Pérez, F. Torres-Ruiz. (2012) An R package for an efficient approximation of first-passage-time densities for diffusion processes based on the FPTL function. Applied Mathematics and Computation, 218, 8408--8428.

P. Román-Román, J.J. Serrano-Pérez, F. Torres-Ruiz. (2014) More general problems on first-passage times for diffusion processes: A new version of the fptdApprox R package. Applied Mathematics and Computation, 244, 432--446.

See Also

diffproc about creation of class “diffproc” objects.

summary.fptl for summaries and plot.fptl for graphical display.

Examples

## Continuing the diffproc(.) examples:
Lognormal <- diffproc(c("m*x","sigma^2*x^2","dnorm((log(x)-(log(y)+(m-sigma^2/2)*(t-s)))/(sigma*sqrt(t-s)),0,1)/(sigma*sqrt(t-s)*x)", "plnorm(x,log(y)+(m-sigma^2/2)*(t-s),sigma*sqrt(t-s))"));
LognormalFEx <- diffproc(c("`h(t)`*x", "sigma^2*x^2", "dnorm((log(x)-(log(y)+`H(s,t)`-(sigma^2/2)*(t - s)))/(sigma*sqrt(t-s)),0,1)/(sigma*sqrt(t-s)*x)", "plnorm(x,log(y)+ `H(s,t)`-(sigma^2/2)*(t-s),sigma*sqrt(t-s))"))
## Specifying a boundary
b <- "4.5 + 4*t^2 + 7*t*sqrt(t)*sin(6*sqrt(t))"

## Computing FPTL functions and creating objects of class fptl
y <- FPTL(dp = Lognormal, t0 = 0, T = 18, x0 = 1, S = b, env = list(m = 0.48,
          sigma = 0.07))
y

z <- FPTL(dp = LognormalFEx, t0 = 1, T = 10, x0 = 1, S = 15, env = list(sigma=0.1, 
          `h(t)` = "t/4", `H(s,t)` = "(t^2-s^2)/8"))
z
          
## Testing fptl objects
is.fptl(y)
is.fptl(z)