# tulip/multivariate-normal-js

A Javascript / Node.JS port of NumPy's multivariate_normal
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
 Failed to load latest commit information. dist example scripts spec src test-dist .eslintrc.yml .gitignore LICENSE README.md package.json

# multivariate-normal-js

A pure-javascript port of NumPy's `random.multivariate_normal`, for Node.js and the browser.

Check out the live demo!

From the NumPy docs:

Draw random samples from a multivariate normal distribution.

The multivariate normal, multinormal or Gaussian distribution is a generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean (average or "center") and variance (standard deviation, or "width," squared) of the one-dimensional normal distribution.

See the NumPy documentation additional notes, examples, and references.

# Example

To start, just `npm install multivariate-normal`. You can also get one of the pre-built files from the `dist` folder.

Then you can do:

```    import MultivariateNormal from "multivariate-normal";
// or without ES6 import: var MultivariateNormal = require("multivariate-normal").default;
// or without a CommonJS runtime: <script src="path/to/multivariate-normal.min.js"></script>, and then use the global window.MultivariateNormal.default

// means of our three dimensions
var meanVector = [1, 2, 3];

// covariance between dimensions. This examples makes the first and third
// dimensions highly correlated, and the second dimension independent.
var covarianceMatrix = [
[ 1.0, 0.0, 0.9 ],
[ 0.0, 1.0, 0.0 ],
[ 0.9, 0.0, 1.0 ],
];

var distribution = MultivariateNormal(meanVector, covarianceMatrix);
distribution.sample(); // => [1.2, 1.8, 3.3]

var newDistribution = distribution.setMean([3, 2, 1]);
newDistribution.sample(); // => [2.8, 2.1, 0.7]

// distributions are immutable
distribution.getMean(); // => [1, 2, 3];
newDistribution.getMean(); // => [3, 2, 1];
```

# API

##### `MultivariateNormal(mean, covarianceMatrix) -> Distribution`

Arguments:

• `mean` 1-D Array, of length N: Mean of the N-dimensional distribution.
• `cov` 2-D Array, of shape (N, N): Covariance matrix of the distribution. It must be symmetric and positive-semidefinite for proper sampling.

Returns:

• A Distribution object with methods described below. Distributions are immutable -- the `set` methods return new distributions.
##### `distribution.sample() -> Array`

Draw a random sample from the distribution.

Returns:

• 1-D Array, of length N: The random sample from the distribution.
##### `distribution.getMean(newMean) -> Array`

Returns the mean of this distribution. The array will be frozen.

Returns:

• 1-D Array, of length N: Mean of the distribution.
##### `distribution.setMean(newMean) -> Distribution`

Returns a new Distribution with the same covariance matrix as the current distribution, but a new mean.

Arguments:

• `newMean` 1-D Array, of length N: Mean of the new distribution.

Returns:

• A new Distribution object.
##### `distribution.getCov(newMean) -> Array`

Returns the covariance of this distribution. The array will be frozen.

Returns:

• 2-D Array, of shape (N, N): Covariance matrix of the distribution.
##### `distribution.setCov(newMean) -> Distribution`

Returns a new Distribution with the same mean as the current distribution, but a new covariance matrix.

Arguments:

• `newMean` 2-D Array, of shape (N, N): Covariance matrix of the distribution. It must be symmetric and positive-semidefinite for proper sampling.

Returns:

• A new Distribution object.

# Get Involved

If you've found a bug or have a feature request, file an issue on Github.

To get started developing:

1. Clone this repo.
2. `npm install`

Then, you can run the tests with `npm test`, or run the example app with `npm start` and then navigating to http://localhost:8080.

# Contributing

How to submit changes:

1. Fork this repository.
3. Verify unit tests and linting passes with `npm test`
4. Play around with the example app. Make sure the correlations look correct.
5. Email us as opensource@tulip.co to sign a CLA.
6. Submit a pull request.