| Title: | Brownian Motion Simulations |
|---|---|
| Description: | An implementation of algorithms for simulation of (multivariate) Brownian motion trajectories, including simple unconditional simulation, Brownian bridges, as well as layered and localised Brownian motion simulators. |
| Authors: | Louis Aslett [aut, cre], Murray Pollock [aut] |
| Maintainer: | Louis Aslett <[email protected]> |
| License: | GPL-2 |
| Version: | 0.4.0 |
| Built: | 2026-11-02 21:45:35 UTC |
| Source: | https://github.com/louisaslett/BrownianMotion |
Simulation of one- and multi-dimensional Brownian motion, including Brownian bridges, first passage times, and layers (spatial bounds which contain the path over an interval of time). Simulation is exact: each new point is drawn conditionally on everything already known about the path, including any layers.
A new path can be created with create_bm and is then extended
or filled in with sim. The object is updated in place, so calls
can be chained with pipes. Its contents can be extracted by indexing (see
[.BrownianMotion) and plotted
directly using plot.
Three types of layer are available (see layers), which follow
(broadly) the approaches in the references below:
Beskos, Papaspiliopoulos and Roberts (2008).
Devroye (2009), following the implementation in Pollock, Fearnhead, Johansen and Roberts (2020).
Pollock, Johansen and Roberts (2016).
Repeated symmetric first passages (see first_passage) build
the path on a spatial grid, as in Burq and Jones (2008).
A full introduction is given in the tutorial vignette:
vignette("tutorial", package = "BrownianMotion").
Maintainer: Louis Aslett [email protected]
Authors:
Louis Aslett [email protected]
Murray Pollock [email protected]
Beskos, A., Papaspiliopoulos, O. and Roberts, G.O. (2008). A factorisation of diffusion measure and finite sample path constructions. Methodology and Computing in Applied Probability, 10, 85–104.
Burq, Z.A. and Jones, O.D. (2008). Simulation of Brownian motion at first-passage times. Mathematics and Computers in Simulation, 77, 64–71.
Devroye, L. (2009). On exact simulation algorithms for some distributions related to Jacobi theta functions. Statistics and Probability Letters, 79, 2251–2259.
Pollock, M., Fearnhead, P., Johansen, A.M. and Roberts, G.O. (2020). Quasi-stationary Monte Carlo methods and the ScaLE algorithm (with discussion). Journal of the Royal Statistical Society, Series B (Statistical Methodology), 82, 1–59.
Pollock, M., Johansen, A.M. and Roberts, G.O. (2016). On the exact and
-strong simulation of (jump) diffusions. Bernoulli,
22(2), 794–856.
set.seed(1) bm <- create_bm() bm |> sim(1:4) |> layers(0, 2, type = "bessel") |> first_passage(delta = 1) bm[, "W_t"] plot(bm)set.seed(1) bm <- create_bm() bm |> sim(1:4) |> layers(0, 2, type = "bessel") |> first_passage(delta = 1) bm[, "W_t"] plot(bm)
Brownian motion objects are indexed like a data frame, bm[i, var],
where i selects skeleton points and var selects what to return.
## S3 method for class 'BrownianMotion' bm[i, var, t] ## S3 method for class 'BrownianMotionNd' bm[i, var, t] ## S3 method for class 'BrownianMotionNdZ' bm[i, var, t]## S3 method for class 'BrownianMotion' bm[i, var, t] ## S3 method for class 'BrownianMotionNd' bm[i, var, t] ## S3 method for class 'BrownianMotionNdZ' bm[i, var, t]
bm |
a Brownian motion object. |
i |
the points to select, as indices or labels. Leave empty to select every point. |
var |
what to return (see Details). Omit to return a list of everything. |
t |
times to select, in place of |
Points can be selected in three ways:
by position, e.g. bm[1, "W_t"] for the first point;
by time, using the named argument t, e.g.
bm[t = 1.5, "W_t"]. A range t = a:b selects a,
b and every skeleton time in between (it is not a sequence of
integers). Times not in the skeleton give NA values, but the
layers containing them are still returned;
by label, e.g. bm["user", "t"] (see add_labels).
Leaving i empty, as in bm[, "W_t"], selects every point.
var is one of "t", "W_t" (the path), "W_tm"
(the left limit of the path, which differs from W_t only at jumps
created by add_segment or concat_bm),
"layers" or "labels". If it is omitted, a list of all of these
is returned. For the transformed view bm$Z of a multi-dimensional
path, use "Z_t" and "Z_tm" in place of "W_t" and
"W_tm".
Depending on var: a numeric vector ("t", and
"W_t"/"W_tm" in one dimension); a matrix with one column per
dimension ("W_t"/"W_tm" in several dimensions); a tibble of
layers ("layers"); a named list of label times ("labels");
or a list of all of these if var is omitted.
set.seed(1) bm <- create_bm(t = c(-1, 0, 1), W_t = c(100, 101, 99)) bm |> sim(c(0.5, 2)) |> layers(0, 1, type = "bessel") bm[, "t"] bm[1, "W_t"] # first point bm[t = 0.5, "W_t"] # by time bm[t = 0:1, "W_t"] # 0, 1 and all skeleton times in between bm["user", "t"] # by label bm[, "labels"] bm[t = 0.25, "layers"] # layer containing a time not in the skeleton bm[2] # everything about the second point what <- "W_tm" bm[t = 0:1, what] # var can be held in a variable # Multi-dimensional paths, and their transformed view bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) bm2[, "W_t"] bm2$Z[, "Z_t"]set.seed(1) bm <- create_bm(t = c(-1, 0, 1), W_t = c(100, 101, 99)) bm |> sim(c(0.5, 2)) |> layers(0, 1, type = "bessel") bm[, "t"] bm[1, "W_t"] # first point bm[t = 0.5, "W_t"] # by time bm[t = 0:1, "W_t"] # 0, 1 and all skeleton times in between bm["user", "t"] # by label bm[, "labels"] bm[t = 0.25, "layers"] # layer containing a time not in the skeleton bm[2] # everything about the second point what <- "W_tm" bm[t = 0:1, what] # var can be held in a variable # Multi-dimensional paths, and their transformed view bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) bm2[, "W_t"] bm2$Z[, "Z_t"]
Attaches user labels to times already in the skeleton. Labelled times can
then be used for indexing, e.g. bm["mylabel", "W_t"]. A time can
carry several labels, and the names used internally by the package (such as
"start", "end" and "user") cannot be used.
add_labels(bm, t, label = names(t))add_labels(bm, t, label = names(t))
bm |
a Brownian motion object. Note the object is updated in place |
t |
vector of times in the skeleton to label. |
label |
vector of length 1 or the length of t indicating the introduction of user specified labels (if any). By default, uses any names in the vector of times. |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() bm |> sim(1:4) bm |> add_labels(t = c(1, 3), label = "odd") bm |> add_labels(t = c(peak = 2)) # names of t give the labels bm["odd", "t"] bm[, "labels"]set.seed(1) bm <- create_bm() bm |> sim(1:4) bm |> add_labels(t = c(1, 3), label = "odd") bm |> add_labels(t = c(peak = 2)) # names of t give the labels bm["odd", "t"] bm[, "labels"]
Note: Only valid for time points that don't lie within existing layers. Cannot be an existing time within the skeleton (in this case you should delete then add the point).
add_points(bm, t, W_t, label = names(t))add_points(bm, t, W_t, label = names(t))
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place |
t |
vector of times at which to fix the Brownian motion. |
W_t |
matrix of size the length of t (rows) x dimension (column). If dim = 1, a vector of the length of t is acceptable. If dim > 1 and the length of t = 1, then a vector of length 1 is acceptable (corresponding to the same value at every co-ordinate), or length d is acceptable (corresponding to the d components). |
label |
vector of length 1 or the length of t indicating the introduction of user specified labels (if any). By default, uses any names in the vector of times. |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
# Force the path through W_0 = 101 and W_1 = 99 (a Brownian bridge) bm <- create_bm(-1, 100) bm |> add_points(c(0, 1), c(101, 99)) bm[, "W_t"] # In several dimensions, give one value per component bm3 <- create_bm(dim = 3) bm3 |> add_points(t = 1, W_t = c(-1, 0, 1)) bm3[t = 1, "W_t"]# Force the path through W_0 = 101 and W_1 = 99 (a Brownian bridge) bm <- create_bm(-1, 100) bm |> add_points(c(0, 1), c(101, 99)) bm[, "W_t"] # In several dimensions, give one value per component bm3 <- create_bm(dim = 3) bm3 |> add_points(t = 1, W_t = c(-1, 0, 1)) bm3[t = 1, "W_t"]
Shifts the part of the path over [l, r) by a constant amount,
introducing a discontinuity (jump) at l and/or r. The shift is
given either directly by delta, or by the value W_t that the
path should take at time l. Layers in the interval are moved with the
path.
add_segment(bm, l = -Inf, r = Inf, W_t = NULL, delta = NULL, label = NULL)add_segment(bm, l = -Inf, r = Inf, W_t = NULL, delta = NULL, label = NULL)
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place |
l |
closed left end of interval to add a segment. By default, '-Inf' which results in the introduction of a segment by shifting the entire path up to 'r' |
r |
open right end of interval to add a segment. By default, 'Inf' which results in the introduction of a segment by shifting the entire path from 'l' |
W_t |
vector of length the dimension of the Brownian motion specifying the coordinate of the Brownian motion at the time l (specified by the user). A vector of length 1 is acceptable (corresponding to the same value at every co-ordinate). Defaults to NULL, meaning this argument is ignored in favor of delta. |
delta |
vector of length the dimension of the Brownian motion specifying the shift of the Brownian motion at the time l (specified by the user). A vector of length 1 is acceptable (corresponding to the same shift for every co-ordinate). Defaults to NULL, meaning this argument is ignored in favor of W_t. |
label |
optional user label to attach to the start and end times of the segment. |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() bm |> sim(1:5) # Move the path over [2, 4) up by 3, giving jumps at t = 2 and t = 4 bm |> add_segment(l = 2, r = 4, delta = 3) # Jump to W_5 = 0 and carry on from there bm |> add_segment(l = 5, W_t = 0) |> sim(6) bm[, "W_t"] bm[, "W_tm"] # left limits, which differ from W_t at the jumps plot(bm)set.seed(1) bm <- create_bm() bm |> sim(1:5) # Move the path over [2, 4) up by 3, giving jumps at t = 2 and t = 4 bm |> add_segment(l = 2, r = 4, delta = 3) # Jump to W_5 = 0 and carry on from there bm |> add_segment(l = 5, W_t = 0) |> sim(6) bm[, "W_t"] bm[, "W_tm"] # left limits, which differ from W_t at the jumps plot(bm)
Joins Brownian motion objects end to end, in the order given, into a new
object. Each path after the first is shifted in time to start where the
previous one ends, keeping its own values, so there is in general a jump at
each join. Given a single object, this returns a copy of it, which is the way
to duplicate a path: plain assignment (bm2 <- bm) only creates a second
reference to the same object.
concat_bm(..., t0 = NULL)concat_bm(..., t0 = NULL)
... |
Brownian motion objects to concatenate, all of the same dimension and covariance. The objects passed in are not modified. |
t0 |
scalar representing the time the new Brownian motion should be initialised. Defaults to value of initial time of the first Brownian motion object to be concatenated. |
A new Brownian motion object of the same class as the inputs.
set.seed(1) bm <- create_bm() bm |> sim(1:3) # A copy, which can be extended without changing bm bm.copy <- concat_bm(bm) bm.copy |> sim(10) bm[, "t"] # Two copies end to end, starting at t = 5 bm2 <- concat_bm(bm, bm, t0 = 5) bm2[, "t"] plot(bm2)set.seed(1) bm <- create_bm() bm |> sim(1:3) # A copy, which can be extended without changing bm bm.copy <- concat_bm(bm) bm.copy |> sim(10) bm[, "t"] # Two copies end to end, starting at t = 5 bm2 <- concat_bm(bm, bm, t0 = 5) bm2[, "t"] plot(bm2)
Creates an R environment to contain the trajectories and layer information of a Brownian motion.
create_bm( t = 0, W_t = 0, dim = 1, cov = 1, refine = TRUE, mult = 1, prefer = "bessel" )create_bm( t = 0, W_t = 0, dim = 1, cov = 1, refine = TRUE, mult = 1, prefer = "bessel" )
t |
vector of fixed times of the Brownian motion. Defaults to value of 0. |
W_t |
matrix of size the length of t (rows) x dimension (column). If dim = 1, a vector of the length of t is acceptable. If dim > 1 and the length of t = 1, then a vector of length 1 is acceptable (corresponding to the same value at every co-ordinate), or length d is acceptable (corresponding to the d components). Defaults to 0 for every component. |
dim |
scalar corresponding to the dimension of the Brownian motion. |
cov |
covariance matrix of the Brownian motion. If scalar corresponds to a multiple of the identity matrix. If a vector of length dim, corresponds to a diagonal matrix with these diagonal elements. If matrix should be of size dim x dim. |
refine |
indicates whether refinement should be by default carried out. If of length 1, then this specifies refinement for every dimension. If of length dim, then this specifies refinement for each dimension (in order). |
mult |
set the default mult parameter to be used for any layer operations on this path, including for the level of refinement if |
prefer |
indicates whether there is a preference for "bessel" or "intersection" layers where possible. If of length 1, then this specifies the preference for every dimension. If of length dim, then this specifies preference for each dimension (in order). |
A new Brownian motion object: of class BrownianMotion when
dim = 1, or BrownianMotionNd otherwise. The object is an
environment, so functions which modify it (such as sim)
update it in place; use concat_bm to take a copy.
# Standard Brownian motion started at W_0 = 0 bm <- create_bm() # A path started at W_{-1} = 100 and forced through two further points bm <- create_bm(t = c(-1, 0, 1), W_t = c(100, 101, 99)) bm[, "W_t"] # Three-dimensional Brownian motion with correlated components bm3 <- create_bm(dim = 3, cov = diag(0.5, 3) + 0.5) bm3$cov # Independent components with different variances bm2 <- create_bm(dim = 2, cov = c(1, 4))# Standard Brownian motion started at W_0 = 0 bm <- create_bm() # A path started at W_{-1} = 100 and forced through two further points bm <- create_bm(t = c(-1, 0, 1), W_t = c(100, 101, 99)) bm[, "W_t"] # Three-dimensional Brownian motion with correlated components bm3 <- create_bm(dim = 3, cov = diag(0.5, 3) + 0.5) bm3$cov # Independent components with different variances bm2 <- create_bm(dim = 2, cov = c(1, 4))
Removes user labels. Give label alone to remove those labels from all
times, t alone to remove all user labels from those times, or both to
remove those labels from those times only. Labels used internally by the
package cannot be deleted.
delete_labels(bm, t = NA, label = NA)delete_labels(bm, t = NA, label = NA)
bm |
a Brownian motion object. Note the object is updated in place |
t |
vector of times in the skeleton from which to remove labels. |
label |
vector of user labels to remove. |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() bm |> sim(c(a = 1, b = 2, a = 3)) bm |> delete_labels(t = 3, label = "a") # "a" remains at t = 1 bm |> delete_labels(label = "b") # "b" removed everywhere bm[, "labels"]set.seed(1) bm <- create_bm() bm |> sim(c(a = 1, b = 2, a = 3)) bm |> delete_labels(t = 3, label = "a") # "a" remains at t = 1 bm |> delete_labels(label = "b") # "b" removed everywhere bm[, "labels"]
Eliminate parts of path, layer or both from the skeleton
delete_skeleton(bm, l = -Inf, r = Inf, type = "all")delete_skeleton(bm, l = -Inf, r = Inf, type = "all")
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place |
l |
closed left end of interval to delete. By default, '-Inf' which results in left truncation of the path up to 'r' |
r |
open right end of interval to delete. By default, 'Inf' which results in right truncation of the path from 'l' |
type |
one of '"all"', '"layer"' or '"label"' to specify whether to delete both path observations and layers, just layers, or just user labels in the interval |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() bm |> sim(1:6) |> layers(0, 6, type = "bessel") # Remove only the layers over [2, 4) bm |> delete_skeleton(l = 2, r = 4, type = "layer") # Remove everything after t = 5 bm |> delete_skeleton(l = 5) bm[, "t"]set.seed(1) bm <- create_bm() bm |> sim(1:6) |> layers(0, 6, type = "bessel") # Remove only the layers over [2, 4) bm |> delete_skeleton(l = 2, r = 4, type = "layer") # Remove everything after t = 5 bm |> delete_skeleton(l = 5) bm[, "t"]
Finds the first passage time of a Brownian motion object to a specified lower, upper, or lower and upper limit.
first_passage( bm, l = NULL, u = NULL, delta.l = NULL, delta.u = NULL, delta = NULL, label = NULL )first_passage( bm, l = NULL, u = NULL, delta.l = NULL, delta.u = NULL, delta = NULL, label = NULL )
bm |
a Brownian motion object (of dimension 1) from which simulation should continue. Note the object is updated in place. |
l |
scalar giving lower bound for first passage. |
u |
scalar giving upper bound for first passage. |
delta.l |
provide bounds via the negative change in Brownian motion. May be specified together with |
delta.u |
provide bounds via the positive change in Brownian motion. May be specified together with |
delta |
scalar providing the bounds by way of the positive/negative change in the Brownian motion. |
label |
a user specified label for the first passage time created by this layer (optional). |
This function updates a Brownian motion object adding the first passage time to
the specified lower (l), upper (u), or lower and upper limits.
The limits can also be specfied via delta which places the limits as the
current endpoint state +/- delta.
Note that simulation of the first passage implicitly imposes constraints on the
underlying Brownian motion between the endpoint and the first passage
time.
In particular, in the case that the lower and upper limits are asymmetric around the endpoint, there may be a recursive simulation of nested symmetric first passages between the endpoint and the ultimate first passage, resulting in implicit imposition of nested constraints. When plotting a Brownian motion these are visible as dashed red lines nested within the solid red line constraint imposed by the overall first passage simulation.
A symmetric first passage moves the path by +delta or -delta,
each with probability 1/2, at a time obtained by scaling the exit time of
standard Brownian motion from , which is sampled exactly using
the algorithm of Devroye (2009) as implemented in Pollock et al. (2020).
Repeated calls with a fixed delta therefore build the path on a
regular spatial grid at its successive first passage times, as proposed by
Burq and Jones (2008).
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
Burq, Z.A. and Jones, O.D. (2008). Simulation of Brownian motion at first-passage times. Mathematics and Computers in Simulation, 77, 64–71.
Devroye, L. (2009). On exact simulation algorithms for some distributions related to Jacobi theta functions. Statistics and Probability Letters, 79, 2251–2259.
Pollock, M., Fearnhead, P., Johansen, A.M. and Roberts, G.O. (2020). Quasi-stationary Monte Carlo methods and the ScaLE algorithm (with discussion). Journal of the Royal Statistical Society, Series B (Statistical Methodology), 82, 1–59.
set.seed(1) bm <- create_bm() # First time the path moves 1 away from its current end point bm |> first_passage(delta = 1) # Asymmetric limits, given relative to the end point... bm |> first_passage(delta.l = -1, delta.u = 3) # ... or as absolute levels, with a label on the passage time end <- bm["end", "W_t"] bm |> first_passage(l = end - 2, u = end + 2, label = "exit") bm["exit", "t"] plot(bm)set.seed(1) bm <- create_bm() # First time the path moves 1 away from its current end point bm |> first_passage(delta = 1) # Asymmetric limits, given relative to the end point... bm |> first_passage(delta.l = -1, delta.u = 3) # ... or as absolute levels, with a label on the passage time end <- bm["end", "W_t"] bm |> first_passage(l = end - 2, u = end + 2, label = "exit") bm["exit", "t"] plot(bm)
Simulates layers (bounds which contain the Brownian motion path) for each
interval between consecutive skeleton times in [s, t]. If s or
t are not already in the skeleton, they are simulated first.
layers( bm, s, t, type = bm$prefer, refine = bm$refine, mult = bm$mult, prefer = bm$prefer, label = c(names(s), names(t)) )layers( bm, s, t, type = bm$prefer, refine = bm$refine, mult = bm$mult, prefer = bm$prefer, label = c(names(s), names(t)) )
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place |
s |
left hand time point |
t |
right hand time point |
type |
type specifies whether to carry out "bessel" or "intersection" or "localised" simulation. If of length 1, then this specifies the type for every dimension. If of length dim, then this specifies for each dimension the type. By default this matches the setting for preference specified on the creation of the Brownian motion object. |
refine |
indicates whether refinement should be by default carried out. If of length 1, then this specifies refinement for every dimension. If of length dim, then this specifies refinement for each dimension (in order). By default uses the setting on creation of the Brownian motion object. |
mult |
the default layer size is |
prefer |
indicates whether there is a preference for "bessel" or "intersection" layers where possible. If of length 1, then this specifies the preference for every dimension. If of length dim, then this specifies preference for each dimension (in order). By default uses the setting on creation of the Brownian motion object. |
label |
vector of length 1 or the length of t indicating the introduction of user specified labels (if any). By default, uses any names in the vector of times. |
Three types of layer are available. "bessel" and
"intersection" layers are simulated exactly by retrospective Bernoulli
sampling and inversion sampling, and existing layers of either of these types
in [s, t] are converted to the requested type where possible.
"localised" layers are obtained by simulating first passage times, and
are only added to intervals which do not already have a layer.
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
Bessel layers: Beskos, A., Papaspiliopoulos, O. and Roberts, G.O. (2008). A factorisation of diffusion measure and finite sample path constructions. Methodology and Computing in Applied Probability, 10, 85–104.
Localised layers: Devroye, L. (2009). On exact simulation algorithms for some distributions related to Jacobi theta functions. Statistics and Probability Letters, 79, 2251–2259; and Pollock, M., Fearnhead, P., Johansen, A.M. and Roberts, G.O. (2020). Quasi-stationary Monte Carlo methods and the ScaLE algorithm (with discussion). Journal of the Royal Statistical Society, Series B (Statistical Methodology), 82, 1–59.
Intersection layers: Pollock, M., Johansen, A.M. and Roberts, G.O. (2016).
On the exact and -strong simulation of (jump) diffusions.
Bernoulli, 22(2), 794–856.
set.seed(1) bm <- create_bm() bm |> sim(c(1, 2, 4)) # Bessel layers over [0, 2], then [2, 3]: t = 3 is not yet in the skeleton, # so it is simulated first bm |> layers(0, 2, type = "bessel") |> layers(2, 3) # Localised layers, which may extend the path past its current end bm |> layers(4, 6, type = "localised") bm[, "layers"] plot(bm)set.seed(1) bm <- create_bm() bm |> sim(c(1, 2, 4)) # Bessel layers over [0, 2], then [2, 3]: t = 3 is not yet in the skeleton, # so it is simulated first bm |> layers(0, 2, type = "bessel") |> layers(2, 3) # Localised layers, which may extend the path past its current end bm |> layers(4, 6, type = "localised") bm[, "layers"] plot(bm)
Plots the skeleton of a Brownian motion path with ggplot2. Black dots
are the simulated points, joined by grey lines; these lines are only a guide
and are not the path itself. Layers are drawn as horizontal bounds coloured
by type (purple for Bessel, blue for intersection, red for localised), with
solid lines for bounds the path stays within and dashed or dotted lines for
inner bounds. Bounds given by the user to first_passage are
drawn in green. Jumps (see add_segment) are shown with open
circles at the left limit and a dotted vertical line.
## S3 method for class 'BrownianMotionNd' plot(x, y, ...) ## S3 method for class 'BrownianMotionNdZ' plot(x, y, ...) ## S3 method for class 'BrownianMotion' plot(x, y, ...)## S3 method for class 'BrownianMotionNd' plot(x, y, ...) ## S3 method for class 'BrownianMotionNdZ' plot(x, y, ...) ## S3 method for class 'BrownianMotion' plot(x, y, ...)
x |
a Brownian motion object. |
y |
unused. |
... |
plotting options:
|
A multi-dimensional path is drawn as a grid of plots (combined with
patchwork): each component against time on the diagonal, and each pair
of components against each other off the diagonal, where the red region
contains the path over the plotted time range and the black box bounds it.
plot(bm$Z) draws the transformed, independent components instead.
A ggplot2 plot (a patchwork of plots for several dimensions), which is drawn when printed.
set.seed(1) bm <- create_bm() bm |> sim(1:4) |> layers(0, 2, type = "bessel") |> first_passage(l = -3, u = 3) plot(bm) plot(bm, t.lim = c(0, 2)) plot(bm, hide.user = TRUE) bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) plot(bm2) plot(bm2, layers.2d = "detailed", pairs = FALSE) plot(bm2$Z)set.seed(1) bm <- create_bm() bm |> sim(1:4) |> layers(0, 2, type = "bessel") |> first_passage(l = -3, u = 3) plot(bm) plot(bm, t.lim = c(0, 2)) plot(bm, hide.user = TRUE) bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) plot(bm2) plot(bm2, layers.2d = "detailed", pairs = FALSE) plot(bm2$Z)
Prints an overview of a Brownian motion path followed by its skeleton as a
table, with one row per simulated point. format() returns the same
output as a character vector, one element per line.
## S3 method for class 'BrownianMotion' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotionNd' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotionNdZ' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotion' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'BrownianMotionNd' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'BrownianMotionNdZ' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...)## S3 method for class 'BrownianMotion' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotionNd' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotionNdZ' print(x, n = NULL, digits = NULL, ...) ## S3 method for class 'BrownianMotion' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'BrownianMotionNd' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'BrownianMotionNdZ' format(x, n = NULL, digits = NULL, width = cli::console_width(), ...)
x |
a Brownian motion object, or the transformed view |
n |
the number of skeleton points to show. By default every point is
shown when there are at most 20, and 10 otherwise. Use |
digits |
the minimum number of significant digits to show, as in
|
... |
further arguments passed on from |
width |
the width of the output in characters. Defaults to the width of the console. |
The first lines give the number of skeleton points and the time range they span, the number of layers and the proportion of that time range they cover, and the number of jumps and user labels. For a multi-dimensional path the covariance is also described.
The table then lists, for each skeleton point:
t, W_t
the time and the value of the path (one column
per component in several dimensions, or Z_t for the transformed
view bm$Z).
W_tm(one dimension, paths with jumps only) the left limit of
the path at each jump. In several dimensions a jump column gives
the (Euclidean) size of the jump instead.
originhow the point arose: "fixed" for points given to
create_bm or add_points, "sim" for
points simulated with sim (or as the ends of a layer
interval), "passage" for first passage times (see
first_passage, which are also used to build localised
layers) and "other" for anything else.
layer, bounds
the type of layer, if any, over the
interval from this point to the next, and (in one dimension) the bounds
[L, U] which contain the whole path over that interval. For a
multi-dimensional path the layer types are those of the independent
components of bm$Z; see bm[, "layers"] for the bounds.
labelsany user labels on the point (see
add_labels).
Long paths show only the first and last few points; use n to see
more. Layer types are coloured as in plot
when the console supports colour. Columns which do not fit in the console
width are dropped or truncated.
print() returns x invisibly. format() returns a
character vector with one element per line of output.
summary for a fuller
summary, and indexing to extract
the values shown.
set.seed(1) bm <- create_bm() bm |> sim(c(1, 2, peak = 3)) |> layers(0, 2, type = "bessel") bm # Long paths show only the first and last few points bm |> first_passage(delta = 0.5) |> sim(seq(3.1, 6, by = 0.1)) bm print(bm, n = 4, digits = 2) # Multi-dimensional paths, and their transformed view bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) bm2 bm2$Zset.seed(1) bm <- create_bm() bm |> sim(c(1, 2, peak = 3)) |> layers(0, 2, type = "bessel") bm # Long paths show only the first and last few points bm |> first_passage(delta = 0.5) |> sim(seq(3.1, 6, by = 0.1)) bm print(bm, n = 4, digits = 2) # Multi-dimensional paths, and their transformed view bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) bm2 bm2$Z
Tightens the bounds of every layer which overlaps the interval
(s, t), without adding points to the skeleton. All layer types
(Bessel, intersection and localised) can be refined.
refine(bm, s, t, mult = bm$mult)refine(bm, s, t, mult = bm$mult)
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place |
s |
left hand time point |
t |
right hand time point |
mult |
the default layer size is |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() bm |> sim(1:3) |> layers(0, 3, type = "bessel") bm[, "layers"] # Tighten all layers over [0, 3] bm |> refine(0, 3, mult = 0.2) bm[, "layers"]set.seed(1) bm <- create_bm() bm |> sim(1:3) |> layers(0, 3, type = "bessel") bm[, "layers"] # Tighten all layers over [0, 3] bm |> refine(0, 3, mult = 0.2) bm[, "layers"]
Simulates Brownian motion at chosen times, automatically applying the correct algorithm to condition on the current known (ie previously simulated) states of the trajectory.
sim( bm, t, refine = bm$refine, mult = bm$mult, prefer = bm$prefer, label = names(t) )sim( bm, t, refine = bm$refine, mult = bm$mult, prefer = bm$prefer, label = names(t) )
bm |
a Brownian motion object from which simulation should continue. Note the object is updated in place. |
t |
a vector of times to simulate at. |
refine |
whether to automatically refine layers where the simulated
time results in bisection of an existing layer. Defaults to the option
specified at the time of creation of |
mult |
the mult parameter to be passed through to any layer operations
including for the level of refinement if |
prefer |
indicate the preferred layer type which should arise after
conditional simulation bisects an existing layer (this will be respected
where possible, but it not always achievable). Defaults to the option
specified at the time of creation of |
label |
vector of length 1 or the length of t indicating the introduction of user specified labels (if any). By default, uses any names in the vector of times. |
The Brownian motion object bm, updated in place and returned
invisibly so that calls can be chained with pipes.
set.seed(1) bm <- create_bm() # Simulate forwards in time, then fill in between existing points bm |> sim(c(1, 2, 3)) |> sim(c(0.5, 1.5)) bm[, "t"] # Times given names are labelled bm |> sim(c(special = 4)) bm["special", "W_t"] # Simulation inside a layer conditions on the layer bounds bm |> layers(1, 2, type = "bessel") |> sim(1.25) plot(bm)set.seed(1) bm <- create_bm() # Simulate forwards in time, then fill in between existing points bm |> sim(c(1, 2, 3)) |> sim(c(0.5, 1.5)) bm[, "t"] # Times given names are labelled bm |> sim(c(special = 4)) bm["special", "W_t"] # Simulation inside a layer conditions on the layer bounds bm |> layers(1, 2, type = "bessel") |> sim(1.25) plot(bm)
Summarises the skeleton of a Brownian motion path, its layers, jumps and labels, and the default settings used for further simulation.
## S3 method for class 'BrownianMotion' summary(object, ...) ## S3 method for class 'BrownianMotionNd' summary(object, ...) ## S3 method for class 'BrownianMotionNdZ' summary(object, ...) ## S3 method for class 'summary.BrownianMotion' print(x, digits = NULL, ...) ## S3 method for class 'summary.BrownianMotionNd' print(x, digits = NULL, ...) ## S3 method for class 'summary.BrownianMotion' format(x, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'summary.BrownianMotionNd' format(x, digits = NULL, width = cli::console_width(), ...)## S3 method for class 'BrownianMotion' summary(object, ...) ## S3 method for class 'BrownianMotionNd' summary(object, ...) ## S3 method for class 'BrownianMotionNdZ' summary(object, ...) ## S3 method for class 'summary.BrownianMotion' print(x, digits = NULL, ...) ## S3 method for class 'summary.BrownianMotionNd' print(x, digits = NULL, ...) ## S3 method for class 'summary.BrownianMotion' format(x, digits = NULL, width = cli::console_width(), ...) ## S3 method for class 'summary.BrownianMotionNd' format(x, digits = NULL, width = cli::console_width(), ...)
object |
a Brownian motion object, or the transformed view |
... |
unused. |
x |
a summary, as returned by |
digits |
the minimum number of significant digits to show, as in
|
width |
the width of the output in characters. Defaults to the width of the console. |
The values of the path are summarised at the skeleton points only (including the left limits at any jumps), so the minimum and maximum are those of the simulated points, not of the whole path. Over the parts of the time range covered by layers, however, the whole path is known to lie within the layer bounds, and the summary reports the overall bounds this gives. For a multi-dimensional path these are the bounds of the smallest box, with sides parallel to the axes, which contains every layer.
summary() returns an object of class
"summary.BrownianMotion" (one dimension) or
"summary.BrownianMotionNd" (several dimensions, and bm$Z),
which is a list with elements:
dimthe dimension of the path.
view(several dimensions) "W" for the path, or
"Z" for its transformed view bm$Z.
cov(several dimensions) the covariance matrix of the components summarised.
n.pointsthe number of skeleton points.
t.rangethe first and last times of the skeleton.
originthe number of skeleton points of each origin:
"fixed", "sim", "passage" and "other" (see
print).
spacingthe minimum, median and maximum time between
consecutive skeleton points, or NULL for a single point.
path(one dimension) a data frame giving the time and value of the path at its start, end, minimum and maximum.
components(several dimensions) a data frame with a row per
component giving its value at the start and end, its minimum and
maximum, and the lower (L) and upper (U) layer bounds.
jumpsa data frame with a row per jump, giving its time
t and size (in one dimension also the left limit
W_tm and value W_t; in several dimensions the size is
the Euclidean length of the jump).
layers(one dimension) a data frame with a row per layer
type, giving the number of intervals, the total time they cover, and
the mean distance between their bounds. In several dimensions, a matrix
of the number of intervals of each type (rows) in each component of
bm$Z (columns).
n.layersthe number of layer intervals.
coveragethe proportion of the time range covered by
layers (NA for a single point).
gapsa data frame of the intervals, from and
to, not covered by any layer.
boundsthe bounds which contain the whole path over the
layered time: a vector c(L = , U = ) in one dimension, and part
of components in several. NULL if there are no layers.
labelsthe number of points with each user label.
passages(one dimension) the number of first passages
requested with first_passage.
settingsthe defaults refine, mult and
prefer used by sim and layers (one
value per component in several dimensions).
print() returns x invisibly.
print for a table of the
skeleton, and indexing and
layers for the details of each point and layer.
set.seed(1) bm <- create_bm() bm |> sim(c(1, 2, peak = 3)) |> layers(0, 2, type = "bessel") |> first_passage(delta = 1) summary(bm) # The summary can also be used programmatically s <- summary(bm) s$coverage s$bounds bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) summary(bm2) summary(bm2$Z)set.seed(1) bm <- create_bm() bm |> sim(c(1, 2, peak = 3)) |> layers(0, 2, type = "bessel") |> first_passage(delta = 1) summary(bm) # The summary can also be used programmatically s <- summary(bm) s$coverage s$bounds bm2 <- create_bm(dim = 2, cov = matrix(c(1, 0.5, 0.5, 1), 2)) bm2 |> sim(1:2) |> layers(0, 2) summary(bm2) summary(bm2$Z)