---
title: "mlsjunkgen"
author: "Steve Myles"
date: 2015-09-07
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{mlsjunkgen}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Background

I took a course in graduate school ("[Statistical Analysis for Digital 
Simulation](https://catalog.ttu.edu/portfolio.php?catoid=15&add=1&coid=93083#)") 
at [Texas Tech](https://www.ttu.edu/) from Dr. Elliot Montes in which we spent a 
lot of time on the generation and analysis of random numbers.  Here is a 
simple-yet-powerful pseudo-random number generator that I learned about in that 
course.  It is named "The MLS Junk Generator" after [Dr. Milton L. 
Smith](https://www.depts.ttu.edu/imse/faculty/milton_smith/index.php).

I have also released [an Excel/VBA implementation](https://github.com/scumdogsteev/mls-junk-generator) and provided 
[the simple R code](https://github.com/scumdogsteev/mls-junk-generatR) used as 
the basis for this package.

## Algorithm

For any seed values of w, x, y, z:

r<sub>i</sub> = 5.980217w<sup>2</sup> + 9.446377x<sup>0.25</sup> + 
4.81379y<sup>0.33</sup> + 8.91197z<sup>0.5</sup>  

r<sub>i</sub> = r<sub>i</sub> - Int(r<sub>i</sub>)   

For r<sub>i</sub>+1:  

w = x  
    
x = y  
    
y = z  
    
z = r<sub>i</sub>

## Analysis

This generator tends to do well with various tests for randomness (K-S, Chi 
Square, test for runs up and down).  It may not perform as well on other tests 
(e.g., tests for runs above and below the mean), but that could relate to my 
choice of seeds.  As a point of reference, the period of Excel's built-in random 
number generator is 16,777,216 (at least in Excel 2003; the algorithm may have 
changed in Excel 2007 or 2010 [Edit: this seems to still be the period of 
Excel's RNG.]) and the MLS Junk Generator's period is something greater than 9.9 
billion

# Usage

The package consists of four functions:

1. `junkgen` - generates a pseudo-random number from user-specified seeds
2. `mlsjunkgenv` - generates a vector of pseudo-random numbers by calling 
   `junkgen` a user-specified number of times
3. `mlsjunkgend` - generates a data frame of pseudo-random numbers by calling 
   `junkgen` a user-specified number of times
4. `mlsjunkgenm` - generates a user-specified size matrix of pseudo-random 
   numbers by calling `mlsjunkgenv` and assigning the results to a matrix
   
## Examples

```{r library, echo=FALSE}
library(mlsjunkgen)
```

**`junkgen`** generates a single pseudo-random number based on four user-specified
seeds:

```{r junkgen}
w <- 1
x <- 2
y <- 3
z <- 4
junkgen(w = w, x = x, y = y, z = z)
```

**`mlsjunkgenv`** generates a vector containing a stream of `n` (default = 1) 
user-specified pseudo-random numbers based on four user-specified seeds rounded 
to a specified (default = 5) number of decimal places:

```{r mlsjunkgenv 1}
mlsjunkgenv(n = 10, w = w, x = x, y = y, z = z, round = 8)
```

The same example with default rounding:

```{r mlsjunkgenv 2}
mlsjunkgenv(n = 10, w = w, x = x, y = y, z = z)
```

**`mlsjunkgend`** generates a data frame containing a stream of `n` user-specified
pseudo-random numbers based on four user-specified seeds:

```{r mlsjunkgend 1}
mlsjunkgend(n = 10, w = w, x = x, y = y, z = z, round = 8)
```

The same example with default rounding:

```{r mlsjunkgend 2}
mlsjunkgend(n = 10, w = w, x = x, y = y, z = z)
```

**`mlsjunkgenm`** generates a matrix of user-specified size containing a stream 
of pseudo-random numbers based on four user-specified seeds:

```{r mlsjunkgenm}
mlsjunkgenm(nrow = 5, ncol = 5, w = w, x = x, y = y, z = z, round = 3)
```