Approx.fpt.density: Approximating First-Passage-Time Densities

Description Usage Arguments Details Value Author(s) References See Also Examples

Description

Approx.fpt.density computes values of the approximate first-passage-time (f.p.t.) density, for conditioned and unconditioned problems.

For the unconditioned case, values of the approximate densities for f.p.t. problems conditioned to suitable values of the initial distribution are also calculated.

Usage

1
2
3
4
Approx.fpt.density(dp, t0, T, id, S, env = NULL, variableStep = TRUE, 
                   from.t0 = FALSE, to.T = FALSE, r = 4000, zeroSlope = 0.01, 
                   p0.tol = 8, k = 3, m = 100, n = 250, p = 0.2, alpha = 1, 
                   skip = TRUE, tol = 0.001, it.max)               

Arguments

dp

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

t0, T

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

id

a numerical value specifying a fixed initial value of the process in the time instant specified in the t0 argument (for a conditioned f.p.t. problem), or a four-component list specifying the initial distribution of the process (for an unconditioned f.p.t. problem). In the last case the first component is the R mathematical expression of the density as a character string, the second one is a label to denote the distribution in the reports generated by the report method, the third one is the label to denote the distribution for LaTeX, and the four one is a label to denote the distribution in the graphs generated by the plot method.

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. It is copied into a temporary environment for evaluating the mathematical expressions in the dp object and S.

variableStep

a logical value indicating whether a variable integration step is used.

from.t0

a logical value indicating whether the approximation should be calculated from the lower end of the interval considered, t0.

to.T

a logical value indicating whether the approximation should be calculated to the upper end of the interval considered, T.

r

number of points at which the FPTL function is evaluated.

zeroSlope

maximum slope required to consider that a growing function is constant.

p0.tol

controls where the First-Passage-Time Location function begins to increase significantly.

k

controls whether the First-Passage-Time Location function decreases very slowly.

m

Number of equally spaced values to select from the specified initial distribution in the case of an unconditioned f.p.t. problem.

n

Number of points used to determine the integration step in subintervals [t[i]*, tmax[i]^+] i=1,..., m, from interesting instants provided by the FPTL function.

p

Ratio of n used to determine the integration step in subintervals [tmax[i]^+, t[i+1]*], i=1,..., m, [t0, t[1]*] and [tmax[m]^+, T].

alpha

Parameter used to determine the integration step in subintervals [tmax[i]^+, t[i+1]*], i=1,..., m, [t0, t[1]*] and [tmax[m]^+, T], in order to reduce the computational cost of approximating the f.p.t. density function in those cases where t[i+1]* - tmax[i]^+ >> tmax[i]^- - t[i]*, for some i, t[1]* - t0 >> tmax[1]^- - t[1]* or T - tmax[m]^+ >> tmax[m]^- - t[m]*, respectively.

skip

a logical value indicating whether the intervals at which the FPTL function is near zero could be avoided.

tol

If the cumulative integral of the approximation is greater than or equal to 1 - tol the algorithm is stopped.

it.max

If the number of iterations required for the approximation process is greater than it.max, the function asks for permission to continue. Defaults to 50000 for a conditioned f.p.t. problem, and 1000000 for an unconditioned f.p.t. problem.

Details

For an unconditioned f.p.t. problem, this function allows to compute directly the approximate f.p.t. density from an object of class “diffproc”. In contrast to the approximation of a conditioned f.p.t. density by using the Approx.cfpt.density function, in this case it is not necessary for users to make previous calls to the functions FPTL and summary.FPTL.

For a diffusion process {X(t), t0 ≤ t ≤ T} with non-degenerate initial distribution the unconditioned f.p.t. variable, through a continuous boundary S(t), is defined as

T = Inf{ t ≥ t0 : X(t) > S(t)} ,

if X(t0) < S(t0), and

T = Inf{ t ≥ t0 : X(t) < S(t)} ,

if X(t0) > S(t0).

and its density function can be obtained by means of the numerical integration, in the range of variation of X(t0), of the corresponding f.p.t. densities conditioned to values of X(t0), weighted by the initial density function.

For each conditioned problem related to an unconditioned f.p.t. problem, the Approx.fpt.density function makes internal calls to FPTL and summary.fptl functions, in order to localize each conditioned f.p.t. variable, according to the zeroSlope, p0.tol and k arguments. Then, the function makes a internall call to Integration.Steps function, in order to determine the suitable subintervals and integration steps to be used to approximate the unconditioned f.p.t. density and conditioned f.p.t. densities according to the variableStep, from.t0, to.T, n, p and alpha arguments.

From this information, a suitable sequence of time instants in [t0, T] for the approximation of the f.p.t. densities is available. For each time instant t in such sequence, the Approx.fpt.density function computes the value of the f.p.t. density conditioned to m values of the initial distribution (equally spaced in its range of variation), and then it computes the value of the unconditioned f.p.t density.

