diff --git a/lib/node_modules/@stdlib/random/docs/types/index.d.ts b/lib/node_modules/@stdlib/random/docs/types/index.d.ts index 5130b2b21dce..c3d261536d00 100644 --- a/lib/node_modules/@stdlib/random/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/random/docs/types/index.d.ts @@ -20,42 +20,510 @@ /* eslint-disable max-lines */ +import arcsine = require( '@stdlib/random/arcsine' ); import array = require( '@stdlib/random/array' ); import base = require( '@stdlib/random/base' ); +import beta = require( '@stdlib/random/beta' ); +import betaprime = require( '@stdlib/random/betaprime' ); +import binomial = require( '@stdlib/random/binomial' ); +import cauchy = require( '@stdlib/random/cauchy' ); +import cosine = require( '@stdlib/random/cosine' ); +import discreteUniform = require( '@stdlib/random/discrete-uniform' ); +import erlang = require( '@stdlib/random/erlang' ); import exponential = require( '@stdlib/random/exponential' ); +import f = require( '@stdlib/random/f' ); +import gamma = require( '@stdlib/random/gamma' ); +import gumbel = require( '@stdlib/random/gumbel' ); +import invgamma = require( '@stdlib/random/invgamma' ); import iterators = require( '@stdlib/random/iter' ); +import kumaraswamy = require( '@stdlib/random/kumaraswamy' ); +import laplace = require( '@stdlib/random/laplace' ); +import levy = require( '@stdlib/random/levy' ); +import logistic = require( '@stdlib/random/logistic' ); +import lognormal = require( '@stdlib/random/lognormal' ); +import negativeBinomial = require( '@stdlib/random/negative-binomial' ); +import normal = require( '@stdlib/random/normal' ); +import pareto1 = require( '@stdlib/random/pareto-type1' ); import sample = require( '@stdlib/random/sample' ); import shuffle = require( '@stdlib/random/shuffle' ); import streams = require( '@stdlib/random/streams' ); import strided = require( '@stdlib/random/strided' ); import tools = require( '@stdlib/random/tools' ); import uniform = require( '@stdlib/random/uniform' ); +import weibull = require( '@stdlib/random/weibull' ); /** * Interface describing the `random` namespace. */ interface Namespace { + /** + * Generates pseudorandom numbers drawn from an arcsine distribution. + * + * @param shape - output shape + * @param a - minimum support + * @param b - maximum support + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.arcsine( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.arcsine.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.arcsine.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + arcsine: typeof arcsine; + /** * Pseudorandom number generator array creation functions. */ - array: typeof array; + array: typeof array; + + /** + * Base pseudorandom number generators. + */ + base: typeof base; + + /** + * Generates pseudorandom numbers drawn from a beta distribution. + * + * @param shape - output shape + * @param a - first shape parameter + * @param b - second shape parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.beta( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.beta.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.beta.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + beta: typeof beta; + + /** + * Generates pseudorandom numbers drawn from a betaprime distribution. + * + * @param shape - output shape + * @param alpha - first shape parameter + * @param beta - second shape parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.betaprime( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.betaprime.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.betaprime.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + betaprime: typeof betaprime; + + /** + * Generates pseudorandom numbers drawn from a binomial distribution. + * + * @param shape - output shape + * @param n - number of trials + * @param p - success probability + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.binomial( [ 3, 3 ], 17, 0.5 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.binomial.assign( 17, 0.5, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.binomial.factory(); + * + * var out = random( [ 3, 3 ], 17, 0.5 ); + * // returns + */ + binomial: typeof binomial; + + /** + * Generates pseudorandom numbers drawn from a Cauchy distribution. + * + * @param shape - output shape + * @param x0 - location parameter + * @param gamma - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.cauchy( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.cauchy.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.cauchy.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + cauchy: typeof cauchy; + + /** + * Generates pseudorandom numbers drawn from a raised cosine distribution. + * + * @param shape - output shape + * @param mu - mean + * @param s - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.cosine( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.cosine.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.cosine.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + cosine: typeof cosine; + + /** + * Generates pseudorandom numbers drawn from a discrete uniform distribution. + * + * @param shape - output shape + * @param a - minimum support + * @param b - maximum support + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.discreteUniform( [ 3, 3 ], -10, 10 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.discreteUniform.assign( -10, 10, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.discreteUniform.factory(); + * + * var out = random( [ 3, 3 ], -10, 10 ); + * // returns + */ + discreteUniform: typeof discreteUniform; + + /** + * Generates pseudorandom numbers drawn from an Erlang distribution. + * + * @param shape - output shape + * @param k - shape parameter + * @param lambda - rate parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.erlang( [ 3, 3 ], 2, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.erlang.assign( 2, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.erlang.factory(); + * + * var out = random( [ 3, 3 ], 2, 5.0 ); + * // returns + */ + erlang: typeof erlang; + + /** + * Generates pseudorandom numbers drawn from an exponential distribution. + * + * @param shape - output shape + * @param lambda - rate parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.exponential( [ 3, 3 ], 2.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.exponential.assign( 2.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.exponential.factory(); + * + * var out = random( [ 3, 3 ], 2.0 ); + * // returns + */ + exponential: typeof exponential; + + /** + * Generates pseudorandom numbers drawn from an F distribution. + * + * @param shape - output shape + * @param d1 - degrees of freedom + * @param d2 - degrees of freedom + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.f( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.f.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.f.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + f: typeof f; + + /** + * Generates pseudorandom numbers drawn from a gamma distribution. + * + * @param shape - output shape + * @param alpha - shape parameter + * @param beta - rate parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.gamma( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.gamma.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.gamma.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + gamma: typeof gamma; + + /** + * Generates pseudorandom numbers drawn from a Gumbel distribution. + * + * @param shape - output shape + * @param mu - mean + * @param beta - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.gumbel( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.gumbel.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.gumbel.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + gumbel: typeof gumbel; /** - * Base pseudorandom number generators. + * Generates pseudorandom numbers drawn from an inverse gamma distribution. + * + * @param shape - output shape + * @param alpha - shape parameter + * @param beta - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.invgamma( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.invgamma.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.invgamma.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns */ - base: typeof base; + invgamma: typeof invgamma; /** - * Generates pseudorandom numbers drawn from an exponential distribution. + * Pseudorandom number generator iterators. + */ + iterators: typeof iterators; + + /** + * Generates pseudorandom numbers drawn from a Kumaraswamy distribution. * * @param shape - output shape - * @param lambda - rate parameter + * @param a - first shape parameter + * @param b - second shape parameter * @param options - function options * @throws distribution parameters and the output shape must be broadcast compatible * @returns output ndarray * * @example - * var out = ns.exponential( [ 3, 3 ], 2.0 ); + * var out = ns.kumaraswamy( [ 3, 3 ], 2.0, 5.0 ); * // returns * * @example @@ -64,24 +532,257 @@ interface Namespace { * var out = zeros( [ 3, 3 ] ); * // returns * - * var v = ns.exponential.assign( 2.0, out ); + * var v = ns.kumaraswamy.assign( 2.0, 5.0, out ); * // returns * * var bool = ( v === out ); * // returns true * * @example - * var random = ns.exponential.factory(); + * var random = ns.kumaraswamy.factory(); * - * var out = random( [ 3, 3 ], 2.0 ); + * var out = random( [ 3, 3 ], 2.0, 5.0 ); * // returns */ - exponential: typeof exponential; + kumaraswamy: typeof kumaraswamy; /** - * Pseudorandom number generator iterators. + * Generates pseudorandom numbers drawn from a Laplace (double exponential) distribution. + * + * @param shape - output shape + * @param mu - mean + * @param b - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.laplace( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.laplace.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.laplace.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns */ - iterators: typeof iterators; + laplace: typeof laplace; + + /** + * Generates pseudorandom numbers drawn from a Lévy distribution. + * + * @param shape - output shape + * @param mu - location parameter + * @param c - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.levy( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.levy.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.levy.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + levy: typeof levy; + + /** + * Generates pseudorandom numbers drawn from a logistic distribution. + * + * @param shape - output shape + * @param mu - mean parameter + * @param s - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.logistic( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.logistic.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.logistic.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + logistic: typeof logistic; + + /** + * Generates pseudorandom numbers drawn from a lognormal distribution. + * + * @param shape - output shape + * @param mu - location parameter + * @param sigma - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.lognormal( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.lognormal.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.lognormal.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + lognormal: typeof lognormal; + + /** + * Generates pseudorandom numbers drawn from a negative binomial distribution. + * + * @param shape - output shape + * @param r - number of successes until experiment is stopped + * @param p - success probability + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.negativeBinomial( [ 3, 3 ], 17, 0.5 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.negativeBinomial.assign( 17, 0.5, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.negativeBinomial.factory(); + * + * var out = random( [ 3, 3 ], 17, 0.5 ); + * // returns + */ + negativeBinomial: typeof negativeBinomial; + + /** + * Generates pseudorandom numbers drawn from a normal distribution. + * + * @param shape - output shape + * @param mu - mean + * @param sigma - standard deviation + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.normal( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.normal.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.normal.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + normal: typeof normal; + + /** + * Generates pseudorandom numbers drawn from a Pareto (Type I) distribution. + * + * @param shape - output shape + * @param alpha - shape parameter + * @param beta - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.pareto1( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.pareto1.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.pareto1.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + pareto1: typeof pareto1; /** * Samples elements from an array-like object. @@ -141,7 +842,7 @@ interface Namespace { tools: typeof tools; /** - * Generates pseudorandom numbers drawn from a uniform distribution. + * Generates pseudorandom numbers drawn from a continuous uniform distribution. * * @param shape - output shape * @param a - minimum support (inclusive) @@ -173,6 +874,40 @@ interface Namespace { * // returns */ uniform: typeof uniform; + + /** + * Generates pseudorandom numbers drawn from a Weibull distribution. + * + * @param shape - output shape + * @param k - shape parameter + * @param lambda - scale parameter + * @param options - function options + * @throws distribution parameters and the output shape must be broadcast compatible + * @returns output ndarray + * + * @example + * var out = ns.weibull( [ 3, 3 ], 2.0, 5.0 ); + * // returns + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = zeros( [ 3, 3 ] ); + * // returns + * + * var v = ns.weibull.assign( 2.0, 5.0, out ); + * // returns + * + * var bool = ( v === out ); + * // returns true + * + * @example + * var random = ns.weibull.factory(); + * + * var out = random( [ 3, 3 ], 2.0, 5.0 ); + * // returns + */ + weibull: typeof weibull; } /**