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, t_0.
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^*, t_{max,i}^+]
i=1, \ldots, m, from interesting instants provided by the FPTL function.
p
Ratio of n used to determine the integration step in subintervals
[t_{max,i}^+, t_{i+1}^*], i=1, \ldots, m, [t_0, t_1^*] and
[t_{max,m}^{+}, T].
alpha
Parameter used to determine the integration step in subintervals
[t_{max,i}^+, t_{i+1}^*], i=1, \ldots, m, [t_0, t_1^*] and
[t_{max,m}^{+}, T], in order to reduce the computational cost of approximating the f.p.t. density function
in those cases where t_{i+1}^* - t_{max,i}^+ >> t_{max,i}^{-} - \thinspace t_i^*,
for some i, t_1^* - t_0 >> t_{max,1}^{-} - \thinspace t_1^* or
T - t_{max,m}^+ >> t_{max,m}^{-} - \thinspace 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), t_0 \leq t \leq 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(t_0)} = \left\{
\begin{array}{lll}
Inf \ \{ t \geq t_0 \ : \ X(t) > S(t) \} & & if \ X(t_0) < S(t_0) \\[7pt]
Inf \ \{ t \geq t_0 \ : \ X(t) < S(t) \} & & if \ X(t_0) > S(t_0)
\end{array}
\right. ,
Its density function can be obtained by means of the numerical integration, in the range of variation of X(t_0),
of the corresponding f.p.t. densities conditioned to values of X(t_0), 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 [t_0, 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 t_0, 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 [t_0, \ 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 x_0 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
## 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 Nov. 2, 2023, 5:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| 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 |
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 |
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, |
to.T |
a logical value indicating whether the approximation should be calculated to the upper end of the
interval considered, |
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 |
p |
Ratio of n used to determine the integration step in subintervals
|
alpha |
Parameter used to determine the integration step in subintervals
|
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), t_0 \leq t \leq 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(t_0)} = \left\{
\begin{array}{lll}
Inf \ \{ t \geq t_0 \ : \ X(t) > S(t) \} & & if \ X(t_0) < S(t_0) \\[7pt]
Inf \ \{ t \geq t_0 \ : \ X(t) < S(t) \} & & if \ X(t_0) > S(t_0)
\end{array}
\right. ,
Its density function can be obtained by means of the numerical integration, in the range of variation of X(t_0),
of the corresponding f.p.t. densities conditioned to values of X(t_0), 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 [t_0, 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 t_0, 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 |
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 |
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
## 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)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.