From 7ded12323fd88e7657a70860976cdd5ee447877d Mon Sep 17 00:00:00 2001 From: "Steven Paul Sanderson II, MPH" Date: Fri, 19 Jul 2024 12:30:46 -0400 Subject: [PATCH] Fixes #16 --- NAMESPACE | 1 + NEWS.md | 5 +- R/gen-brown-motion.R | 101 +++++++++++++++++++++++++++++++ man/brownian_motion.Rd | 66 ++++++++++++++++++++ man/geometric_brownian_motion.Rd | 1 + man/random_normal_drift_walk.Rd | 1 + man/random_normal_walk.Rd | 1 + 7 files changed, 174 insertions(+), 2 deletions(-) create mode 100644 R/gen-brown-motion.R create mode 100644 man/brownian_motion.Rd diff --git a/NAMESPACE b/NAMESPACE index 52b0022..b065647 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ # Generated by roxygen2: do not edit by hand +export(brownian_motion) export(geometric_brownian_motion) export(random_normal_drift_walk) export(random_normal_walk) diff --git a/NEWS.md b/NEWS.md index 41e5253..d457abf 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,8 +5,9 @@ None ## New Features 1. Fix #9 - Add Function `rw30()` to generate 30 random walks of 100 steps each. -2. Fix #17 - Add Function `geometric_brownian_motion()` -3. Fix #18 - Add Function `random_normal_drift_walk()` +2. Fix #17 - Add Function `geometric_brownian_motion()` to generate Geometric Brownian Motion +3. Fix #18 - Add Function `random_normal_drift_walk()` to generate Random Walk with Drift +4. Fix #16 - Add Function `brownian_motion()` to generate Brownian Motion ## Minor Improvements and Fixes None diff --git a/R/gen-brown-motion.R b/R/gen-brown-motion.R new file mode 100644 index 0000000..4c84df0 --- /dev/null +++ b/R/gen-brown-motion.R @@ -0,0 +1,101 @@ +#' Brownian Motion +#' +#' @family Generator Functions +#' +#' @author Steven P. Sanderson II, MPH +#' +#' @description Create a Brownian Motion Tibble +#' +#' @details Brownian Motion, also known as the Wiener process, is a +#' continuous-time random process that describes the random movement of particles +#' suspended in a fluid. It is named after the physicist Robert Brown, +#' who first described the phenomenon in 1827. +#' +#' The equation for Brownian Motion can be represented as: +#' +#' W(t) = W(0) + sqrt(t) * Z +#' +#' Where W(t) is the Brownian motion at time t, W(0) is the initial value of the +#' Brownian motion, sqrt(t) is the square root of time, and Z is a standard +#' normal random variable. +#' +#' Brownian Motion has numerous applications, including modeling stock prices in +#' financial markets, modeling particle movement in fluids, and modeling random +#' walk processes in general. It is a useful tool in probability theory and +#' statistical analysis. +#' +#' @param .n Total time of the simulation. +#' @param .num_walks Total number of simulations. +#' @param .delta_time Time step size. +#' @param .initial_value Integer representing the initial value. +#' @param .return_tibble The default is TRUE. If set to FALSE then an object +#' of class matrix will be returned. +#' +#' @examples +#' brownian_motion() +#' +#' @return +#' A tibble/matrix +#' +#' @name brownian_motion +NULL + +#' @export +#' @rdname brownian_motion + +brownian_motion <- function(.n = 100, .num_walks = 10, .delta_time = 1, + .initial_value = 0, .return_tibble = TRUE) { + + # Tidyeval ---- + num_sims <- as.numeric(.num_walks) + t <- as.numeric(.n) + initial_value <- as.numeric(.initial_value) + delta_time <- as.numeric(.delta_time) + return_tibble <- as.logical(.return_tibble) + + # Checks + if (!is.numeric(num_sims) | !is.numeric(t) | !is.numeric(initial_value) | + !is.numeric(delta_time)){ + rlang::abort( + message = "The parameters `.num_walks`, `.n`, `.delta_time`, and `.initial_value` must be numeric.", + use_cli_format = TRUE + ) + } + + if (!is.logical(return_tibble)){ + rlang::abort( + message = "The parameter `.return_tibble` must be either TRUE/FALSE", + use_cli_format = TRUE + ) + } + + # Matrix of random draws - one for each simulation + rand_matrix <- matrix(rnorm(t * num_sims, mean = 0, sd = sqrt(delta_time)), + ncol = num_sims, nrow = t) + colnames(rand_matrix) <- 1:num_sims + + # Get the Brownian Motion and convert to price paths + ret <- apply(rbind(rep(initial_value, num_sims), rand_matrix), 2, cumsum) + + # Return + if (return_tibble){ + ret <- ret |> + dplyr::as_tibble() |> + dplyr::mutate(t = 1:(t+1)) |> + tidyr::pivot_longer(-t) |> + dplyr::select(name, t, value) |> + purrr::set_names("walk_number", "x", "y") |> + dplyr::mutate(walk_number = factor(walk_number)) |> + dplyr::arrange(walk_number, x) + } + + # Return ---- + attr(ret, "time") <- .n + attr(ret, "num_sims") <- .num_walks + attr(ret, "delta_time") <- .delta_time + attr(ret, "initial_value") <- .initial_value + attr(ret, "return_tibble") <- .return_tibble + attr(ret, "fns") <- "brownian_motion" + + return(ret) +} diff --git a/man/brownian_motion.Rd b/man/brownian_motion.Rd new file mode 100644 index 0000000..7f1234b --- /dev/null +++ b/man/brownian_motion.Rd @@ -0,0 +1,66 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gen-brown-motion.R +\name{brownian_motion} +\alias{brownian_motion} +\title{Brownian Motion} +\usage{ +brownian_motion( + .n = 100, + .num_walks = 10, + .delta_time = 1, + .initial_value = 0, + .return_tibble = TRUE +) +} +\arguments{ +\item{.n}{Total time of the simulation.} + +\item{.num_walks}{Total number of simulations.} + +\item{.delta_time}{Time step size.} + +\item{.initial_value}{Integer representing the initial value.} + +\item{.return_tibble}{The default is TRUE. If set to FALSE then an object +of class matrix will be returned.} +} +\value{ +A tibble/matrix +} +\description{ +Create a Brownian Motion Tibble +} +\details{ +Brownian Motion, also known as the Wiener process, is a +continuous-time random process that describes the random movement of particles +suspended in a fluid. It is named after the physicist Robert Brown, +who first described the phenomenon in 1827. + +The equation for Brownian Motion can be represented as: + +\if{html}{\out{
}}\preformatted{W(t) = W(0) + sqrt(t) * Z +}\if{html}{\out{
}} + +Where W(t) is the Brownian motion at time t, W(0) is the initial value of the +Brownian motion, sqrt(t) is the square root of time, and Z is a standard +normal random variable. + +Brownian Motion has numerous applications, including modeling stock prices in +financial markets, modeling particle movement in fluids, and modeling random +walk processes in general. It is a useful tool in probability theory and +statistical analysis. +} +\examples{ +brownian_motion() + +} +\seealso{ +Other Generator Functions: +\code{\link{geometric_brownian_motion}()}, +\code{\link{random_normal_drift_walk}()}, +\code{\link{random_normal_walk}()} +} +\author{ +Steven P. Sanderson II, MPH +} +\concept{Generator Functions} diff --git a/man/geometric_brownian_motion.Rd b/man/geometric_brownian_motion.Rd index 0968fd8..191e476 100644 --- a/man/geometric_brownian_motion.Rd +++ b/man/geometric_brownian_motion.Rd @@ -71,6 +71,7 @@ geometric_brownian_motion() } \seealso{ Other Generator Functions: +\code{\link{brownian_motion}()}, \code{\link{random_normal_drift_walk}()}, \code{\link{random_normal_walk}()} } diff --git a/man/random_normal_drift_walk.Rd b/man/random_normal_drift_walk.Rd index d212b78..c007371 100644 --- a/man/random_normal_drift_walk.Rd +++ b/man/random_normal_drift_walk.Rd @@ -54,6 +54,7 @@ ggplot(walks, ggplot2::aes(x = x, y = y, group = walk_number, color = walk_numbe } \seealso{ Other Generator Functions: +\code{\link{brownian_motion}()}, \code{\link{geometric_brownian_motion}()}, \code{\link{random_normal_walk}()} } diff --git a/man/random_normal_walk.Rd b/man/random_normal_walk.Rd index 0848d13..e27eccc 100644 --- a/man/random_normal_walk.Rd +++ b/man/random_normal_walk.Rd @@ -71,6 +71,7 @@ random_normal_walk(.num_walks = 10, .n = 50, .samp = FALSE) } \seealso{ Other Generator Functions: +\code{\link{brownian_motion}()}, \code{\link{geometric_brownian_motion}()}, \code{\link{random_normal_drift_walk}()} }