README.Rmd

---
output:
  md_document:
    toc: true
    toc_depth: 3
  pdf_document:
    smart: false
  html_document:
    smart: false 
---
# Random Walk R package (RandomWalk)


```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE, out.width='100%', out.height='150px'}
  ggplot2::ggplot(RandomWalk::srwalk(time_to_maturity = 4, scale = 100, seed = 5), 
                  ggplot2::aes(time_periods, random_walk_path)) +
  ggplot2::geom_line() +
  ggplot2::theme(axis.line = ggplot2::element_blank(), 
                 axis.text.x = ggplot2::element_blank(),
                 axis.text.y = ggplot2::element_blank(), 
                 axis.ticks = ggplot2::element_blank(),
                 axis.title.x = ggplot2::element_blank(),
                 axis.title.y = ggplot2::element_blank(), 
                 legend.position = "none"
                 # panel.background = ggplot2::element_blank(),
                 # panel.border = ggplot2::element_blank(),
                 # panel.grid.major = ggplot2::element_blank(),
                 # panel.grid.minor = ggplot2::element_blank(), 
                 # plot.background = ggplot2::element_blank()
                 )
```   

## Introduction

The aim of this package is to provide a way to create and manipulate either discrete 
Random Walk or Brownian Motion or even list of them. It would be noticed that the construction
of Brownian Motion is made by taking the limit of a Scaled Random Walk as its step size
goes to zero. The Brownian Motion could therefore be read as a continously stepped
Random Walk.

By convention the _time step size_ of a Random Walk (with no scale defined) is 1.
It means that the value of the Non-Scaled Random Walk updates each _time increment_
of one.
Furthermore the _increments_ of a *Non-Scaled (Unscaled) Random Walk* are either 1 or -1, 
depending on chance (with a Symmetric Non-Scaled Random Walk, getting 1 or -1
as increment is just as likely to occur.)
All that preceed points out that at each time step the value of the random walk 
is sure to be the former one plus or minus 1.

Unlike the Unscaled Random Walk the _increments_ of a *Scaled Random Walk* is defined 
by the following formula: $\sqrt{scale}^{-1}$.
Further more its _time step size_ is no longer one but are defined by the value
of _scale_ and is $\frac{time\_to\_maturity}{scale}$ 


Finally and Also in contrast with the Scaled / Unscaled Random Walk, 
the *Brownian Motion* has neither natural _increments_ not _discrete time step_.
Each value taken by its increments, from time $t_k$ to $t_l$ (with $k < l$) is 
randomly computed using the Normal Law with $mean = 0$ and $variance = t_l - t_k$:
$$N \sim \left(0, t_l - t_k \right)$$

The package also implements some properties of the Random Walk and Brownian Motion
Either to validate some test cases or directly for added functionalities.

Among the following ones:

* Expectation and variance of Random Walk/Brownian Motion
* Expectation and variance of increments
* *Quadratic Variation* (Source of the Black-Scholes-Merton volatility. Computed 
  path by path, where probabilities are not taken into account.)

:exclamation: The special case of Brownian Motion and Random Walk is that they 
incur _the same Quadratic Variation_ among all the different paths.

### Notes

**For more technical informations and example of usage** of the RandomWalk package, 
feel free to have a look inside the [vignettes](/vignettes) repository.


<!-- +++++++++++++++ New H2 +++++++++++++++ -->


## Functions provided by the package

### Key functions

