# Approx.fpt.density: Approximating First-Passage-Time Densities In fptdApprox: Approximation of First-Passage-Time Densities for Diffusion Processes

 Approx.fpt.density R Documentation

## Approximating First-Passage-Time Densities

### 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

```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*] and [tmax[m]^+, T]. `alpha` Parameter used to determine the integration step in subintervals [tmax[i]^+, t[i+1]*], i=1,..., m, [t0, t*] 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* - t0 >> tmax^- - t* 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(S(t), X(t0)) = Inf {t ≥ t0 : X(t) > S(t)} , if X(t0) < S(t0), and T(S(t), X(t0)) = Inf {t ≥ t0 : X(t) < S(t)} , if X(t0) > S(t0).

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.

`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

```## 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 Aug. 22, 2022, 1:05 a.m.