Package 'BrownianMotion'

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

Help Index


BrownianMotion: exact simulation of (conditioned) Brownian motion

Description

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.

Details

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.

Main functions

Creating and simulating

create_bm, sim, add_points

Layers

layers, refine, first_passage

Editing a path

add_segment, delete_skeleton, concat_bm

Labels

add_labels, delete_labels

Inspecting a path

print, summary, plot and indexing

Layer types

Three types of layer are available (see layers), which follow (broadly) the approaches in the references below:

Bessel

Beskos, Papaspiliopoulos and Roberts (2008).

Localised

Devroye (2009), following the implementation in Pollock, Fearnhead, Johansen and Roberts (2020).

Intersection

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").

Author(s)

Maintainer: Louis Aslett [email protected]

Authors:

References

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 ε\varepsilon-strong simulation of (jump) diffusions. Bernoulli, 22(2), 794–856.

Examples

set.seed(1)
bm <- create_bm()
bm |> sim(1:4) |> layers(0, 2, type = "bessel") |> first_passage(delta = 1)
bm[, "W_t"]
plot(bm)

Extract parts of a Brownian motion object

Description

Brownian motion objects are indexed like a data frame, bm[i, var], where i selects skeleton points and var selects what to return.

Usage

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

Arguments

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 i; must be given by name, as in bm[t = 1.5, "W_t"].

Details

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".

Value

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.

Examples

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"]

Manually add labels after simulation

Description

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.

Usage

add_labels(bm, t, label = names(t))

Arguments

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

See Also

delete_labels

Examples

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"]

Manually specify the value of a point in the skeleton

Description

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).

Usage

add_points(bm, t, W_t, label = names(t))

Arguments

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

Examples

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

Create / move a segment

Description

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.

Usage

add_segment(bm, l = -Inf, r = Inf, W_t = NULL, delta = NULL, label = NULL)

Arguments

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

Examples

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)

Copy / Concatenate Brownian motion objects

Description

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.

Usage

concat_bm(..., t0 = NULL)

Arguments

...

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.

Value

A new Brownian motion object of the same class as the inputs.

Examples

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)

Create a Brownian motion object

Description

Creates an R environment to contain the trajectories and layer information of a Brownian motion.

Usage

create_bm(
  t = 0,
  W_t = 0,
  dim = 1,
  cov = 1,
  refine = TRUE,
  mult = 1,
  prefer = "bessel"
)

Arguments

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 refine=TRUE.

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).

Value

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.

Examples

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

Manually delete labels after simulation

Description

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.

Usage

delete_labels(bm, t = NA, label = NA)

Arguments

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

See Also

add_labels

Examples

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

Description

Eliminate parts of path, layer or both from the skeleton

Usage

delete_skeleton(bm, l = -Inf, r = Inf, type = "all")

Arguments

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

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

Examples

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"]

Find a first passage time and state

Description

Finds the first passage time of a Brownian motion object to a specified lower, upper, or lower and upper limit.

Usage

first_passage(
  bm,
  l = NULL,
  u = NULL,
  delta.l = NULL,
  delta.u = NULL,
  delta = NULL,
  label = NULL
)

Arguments

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 to provide asymmetric first passage delta.

delta.u

provide bounds via the positive change in Brownian motion. May be specified together with delta.l to provide asymmetric first passage delta.

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).

Details

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 (−1,1)(-1, 1), 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).

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

References

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.

Examples

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)

Construct new layers

Description

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.

Usage

layers(
  bm,
  s,
  t,
  type = bm$prefer,
  refine = bm$refine,
  mult = bm$mult,
  prefer = bm$prefer,
  label = c(names(s), names(t))
)

Arguments

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 sqrt(t-s). You can scale this by specifying the mult argument which will result in layer sizes of mult*sqrt(t-s). By default uses the setting on creation of the Brownian motion object.

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.

Details

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

References

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 ε\varepsilon-strong simulation of (jump) diffusions. Bernoulli, 22(2), 794–856.

Examples

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)

Plot a Brownian motion path and its layers

