feat!: refactor Bartlett's test to return a class instance

lib/node_modules/@stdlib/stats/bartlett-test/README.md

@@ -55,9 +55,9 @@ where `N` is the total number of observations, `S_i` are the biased group-level
 var bartlettTest = require( '@stdlib/stats/bartlett-test' );
 ```
 
-#### bartlettTest( a\[,b,...,k]\[, opts] )
+#### bartlettTest( a\[,b,...,k]\[, options] )
 
-For input arrays `a`, `b`, ... holding numeric observations, this function calculates Bartlett’s test, which tests the null hypothesis that the variances in all `k` groups are the same. 
+For input arrays `a`, `b`, ... holding numeric observations, this function calculates Bartlett’s test, which tests the null hypothesis that the variances in all `k` groups are the same.
 
 ```javascript
 // Data from Hollander & Wolfe (1973), p. 116:
@@ -125,16 +125,30 @@ var out = bartlettTest( arr, {
 });
 ```
 
-The returned object comes with a `.print()` method which when invoked will print a formatted output of the results of the hypothesis test. `print` accepts a `digits` option that controls the number of decimal digits displayed for the outputs and a `decision` option, which when set to `false` will hide the test decision.
+The function returns a results `object` having the following properties:
+
+-   **alpha**: significance level.
+-   **rejected**: `boolean` indicating the test decision.
+-   **pValue**: test p-value.
+-   **statistic**: test statistic.
+-   **df**: degrees of freedom.
+-   **method**: test name.
+-   **toString**: serializes results as formatted test output.
+-   **toJSON**: serializes results as a JSON object.
+
+To print formatted test output, invoke the `toString` method. The method accepts the following options:
+
+-   **digits**: number of displayed decimal digits. Default: `4`.
+-   **decision**: `boolean` indicating whether to show the test decision. Default: `true`.
 
 ```javascript
 var x = [ 2.9, 3.0, 2.5, 2.6, 3.2 ];
 var y = [ 3.8, 2.7, 4.0, 2.4 ];
 var z = [ 2.8, 3.4, 3.7, 2.2, 2.0 ];
 
 var out = bartlettTest( x, y, z );
-console.log( out.print() );
-/* =>
+var table = out.toString();
+/* e.g., returns
     Bartlett's test of equal variances
 
     Null hypothesis: The variances in all groups are the same.
@@ -177,7 +191,7 @@ var out = bartlettTest( x, y, z );
     }
 */
 
-var table = out.print();
+var table = out.toString();
 /* returns
     Bartlett's test of equal variances
 

lib/node_modules/@stdlib/stats/bartlett-test/benchmark/benchmark.js

@@ -21,10 +21,12 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var randu = require( '@stdlib/random/base/randu' );
-var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var isObject = require( '@stdlib/assert/is-object' );
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var Float64Array = require( '@stdlib/array/float64' );
 var pkg = require( './../package.json' ).name;
 var bartlettTest = require( './../lib' );
 
@@ -33,21 +35,14 @@ var bartlettTest = require( './../lib' );
 
 bench( pkg, function benchmark( b ) {
 	var result;
-	var len;
 	var x;
 	var y;
 	var z;
 	var i;
 
-	x = new Array( 50 );
-	y = new Array( 50 );
-	z = new Array( 50 );
-	len = x.length;
-	for ( i = 0; i < len; i++ ) {
-		x[ i ] = ( randu()*50.0 );
-		y[ i ] = ( randu()*50.0 ) + 10.0;
-		z[ i ] = ( randu()*50.0 ) + 20.0;
-	}
+	x = uniform( 50, 0.0, 50.0 );
+	y = uniform( 50, 10.0, 60.0 );
+	z = uniform( 50, 20.0, 70.0 );
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
@@ -72,11 +67,10 @@ bench( pkg+'::groups', function benchmark( b ) {
 	var len;
 	var i;
 
-	vals = new Array( 150 );
-	group = new Array( 150 );
-	len = vals.length;
+	len = 150;
+	group = discreteUniform( 150, 0, 2 );
+	vals = new Float64Array( len );
 	for ( i = 0; i < len; i++ ) {
-		group[ i ] = discreteUniform( 0, 2 );
 		vals[ i ] = ( randu()*50.0 ) + ( 10.0*group[ i ] );
 	}
 
@@ -98,7 +92,7 @@ bench( pkg+'::groups', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+':print', function benchmark( b ) {
+bench( pkg+':toString', function benchmark( b ) {
 	var digits;
 	var result;
 	var output;
@@ -107,11 +101,10 @@ bench( pkg+':print', function benchmark( b ) {
 	var len;
 	var i;
 
-	vals = new Array( 100 );
-	group = new Array( 100 );
-	len = vals.length;
+	len = 100;
+	group = discreteUniform( len, 0, 2 );
+	vals = new Float64Array( len );
 	for ( i = 0; i < len; i++ ) {
-		group[ i ] = discreteUniform( 0, 2 );
 		vals[ i ] = ( randu()*50.0 ) + ( 10.0*group[ i ] );
 	}
 	result = bartlettTest( vals, {
@@ -121,7 +114,7 @@ bench( pkg+':print', function benchmark( b ) {
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
 		digits = ( i % 8 ) + 1;
-		output = result.print({
+		output = result.toString({
 			'digits': digits
 		});
 		if ( typeof output !== 'string' ) {

lib/node_modules/@stdlib/stats/bartlett-test/docs/repl.txt

@@ -20,7 +20,7 @@
     Returns
     -------
     out: Object
-        Test result object.
+        Test results object.
 
     out.alpha: number
         Significance level.
@@ -40,8 +40,11 @@
     out.df: Object
         Degrees of freedom.
 
-    out.print: Function
-        Function to print formatted output.
+    out.toString: Function
+        Serializes results as formatted output.
+
+    out.toJSON: Function
+        Serializes results as JSON.
 
     Examples
     --------
@@ -50,7 +53,8 @@
     > var y = [ 3.8, 2.7, 4.0, 2.4 ];
     > var z = [ 2.8, 3.4, 3.7, 2.2, 2.0 ];
 
-    > var out = {{alias}}( x, y, z )
+    > var out = {{alias}}( x, y, z );
+    > out.toString()
 
     > var arr = [ 2.9, 3.0, 2.5, 2.6, 3.2,
     ...     3.8, 2.7, 4.0, 2.4,
@@ -61,7 +65,8 @@
     ...     'b', 'b', 'b', 'b',
     ...     'c', 'c', 'c', 'c', 'c'
     ... ];
-    > out = {{alias}}( arr, { 'groups': groups } )
+    > out = {{alias}}( arr, { 'groups': groups } );
+    > out.toString()
 
     See Also
     --------

lib/node_modules/@stdlib/stats/bartlett-test/docs/types/index.d.ts

@@ -22,6 +22,7 @@
 
 import { NumericArray } from '@stdlib/types/array';
 
+
 /**
 * Interface defining function options.
 */