* Multiple Sampled Radom Walks generator: [srwalkGenerator](#srwalkgenerator)
* Sampled Radom Walk constructor: [srwalk](#srwalk)
* Theoretical Radom Walk generator: [trwalkGenerator](#trwalkgenerator)
* Multiple Brownian Motions generator: [sbmotionGenerator](#sbmotiongenerator)
* Brownian Motion constructor: [sbmotion](#sbmotion)
* Joint Distribution Function to characterize the distribution of brownian motion: []()
* Quadratic Variation: [qvar](#qvar)

### Getters and Setters
* To use for retrieving a specific value of one the previous process: 
  [get_values](get_values)


<!-- +++++++++++++++ New h2 +++++++++++++++ --> 

 
## Description of the functions as they was created and defined

The following lines do not fully give a bunch of examples of usage 
of the package functions.

Instead of giving such examples, they provide an brief description of the arguments 
the package functions take as well as the way these agruments are defined (along
with the default value they take)

 
<!-- +++++++++++++++ New h3 +++++++++++++++ --> 
<!-- +++++++++++++++ srwalkGenerator +++++++++++++++ --> 
 
### srwalkGenerator

#### Summary

This function return a R _list_ of multiple _data.frame_ s. Each one contains
the following variables:

1. *time_periods*: Ordered vector from 0 up to T(time_to_maturity). It represents 
  a partition of the period of time where the random walk evolved. 
  The partition step of this vector depends on the variable _scale_.
1. *random_walk_path*: Provides all the random values taken by the sampled 
    random walk.  


#### Arguments
 
| Arguments | Default | Description |
|---|---|---|
| time_to_maturity | 100 | Final time up to the Random Walk goes |
| prob | 0.5 | Probability of occurence of head and tail for each step |
| scale | 1 | Define the partition of the time period and the scale of up and down factors of the increments, following the rule: $\sqrt{scale}^{-1}$|
| seed | 1 | It fixes initial value of the pseudo random number generation in order to get reproducible experiments. |
| n | 1 | Number of Random Walk generated by the function |

  
#### Example of usage

```{r message=FALSE, error=FALSE}
library(RandomWalk)
# The following line set the variable @sampled with a list of 20
# data.frame of Adapted random walk.
Sampled <- srwalkGenerator(time_to_maturity = 500, 
                           seed = 7,
                           n = 20)
```

The previous Sampled Random Walks could be reduce to its graphical representation:

```{r message=FALSE, error=FALSE}
ggplot2::ggplot(dplyr::bind_rows(Sampled, .id = "uid")
                , ggplot2::aes(x = time_periods, 
                               y = random_walk_path,
                               group = uid)) +
ggplot2::geom_line(alpha = .5) + 
ggplot2::labs(title = "Random Walk paths from multiple random experiments", 
              caption = "Random Walks",
              x = 'Time periods',
              y = 'Random Walk')
```
  

<!-- +++++++++++++++ New h3 +++++++++++++++ --> 
<!-- +++++++++++++++ srwalk description +++++++++++++++ --> 
### srwalk

#### Summary

This function is defined to be the constructor of a unique Sampled Random Walk. 
It returns a unique S3 object with classes as follow:

```{R echo=FALSE}
c("sampled_randomwalk", "data.frame")
```
 
srwalk() outputs a data.frame which contains each time step along 
with the associated Sampled Random Walk value, arranged as follow:

1. *time_periods*: Ordered vector from 0 up to T(time_to_maturity). It represents 
  a partition of the period of time where the random walk evolved. 
  The partition step of this vector depends on the variable _scale_.
1. *random_walk_path*: Provides all the random values taken by the sampled 
    random walk.  


#### Arguments
 
| Arguments | Default | Description |
|---|---|---|
| time_to_maturity | 100 | Final time up to the Random Walk goes |
| prob | 0.5 | Probability of occurence of head and tail for each step |
| scale | 1 | Define the partition of the time period and the scale of up and down factors of the increments, following the rule: $\sqrt{scale}^{-1}$|
| seed | 1 | It fixes initial value of the pseudo random number generation in order to get reproducible experiments. |
| n | 1 | Number of Random Walk generated by the function |
 
  
#### Example of usage

```{r echo=TRUE}
library(RandomWalk)
# Generate a 150 steps Unscale Symmetric Random Walk
srw <- srwalk(time_to_maturity =  150)
``` 

  
```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE}
library(knitr)
library(kableExtra)
kable(head(srw))
```   



<!-- +++++++++++++++ New h3 +++++++++++++++ --> 
<!-- +++++++++++++++ srwalk description +++++++++++++++ --> 
### trwalkGenerator
 

| Arguments | Default | Description |
|---|---|---|
| time_to_maturity | 100 | Final time up to the Random Walk goes |
| prob | 0.5 | Probability of occurence of head and tail for each step |
| scale | 1 | Define the partition of the time period. The scale of up and down factors of the Random Walk follows the rule: $sqrt(scale)^{-1}$ |
| full | FALSE | Number of Brownian Motion generated by the function |
  
 
This function returns all the values the Random Walk could take along with their 
associated probabilities. Either the argument full is set to FALSE and only the 
last time period is return or it is set to TRUE and all the periods are then 
provided.

It returns a uniq S3 object with classes as follow:

```{R echo=FALSE}
class(trwalkGenerator())
```
 
  
#### Example of usage

```{r echo=TRUE, eval=FALSE}
library(RandomWalk)
# Generate the distribution of a 150 steps Symmetric Random Walk
trwalkGenerator(time_to_maturity =  150, full = T)

# Generate the distribution of a Symmetric Random walk from time 0 to 4.
# It only returns the last time distribution along with the associated 
# probabilities
trwalkGenerator(time_to_maturity = 4, scale = 2)
``` 

The last example gives the following result:  
  
```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE}
library(knitr)
library(kableExtra)
kable(trwalkGenerator(time_to_maturity = 4, scale = 2) )
```   

With expectation and variance:

```{R}
# Declare the Theoretical Random Walk
trw <- trwalkGenerator(time_to_maturity = 4, scale = 2) 
# Expectation:
(Exp <- sum(trw[, 'Pr'] * trw[, 'Mt']))

# Variance (Which is, according to the theory, equal to time_to_maturity): 
sum(trw[, 'Pr'] * trw[, 'Mt'] ^ 2) - Exp
```





<!-- +++++++++++++++ sbmotionGenerator description +++++++++++++++ --> 
### sbmotionGenerator
 

| Arguments | Default | Description |
|---|---|---|
| time_to_maturity | Maximum time up to the Brownian Motion evolves |
| scale | It defines the time partition between each unit of time. For instance if the scale is 100, the time step [0,1] will be cut in 100 parts. |
| seed | With same seed, 2 exeriments will(would, in fact not yet the case when the param scale is different) give the same output. It therefore provides reproducibles experiments. |
 
This function returns a R *list* of multiple *data.frame*s. Each one contains
the following variables:

1. *time_period*: Ordered vector from 0 up to T(time_to_maturity). It represents 
  the time period in which the Brownian Motion evolved. The partition step of this vector
  depends on the variable *scale*.
2. *brownian_motion_path*: All random values taken by the Sampled Brownian Motion.  



#### Example of usage

```{r}
library(RandomWalk)
# The following line set the variable @sampled with a list of 20
# data.frame of Adapted random walk.
Sampled <- sbmotionGenerator(time_to_maturity = 4, scale = 100, n = 30)
```

The above example generates a list of 5 specifics Brownian Motion. To get an idea
of what it represents, the following chart presents the pathes of those previous 
Brownian motion:
  
```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE}
  ggplot2::ggplot(Sampled[[1]], 
                  ggplot2::aes(time_periods, brownian_motion_path)) +
  ggplot2::geom_point() +
  ggplot2::labs(title = 'Uniq Brownian Motion path with time to maturity fixed at 4',
                caption = 'Uniq Brownian Motion path',
                x = 'Time period',
                y = 'Brownian motion')
```   

```{r, echo=FALSE, message=FALSE, warning=FALSE, error=FALSE}
ggplot2::ggplot(dplyr::bind_rows(Sampled, .id = "uniqueID"), 
                ggplot2::aes(x = time_periods, y = brownian_motion_path, group = uniqueID)) + 
  ggplot2::geom_point(ggplot2::aes(colour = uniqueID)) + 
  ggplot2::theme(legend.position = 'none') +
  ggplot2::labs(title = 'Multiple Brownian Motions path with time to maturity fixed at 4',
                caption = 'Multiple Brownian Motions paths',
                x = 'Time period',
                y = 'Brownian motion')
```





<!-- +++++++++++++++ sbmotion description +++++++++++++++ --> 
### sbmotion
 

| Arguments | Default | Description |
|---|---|---|
| time_to_maturity | Maximum time up to the Brownian Motion evolves |
| scale | It defines the time partition between each unit of time. For instance if the scale is 100, the time step [0,1] will be cut in 100 parts. |
| seed | With same seed, 2 exeriments will(would, in fact not yet the case when the param scale is different) give the same output. It therefore provides reproducibles experiments. |
| n | Number of samples generated by the function |
 
This function returns a *data.frame* containing the following variables: 

1. *time_period*: Ordered vector from 0 up to T(time_to_maturity). It represents 
  the time period in which the Brownian Motion evolved. The partition step of this vector
  depends on the variable *scale*.
2. *brownian_motion_path*: All random values taken by the Sampled Brownian Motion.  



#### Example of usage

```{r}
library(RandomWalk)
# The following line set the variable @sampled with a list of 20
# data.frame of Adapted random walk.
Sampled <- sbmotion(time_to_maturity = 4, scale = 100)
```

The above example generates a list of 5 specifics Brownian Motion. To get an idea
of what it represents, the following chart presents the pathes of those previous 
Brownian motion:
  
```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE, fig.cap='Brownian Motion path up to time to maturity fixed at 4'}
  ggplot2::ggplot(Sampled, 
                  ggplot2::aes(time_periods, brownian_motion_path)) +
  ggplot2::geom_point() +
  ggplot2::labs(title = 'Brownian Motion path with time to maturity fixed at 4',
                caption = 'Brownian Motion path',
                x = 'Time period',
                y = 'Brownian Motion')
```