Description

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.

Usage

## S3 method for class 'BrownianMotionNd'
plot(x, y, ...)

## S3 method for class 'BrownianMotionNdZ'
plot(x, y, ...)

## S3 method for class 'BrownianMotion'
plot(x, y, ...)

Arguments

x

a Brownian motion object.

y

unused.

...

plotting options:

t.lim

a time range c(from, to) to plot.

hide.user

(one dimension) TRUE to hide the green user-specified bounds.

dims

(several dimensions) which components to plot.

pairs

(several dimensions) FALSE to draw only the pairwise plots, without the plots against time.

layers.2d

(several dimensions) how to draw layers in the pairwise plots: "convex" (default) for the convex hull over the time range, "detailed" for each layer separately, or "union" for their union (requires the sf package).

Details

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.

Value

A ggplot2 plot (a patchwork of plots for several dimensions), which is drawn when printed.

Examples

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)

Print a Brownian motion object

Description

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.

Usage

## 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(), ...)

Arguments

x

a Brownian motion object, or the transformed view bm$Z of a multi-dimensional one.

n

the number of skeleton points to show. By default every point is shown when there are at most 20, and 10 otherwise. Use Inf to show all of them.

digits

the minimum number of significant digits to show, as in format. Defaults to max(3, getOption("digits") - 3).

...

further arguments passed on from print() to format(), and otherwise ignored.

width

the width of the output in characters. Defaults to the width of the console.

Details

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.

origin

how 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.

labels

any 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.

Value

print() returns x invisibly. format() returns a character vector with one element per line of output.

See Also

summary for a fuller summary, and indexing to extract the values shown.

Examples

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$Z

Refine layers

Description

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.

Usage

refine(bm, s, t, mult = bm$mult)

Arguments

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 sqrt(t-s). You can scale this by specifying the mult argument which will result in layer sizes of mult*sqrt(t-s). By default uses the setting on creation of the Brownian motion object.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

Examples

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"]

Simulate Brownian motion at a target time

Description

Simulates Brownian motion at chosen times, automatically applying the correct algorithm to condition on the current known (ie previously simulated) states of the trajectory.

Usage

sim(
  bm,
  t,
  refine = bm$refine,
  mult = bm$mult,
  prefer = bm$prefer,
  label = names(t)
)

Arguments

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 bm.

mult

the mult parameter to be passed through to any layer operations including for the level of refinement if refine=TRUE. Defaults to the option specified at the time of creation of bm.

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 bm.

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.

Value

The Brownian motion object bm, updated in place and returned invisibly so that calls can be chained with pipes.

Examples

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)

Summarise a Brownian motion object

Description

Summarises the skeleton of a Brownian motion path, its layers, jumps and labels, and the default settings used for further simulation.

Usage

## 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(), ...)

Arguments

object

a Brownian motion object, or the transformed view bm$Z of a multi-dimensional one.

...

unused.

x

a summary, as returned by summary().

digits

the minimum number of significant digits to show, as in format. Defaults to max(3, getOption("digits") - 3).

width

the width of the output in characters. Defaults to the width of the console.

Details

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.

Value

summary() returns an object of class "summary.BrownianMotion" (one dimension) or "summary.BrownianMotionNd" (several dimensions, and bm$Z), which is a list with elements:

dim

the 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.points

the number of skeleton points.

t.range

the first and last times of the skeleton.

origin

the number of skeleton points of each origin: "fixed", "sim", "passage" and "other" (see print).

spacing

the 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.

jumps

a 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.layers

the number of layer intervals.

coverage

the proportion of the time range covered by layers (NA for a single point).

gaps

a data frame of the intervals, from and to, not covered by any layer.

bounds

the 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.

labels

the number of points with each user label.

passages

(one dimension) the number of first passages requested with first_passage.

settings

the defaults refine, mult and prefer used by sim and layers (one value per component in several dimensions).

print() returns x invisibly.

See Also

print for a table of the skeleton, and indexing and layers for the details of each point and layer.

Examples

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)