@@ -34,7 +35,7 @@
 	/**
 	* Array of group indicators.
 	*/
 	groups?: Array<any>;
 }
 
 /**
@@ -72,9 +73,14 @@
 	df: number;
 
 	/**
-	* Function to print formatted output.
+	* Serializes results as formatted test output.
+	*/
+	toString: Function; // FIXME: provide better type
+
+	/**
+	* Serializes results as JSON.
 	*/
-	print: Function;
+	toJSON: Function; // FIXME: provide better type
 }
 
 /**

lib/node_modules/@stdlib/stats/bartlett-test/examples/index.js

@@ -30,5 +30,5 @@ console.log( 'Output object: ' );
 console.dir( out );
 console.log( '\n' );
 
-var table = out.print();
+var table = out.toString();
 console.log( table );

lib/node_modules/@stdlib/stats/bartlett-test/lib/main.js

@@ -22,15 +22,16 @@
 
 var isCollection = require( '@stdlib/assert/is-collection' );
 var isPlainObject = require( '@stdlib/assert/is-plain-object' );
-var setReadOnly = require( '@stdlib/utils/define-read-only-property' );
 var objectKeys = require( '@stdlib/utils/keys' );
 var format = require( '@stdlib/string/format' );
 var chisqCDF = require( '@stdlib/stats/base/dists/chisquare/cdf' );
 var group = require( '@stdlib/utils/group' );
 var ln = require( '@stdlib/math/base/special/ln' );
-var variance = require( './variance.js' );
+var Int32Array = require( '@stdlib/array/int32' );
+var Float64Array = require( '@stdlib/array/float64' );
+var dvariance = require( '@stdlib/stats/base/dvariance' );
 var validate = require( './validate.js' );
-var print = require( './print.js' ); // eslint-disable-line stdlib/no-redeclare
+var Results = require( './results.js' );
 
 
 // MAIN //
@@ -74,7 +75,6 @@ function bartlett() {
 	var arg;
 	var err;
 	var lnv;
-	var out;
 	var df;
 	var n;
 	var v;
@@ -110,8 +110,8 @@ function bartlett() {
 	ninvSum = 0.0;
 	vSum = 0.0;
 	lnv = 0.0;
-	n = new Array( ngroups );
-	v = n.slice();
+	n = new Int32Array( ngroups );
+	v = new Float64Array( ngroups );
 	for ( i = 0; i < ngroups; i++ ) {
 		arg = args[ i ];
 		if ( !isCollection( arg ) ) {
@@ -123,7 +123,7 @@ function bartlett() {
 		n[ i ] = arg.length - 1;
 		nSum += n[ i ];
 		ninvSum += 1.0 / n[ i ];
-		v[ i ] = variance( arg );
+		v[ i ] = dvariance( arg.length, 1, arg, 1 );
 		vSum += ( n[ i ] * v[ i ] );
 		lnv += n[ i ] * ln( v[ i ] );
 	}
@@ -142,15 +142,7 @@ function bartlett() {
 	df = ngroups - 1;
 	pval = 1.0 - chisqCDF( stat, df );
 
-	out = {};
-	setReadOnly( out, 'rejected', pval <= alpha );
-	setReadOnly( out, 'alpha', alpha );
-	setReadOnly( out, 'pValue', pval );
-	setReadOnly( out, 'statistic', stat );
-	setReadOnly( out, 'df', df );
-	setReadOnly( out, 'method', 'Bartlett\'s test of equal variances' );
-	setReadOnly( out, 'print', print );
-	return out;
+	return new Results( pval, alpha, stat, df );
 }