Merge branch 'stdlib-js:develop' into dnannsumors-refactor

CONTRIBUTORS

@@ -28,6 +28,7 @@ EuniceSim142 <[email protected]>
 Frank Kovacs <[email protected]>
 Golden Kumar <[email protected]>
 Gunj Joshi <[email protected]>
+Gururaj Gurram <[email protected]>
 HarshaNP <[email protected]>
 Harshita Kalani <[email protected]>
 Hridyanshu <[email protected]>

lib/node_modules/@stdlib/math/base/special/max/lib/native.js

@@ -26,7 +26,7 @@ var addon = require( './../src/addon.node' );
 // MAIN //
 
 /**
-* Return the maximum value.
+* Returns the maximum value.
 *
 * @private
 * @param {number} x - first number

lib/node_modules/@stdlib/math/base/special/min/lib/native.js

@@ -26,7 +26,7 @@ var addon = require( './../src/addon.node' );
 // MAIN //
 
 /**
-* Return the minimum value.
+* Returns the minimum value.
 *
 * @private
 * @param {number} x - first number

lib/node_modules/@stdlib/stats/base/dists/chi/README.md

@@ -101,15 +101,91 @@ var mu = dist.mean;
 
 ## Examples
 
-<!-- TODO: better examples -->
-
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var objectKeys = require( '@stdlib/utils/keys' );
+var chiRandomFactory = require( '@stdlib/random/base/chi' ).factory;
+var filledarrayBy = require( '@stdlib/array/filled-by' );
+var variance = require( '@stdlib/stats/base/variance' );
+var linspace = require( '@stdlib/array/base/linspace' );
+var rayleigh = require( '@stdlib/stats/base/dists/rayleigh' );
+var mean = require( '@stdlib/stats/base/mean' );
+var abs = require( '@stdlib/math/base/special/abs' );
 var chi = require( '@stdlib/stats/base/dists/chi' );
 
-console.log( objectKeys( chi ) );
+// Define the degrees of freedom parameter:
+var k = 2;
+
+// Generate an array of x values:
+var x = linspace( 0, 10, 100 );
+
+// Compute the PDF for each x:
+var chiPDF = chi.pdf.factory( k );
+var pdf = filledarrayBy( x.length, 'float64', chiPDF );
+
+// Compute the CDF for each x:
+var chiCDF = chi.cdf.factory( k );
+var cdf = filledarrayBy( x.length, 'float64', chiCDF );
+
+// Output the PDF and CDF values:
+console.log( 'x values:', x );
+console.log( 'PDF values:', pdf );
+console.log( 'CDF values:', cdf );
+
+// Compute statistical properties:
+var theoreticalMean = chi.mean( k );
+var theoreticalVariance = chi.variance( k );
+var theoreticalSkewness = chi.skewness( k );
+var theoreticalKurtosis = chi.kurtosis( k );
+
+console.log( 'Theoretical Mean:', theoreticalMean );
+console.log( 'Theoretical Variance:', theoreticalVariance );
+console.log( 'Skewness:', theoreticalSkewness );
+console.log( 'Kurtosis:', theoreticalKurtosis );
+
+// Generate random samples from the Chi distribution:
+var rchi = chiRandomFactory( k );
+var n = 1000;
+var samples = filledarrayBy( n, 'float64', rchi );
+
+// Compute sample mean and variance:
+var sampleMean = mean( n, samples, 1 );
+var sampleVariance = variance( n, 1, samples, 1 );
+
+console.log( 'Sample Mean:', sampleMean );
+console.log( 'Sample Variance:', sampleVariance );
+
+// Compare sample statistics to theoretical values:
+console.log( 'Difference in Mean:', abs( theoreticalMean - sampleMean ) );
+console.log( 'Difference in Variance:', abs( theoreticalVariance - sampleVariance ) );
+
+// Demonstrate the relationship with the Rayleigh distribution when k=2:
+var rayleighPDF = rayleigh.pdf.factory( 1.0 );
+var rayleighCDF = rayleigh.cdf.factory( 1.0 );
+
+// Compute Rayleigh PDF and CDF for each x:
+var rayleighPDFValues = filledarrayBy( x.length, 'float64', rayleighPDF );
+
+var rayleighCDFValues = filledarrayBy( x.length, 'float64', rayleighCDF );
+
+// Compare Chi and Rayleigh PDFs and CDFs:
+var maxDiffPDF = 0.0;
+var maxDiffCDF = 0.0;
+var diffPDF;
+var diffCDF;
+var i;
+for ( i = 0; i < x.length; i++ ) {
+ diffPDF = abs( pdf[ i ] - rayleighPDFValues[ i ] );
+ if ( diffPDF > maxDiffPDF ) {
+ maxDiffPDF = diffPDF;
+ }
+ diffCDF = abs( cdf[ i ] - rayleighCDFValues[ i ] );
+ if ( diffCDF > maxDiffCDF ) {
+ maxDiffCDF = diffCDF;
+ }
+}
+console.log( 'Maximum difference between Chi(k=2) PDF and Rayleigh PDF:', maxDiffPDF );
+console.log( 'Maximum difference between Chi(k=2) CDF and Rayleigh CDF:', maxDiffCDF );
 ```
 
 </section>

lib/node_modules/@stdlib/stats/base/dists/chi/examples/index.js

@@ -18,7 +18,85 @@
 
 'use strict';
 
-var objectKeys = require( '@stdlib/utils/keys' );
+var chiRandomFactory = require( '@stdlib/random/base/chi' ).factory;
+var filledarrayBy = require( '@stdlib/array/filled-by' );
+var variance = require( '@stdlib/stats/base/variance' );
+var linspace = require( '@stdlib/array/base/linspace' );
+var rayleigh = require( '@stdlib/stats/base/dists/rayleigh' );
+var mean = require( '@stdlib/stats/base/mean' );
+var abs = require( '@stdlib/math/base/special/abs' );
 var chi = require( './../lib' );
 
-console.log( objectKeys( chi ) );
+// Define the degrees of freedom parameter:
+var k = 2;
+
+// Generate an array of x values:
+var x = linspace( 0, 10, 100 );
+
+// Compute the PDF for each x:
+var chiPDF = chi.pdf.factory( k );
+var pdf = filledarrayBy( x.length, 'float64', chiPDF );
+
+// Compute the CDF for each x:
+var chiCDF = chi.cdf.factory( k );
+var cdf = filledarrayBy( x.length, 'float64', chiCDF );
+
+// Output the PDF and CDF values:
+console.log( 'x values:', x );
+console.log( 'PDF values:', pdf );
+console.log( 'CDF values:', cdf );
+
+// Compute statistical properties:
+var theoreticalMean = chi.mean( k );
+var theoreticalVariance = chi.variance( k );
+var theoreticalSkewness = chi.skewness( k );
+var theoreticalKurtosis = chi.kurtosis( k );
+
+console.log( 'Theoretical Mean:', theoreticalMean );
+console.log( 'Theoretical Variance:', theoreticalVariance );
+console.log( 'Skewness:', theoreticalSkewness );
+console.log( 'Kurtosis:', theoreticalKurtosis );
+
+// Generate random samples from the Chi distribution:
+var rchi = chiRandomFactory( k );
+var n = 1000;
+var samples = filledarrayBy( n, 'float64', rchi );
+
+// Compute sample mean and variance:
+var sampleMean = mean( n, samples, 1 );
+var sampleVariance = variance( n, 1, samples, 1 );
+
+console.log( 'Sample Mean:', sampleMean );
+console.log( 'Sample Variance:', sampleVariance );
+
+// Compare sample statistics to theoretical values:
+console.log( 'Difference in Mean:', abs( theoreticalMean - sampleMean ) );
+console.log( 'Difference in Variance:', abs( theoreticalVariance - sampleVariance ) );
+
+// Demonstrate the relationship with the Rayleigh distribution when k=2:
+var rayleighPDF = rayleigh.pdf.factory( 1.0 );
+var rayleighCDF = rayleigh.cdf.factory( 1.0 );
+
+// Compute Rayleigh PDF and CDF for each x:
+var rayleighPDFValues = filledarrayBy( x.length, 'float64', rayleighPDF );
+
+var rayleighCDFValues = filledarrayBy( x.length, 'float64', rayleighCDF );
+
+// Compare Chi and Rayleigh PDFs and CDFs:
+var maxDiffPDF = 0.0;
+var maxDiffCDF = 0.0;
+var diffPDF;
+var diffCDF;
+var i;
+for ( i = 0; i < x.length; i++ ) {
+ diffPDF = abs( pdf[ i ] - rayleighPDFValues[ i ] );
+ if ( diffPDF > maxDiffPDF ) {
+ maxDiffPDF = diffPDF;
+ }
+ diffCDF = abs( cdf[ i ] - rayleighCDFValues[ i ] );
+ if ( diffCDF > maxDiffCDF ) {
+ maxDiffCDF = diffCDF;
+ }
+}
+console.log( 'Maximum difference between Chi(k=2) PDF and Rayleigh PDF:', maxDiffPDF );
+console.log( 'Maximum difference between Chi(k=2) CDF and Rayleigh CDF:', maxDiffCDF );

lib/node_modules/@stdlib/stats/base/dists/gamma/README.md

@@ -108,10 +108,91 @@ var y = dist.cdf( 0.5 );
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var objectKeys = require( '@stdlib/utils/keys' );
+var gammaRandomFactory = require( '@stdlib/random/base/gamma' ).factory;
+var filledarrayby = require( '@stdlib/array/filled-by' );
+var Float64Array = require( '@stdlib/array/float64' );
+var variance = require( '@stdlib/stats/base/variance' );
+var linspace = require( '@stdlib/array/base/linspace' );
+var mean = require( '@stdlib/stats/base/mean' );
+var abs = require( '@stdlib/math/base/special/abs' );
 var gamma = require( '@stdlib/stats/base/dists/gamma' );
 
-console.log( objectKeys( gamma ) );
+// Define the shape and scale parameters:
+var alpha = 3.0; // shape parameter (α)
+var beta = 2.0; // scale parameter (β)
+
+// Generate an array of x values:
+var x = linspace( 0.0, 20.0, 100 );
+
+// Compute the PDF for each x:
+var gammaPDF = gamma.pdf.factory( alpha, beta );
+var pdf = filledarrayby( x.length, 'float64', gammaPDF );
+
+// Compute the CDF for each x:
+var gammaCDF = gamma.cdf.factory( alpha, beta );
+var cdf = filledarrayby( x.length, 'float64', gammaCDF );
+
+// Output the PDF and CDF values:
+console.log( 'x values:', x );
+console.log( 'PDF values:', pdf );
+console.log( 'CDF values:', cdf );
+
+// Compute statistical properties:
+var theoreticalMean = gamma.mean( alpha, beta );
+var theoreticalVariance = gamma.variance( alpha, beta );
+var theoreticalSkewness = gamma.skewness( alpha, beta );
+var theoreticalKurtosis = gamma.kurtosis( alpha, beta );
+
+console.log( 'Theoretical Mean:', theoreticalMean );
+console.log( 'Theoretical Variance:', theoreticalVariance );
+console.log( 'Skewness:', theoreticalSkewness );
+console.log( 'Kurtosis:', theoreticalKurtosis );
+
+// Generate random samples from the gamma distribution:
+var rgamma = gammaRandomFactory( alpha, beta );
+var n = 300;
+var samples = filledarrayby( n, 'float64', rgamma );
+
+// Compute sample mean and variance:
+var sampleMean = mean( n, samples, 1 );
+var sampleVariance = variance( n, 1, samples, 1 );
+
+console.log( 'Sample Mean:', sampleMean );
+console.log( 'Sample Variance:', sampleVariance );
+
+// Compare sample statistics to theoretical values:
+console.log( 'Difference in Mean:', abs( theoreticalMean - sampleMean ) );
+console.log( 'Difference in Variance:', abs( theoreticalVariance - sampleVariance ) );
+
+// Demonstrate that the sum of `k` gamma variables is a gamma-distributed sum of `k` gamma(α, β) variables with same β is `gamma(k*α, β)`:
+var k = 5;
+var sumSamples = new Float64Array( n );
+
+var sum;
+var i;
+var j;
+for ( i = 0; i < sumSamples.length; i++ ) {
+ sum = 0.0;
+ for ( j = 0; j < k; j++ ) {
+ sum += rgamma();
+ }
+ sumSamples[ i ] = sum;
+}
+
+// Theoretical parameters for the sum:
+var sumAlpha = k * alpha;
+var sumMean = gamma.mean( sumAlpha, beta );
+var sumVariance = gamma.variance( sumAlpha, beta );
+
+console.log( 'Sum Theoretical Mean:', sumMean );
+console.log( 'Sum Theoretical Variance:', sumVariance );
+
+// Compute sample mean and variance for the sum:
+var sumSampleMean = mean( sumSamples.length, sumSamples, 1 );
+var sumSampleVariance = variance( sumSamples.length, 1, sumSamples, 1 );
+
+console.log( 'Sum Sample Mean:', sumSampleMean );
+console.log( 'Sum Sample Variance:', sumSampleVariance );
 ```
 
 </section>

lib/node_modules/@stdlib/stats/base/dists/gamma/examples/index.js

@@ -18,7 +18,88 @@
 
 'use strict';
 
-var objectKeys = require( '@stdlib/utils/keys' );
+var gammaRandomFactory = require( '@stdlib/random/base/gamma' ).factory;
+var filledarrayby = require( '@stdlib/array/filled-by' );
+var Float64Array = require( '@stdlib/array/float64' );
+var variance = require( '@stdlib/stats/base/variance' );
+var linspace = require( '@stdlib/array/base/linspace' );
+var mean = require( '@stdlib/stats/base/mean' );
+var abs = require( '@stdlib/math/base/special/abs' );
 var gamma = require( './../lib' );
 
-console.log( objectKeys( gamma ) );
+// Define the shape and scale parameters:
+var alpha = 3.0; // shape parameter (α)
+var beta = 2.0; // scale parameter (β)
+
+// Generate an array of x values:
+var x = linspace( 0.0, 20.0, 100 );
+
+// Compute the PDF for each x:
+var gammaPDF = gamma.pdf.factory( alpha, beta );
+var pdf = filledarrayby( x.length, 'float64', gammaPDF );
+
+// Compute the CDF for each x:
+var gammaCDF = gamma.cdf.factory( alpha, beta );
+var cdf = filledarrayby( x.length, 'float64', gammaCDF );
+
+// Output the PDF and CDF values:
+console.log( 'x values:', x );
+console.log( 'PDF values:', pdf );
+console.log( 'CDF values:', cdf );
+
+// Compute statistical properties:
+var theoreticalMean = gamma.mean( alpha, beta );
+var theoreticalVariance = gamma.variance( alpha, beta );
+var theoreticalSkewness = gamma.skewness( alpha, beta );
+var theoreticalKurtosis = gamma.kurtosis( alpha, beta );
+
+console.log( 'Theoretical Mean:', theoreticalMean );
+console.log( 'Theoretical Variance:', theoreticalVariance );
+console.log( 'Skewness:', theoreticalSkewness );
+console.log( 'Kurtosis:', theoreticalKurtosis );
+
+// Generate random samples from the gamma distribution:
+var rgamma = gammaRandomFactory( alpha, beta );
+var n = 300;
+var samples = filledarrayby( n, 'float64', rgamma );
+
+// Compute sample mean and variance:
+var sampleMean = mean( n, samples, 1 );
+var sampleVariance = variance( n, 1, samples, 1 );
+
+console.log( 'Sample Mean:', sampleMean );
+console.log( 'Sample Variance:', sampleVariance );
+
+// Compare sample statistics to theoretical values:
+console.log( 'Difference in Mean:', abs( theoreticalMean - sampleMean ) );
+console.log( 'Difference in Variance:', abs( theoreticalVariance - sampleVariance ) );
+
+// Demonstrate that the sum of `k` gamma variables is a gamma-distributed sum of `k` gamma(α, β) variables with same β is `gamma(k*α, β)`:
+var k = 5;
+var sumSamples = new Float64Array( n );
+
+var sum;
+var i;
+var j;
+for ( i = 0; i < sumSamples.length; i++ ) {
+ sum = 0.0;
+ for ( j = 0; j < k; j++ ) {
+ sum += rgamma();
+ }
+ sumSamples[ i ] = sum;
+}
+
+// Theoretical parameters for the sum:
+var sumAlpha = k * alpha;
+var sumMean = gamma.mean( sumAlpha, beta );
+var sumVariance = gamma.variance( sumAlpha, beta );
+
+console.log( 'Sum Theoretical Mean:', sumMean );
+console.log( 'Sum Theoretical Variance:', sumVariance );
+
+// Compute sample mean and variance for the sum:
+var sumSampleMean = mean( sumSamples.length, sumSamples, 1 );
+var sumSampleVariance = variance( sumSamples.length, 1, sumSamples, 1 );
+
+console.log( 'Sum Sample Mean:', sumSampleMean );
+console.log( 'Sum Sample Variance:', sumSampleVariance );