docs: improve README examples of stats/base/dists/gamma namespace

PR-URL: #1804 Ref: #1627 Co-authored-by: Philipp Burckhardt <[email protected]> Co-authored-by: shivam Ahir <[email protected]> Reviewed-by: Philipp Burckhardt <[email protected]>
stdlib-js · Oct 10, 2024 · e399bfd · kgryte · Oct 16, 2024 · kgryte
1 parent 6c3b249
commit e399bfd
Show file tree

Hide file tree

Showing 2 changed files with 166 additions and 4 deletions.
diff --git a/lib/node_modules/@stdlib/stats/base/dists/gamma/README.md b/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>

diff --git a/lib/node_modules/@stdlib/stats/base/dists/gamma/examples/index.js b/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 );