For the approximation of each conditioned f.p.t density, the numerical procedure proposed by Buonocore et al. (1987), based on the composite trapezoid method, has been implemented. This method has also been used in the numerical integration for obtaining the unconditioned f.p.t. density.

The mathematical expression of the boundary S should be a function of t and may include the argument t0, the name x0, to refer to an initial value of the process, and the parameters specified in the env argument. The 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.

By default the function does not compute the approximate f.p.t. density from the time instant t0, but from a more suitable time instant provided by the First-Passage-Time Location (FPTL) function. It also uses a variable integration step.

If skip = TRUE, for each subinterval in which it could be possible to avoid calculating all the conditioned f.p.t. densities, the function checks the value of the approximate unconditioned f.p.t. density at the lower end of such subinterval. If it is almost 0, the approximate unconditioned f.p.t. density calculation is avoided in the subinterval, and it continues from the upper end of the subinterval considering a zero value of the approximate unconditioned f.p.t. density.

Similarly, if to.T = FALSE, the function checks the cumulative value of the integral for each upper end of the subintervals for which it is not possible to avoid the application of the numerical algorithm for each conditioned problem. If it is greater than or equal to 1 - tol, the approximation procedure is stopped. In any case, the procedure is stopped at the upper end of the last subinterval, and if the cumulative value of the integral is less than 1 - tol the function issues a warning.

Value

The Approx.fpt.density function computes and returns an object of class “fpt.density”. This object is a three-component list:

x

a sequence of suitable time instants in [t0, T] according to the arguments in the function call.

y

the approximate f.p.t. density function values on the x sequence for the unconditioned or conditioned problem at hand.

y.x0

NULL for a conditioned f.p.t. problem or a matrix with the values, by columns, of the approximate f.p.t. densities conditioned to each considered value x0 selected from the initial distribution for an unconditioned f.p.t. problem.


It also includes six additional attributes:

Call the unevaluated function call, substituting each object of length 1 (referred
by name in call) by its value.
Steps matrix of subintervals and integration steps to consider for computing the
approximate f.p.t. density.
cumIntegral vector of the values of the cumulative integral of the approximation for
each subinterval considered.
skips a list that contains, for each subinterval, the indexes of the initial values
for which the calculation of the approximate conditioned f.p.t. densities
has been avoided.
CPUTime matrix of user and system times, by columns, required to approximate
the density for each subinterval considered, by rows.
summary.fptl the object of class “summary.fptl” that results in the internal calls to the
summary.fptl function which is used as sfptl argument in the internal
call to the Integration.Steps function.

x is the vector result of the concatenation of the sequences of equally spaced values in the suitable subintervals determined by the Integration.Steps function.

Author(s)

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

References

Buonocore, A., Nobile, A.G. and Ricciardi, L.M. (1987) A new integral equation for the evaluation of first-passage-time probability densities. Adv. Appl. Probab., 19, 784–800.

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.

is.fpt.density to test for objects of class “fpt.density”.

print.fpt.density to show objects of class “fpt.density”.

report.fpt.density to generate a report.

plot.fpt.density for graphical display.

FPTL to evaluate the FPTL function and create objects of class “fptl”.

summary.fptl to locate the f.p.t. variable and create objects of class “summary.fptl”.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
## Continuing the diffproc(.) example:

## Making an efficient approximation of the f.p.t. density
## in the case of a conditioned f.p.t. problem. (optimal 
## variable integration steps and small computational cost)
yyy.cp <- Approx.fpt.density(dp = Lognormal, t0 = 0, T = 18, id = 1, S = 
                        "4.5 + 4*t^2 + 7*t*sqrt(t)*sin(6*sqrt(t))", 
                        env = list(m = 0.48, sigma = 0.07))
yyy.cp

## Not run: 
## Making a less efficient approximation of the f.p.t. density 
## (optimal fixed integration step but high computational cost related to 
##  the efficient approximation)
yyy1.cp <- Approx.fpt.density(dp = Lognormal, t0 = 0, T = 18, id = 1, S = 
                        "4.5 + 4*t^2 + 7*t*sqrt(t)*sin(6*sqrt(t))", 
                        env = list(m = 0.48, sigma = 0.07), 
                        variableStep = FALSE, from.t0 = TRUE, to.T = 
                        TRUE, skip = FALSE)
yyy1.cp

## Making an efficient approximation of the f.p.t. density 
## in the case of an unconditioned f.p.t. problem.
yyy.ucp <- Approx.fpt.density(dp = Lognormal, t0 = 0, T = 18, id = 
                list("dlnorm(x,-0.005,0.1)", "Lambda(-0.005,0.1)", 
                "\\Lambda(-0.005,0.1)", "Lognormal(-0.005,0.1)"),
                S = "4.5 + 4*t^2 + 7*t*sqrt(t)*sin(6*sqrt(t))", 
                env = list(m = 0.48, sigma = 0.07), m=25)                 
yyy.ucp
## End(Not run)

fptdApprox documentation built on Feb. 29, 2020, 1:07 a.m.