@stdlib/stats-strided-dvariancewd 0.1.0

package/lib/main.js

@@ -0,0 +1,35 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var dvariancewd = require( './dvariancewd.js' );
+var ndarray = require( './ndarray.js' );
+
+
+// MAIN //
+
+setReadOnly( dvariancewd, 'ndarray', ndarray );
+
+
+// EXPORTS //
+
+module.exports = dvariancewd;

package/lib/native.js

@@ -0,0 +1,35 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var dvariancewd = require( './dvariancewd.native.js' );
+var ndarray = require( './ndarray.native.js' );
+
+
+// MAIN //
+
+setReadOnly( dvariancewd, 'ndarray', ndarray );
+
+
+// EXPORTS //
+
+module.exports = dvariancewd;

package/lib/ndarray.js

@@ -0,0 +1,112 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MAIN //
+
+/**
+* Computes the variance of a double-precision floating-point strided array using Welford's algorithm.
+*
+* ## Method
+*
+* -   This implementation uses Welford's algorithm for efficient computation, which can be derived as follows. Let
+*
+*     ```tex
+*     \begin{align*}
+*     S_n &= n \sigma_n^2 \\
+*         &= \sum_{i=1}^{n} (x_i - \mu_n)^2 \\
+*         &= \biggl(\sum_{i=1}^{n} x_i^2 \biggr) - n\mu_n^2
+*     \end{align*}
+*     ```
+*
+*     Accordingly,
+*
+*     ```tex
+*     \begin{align*}
+*     S_n - S_{n-1} &= \sum_{i=1}^{n} x_i^2 - n\mu_n^2 - \sum_{i=1}^{n-1} x_i^2 + (n-1)\mu_{n-1}^2 \\
+*                   &= x_n^2 - n\mu_n^2 + (n-1)\mu_{n-1}^2 \\
+*                   &= x_n^2 - \mu_{n-1}^2 + n(\mu_{n-1}^2 - \mu_n^2) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + n(\mu_{n-1} - \mu_n)(\mu_{n-1} + \mu_n) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + (\mu_{n-1} - x_n)(\mu_{n-1} + \mu_n) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + \mu_{n-1}^2 - x_n\mu_n - x_n\mu_{n-1} + \mu_n\mu_{n-1} \\
+*                   &= x_n^2 - x_n\mu_n - x_n\mu_{n-1} + \mu_n\mu_{n-1} \\
+*                   &= (x_n - \mu_{n-1})(x_n - \mu_n) \\
+*                   &= S_{n-1} + (x_n - \mu_{n-1})(x_n - \mu_n)
+*     \end{align*}
+*     ```
+*
+*     where we use the identity
+*
+*     ```tex
+*     x_n - \mu_{n-1} = n (\mu_n - \mu_{n-1})
+*     ```
+*
+* ## References
+*
+* -   Welford, B. P. 1962. "Note on a Method for Calculating Corrected Sums of Squares and Products." _Technometrics_ 4 (3). Taylor & Francis: 419–20. doi:[10.1080/00401706.1962.10490022](https://doi.org/10.1080/00401706.1962.10490022).
+* -   van Reeken, A. J. 1968. "Letters to the Editor: Dealing with Neely's Algorithms." _Communications of the ACM_ 11 (3): 149–50. doi:[10.1145/362929.362961](https://doi.org/10.1145/362929.362961).
+*
+* @param {PositiveInteger} N - number of indexed elements
+* @param {number} correction - degrees of freedom adjustment
+* @param {Float64Array} x - input array
+* @param {integer} strideX - stride length
+* @param {NonNegativeInteger} offsetX - starting index
+* @returns {number} variance
+*
+* @example
+* var Float64Array = require( '@stdlib/array-float64' );
+*
+* var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
+*
+* var v = dvariancewd( 4, 1, x, 2, 1 );
+* // returns 6.25
+*/
+function dvariancewd( N, correction, x, strideX, offsetX ) {
+	var delta;
+	var mu;
+	var M2;
+	var ix;
+	var v;
+	var n;
+	var i;
+
+	n = N - correction;
+	if ( N <= 0 || n <= 0.0 ) {
+		return NaN;
+	}
+	if ( N === 1 || strideX === 0 ) {
+		return 0.0;
+	}
+	ix = offsetX;
+	M2 = 0.0;
+	mu = 0.0;
+	for ( i = 0; i < N; i++ ) {
+		v = x[ ix ];
+		delta = v - mu;
+		mu += delta / (i+1);
+		M2 += delta * ( v - mu );
+		ix += strideX;
+	}
+	return M2 / n;
+}
+
+
+// EXPORTS //
+
+module.exports = dvariancewd;

package/lib/ndarray.native.js

@@ -0,0 +1,53 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var addon = require( './../src/addon.node' );
+
+
+// MAIN //
+
+/**
+* Computes the variance of a double-precision floating-point strided array using Welford's algorithm.
+*
+* @param {PositiveInteger} N - number of indexed elements
+* @param {number} correction - degrees of freedom adjustment
+* @param {Float64Array} x - input array
+* @param {integer} strideX - stride length
+* @param {NonNegativeInteger} offsetX - starting index
+* @returns {number} variance
+*
+* @example
+* var Float64Array = require( '@stdlib/array-float64' );
+*
+* var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
+*
+* var v = dvariancewd( 4, 1, x, 2, 1 );
+* // returns 6.25
+*/
+function dvariancewd( N, correction, x, strideX, offsetX ) {
+	return addon.ndarray( N, correction, x, strideX, offsetX );
+}
+
+
+// EXPORTS //
+
+module.exports = dvariancewd;

package/manifest.json

@@ -0,0 +1,100 @@
+{
+  "options": {
+    "task": "build",
+    "wasm": false
+  },
+  "fields": [
+    {
+      "field": "src",
+      "resolve": true,
+      "relative": true
+    },
+    {
+      "field": "include",
+      "resolve": true,
+      "relative": true
+    },
+    {
+      "field": "libraries",
+      "resolve": false,
+      "relative": false
+    },
+    {
+      "field": "libpath",
+      "resolve": true,
+      "relative": false
+    }
+  ],
+  "confs": [
+    {
+      "task": "build",
+      "wasm": false,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/blas-base-shared",
+        "@stdlib/strided-base-stride2offset",
+        "@stdlib/napi-export",
+        "@stdlib/napi-argv",
+        "@stdlib/napi-argv-int64",
+        "@stdlib/napi-argv-double",
+        "@stdlib/napi-argv-strided-float64array",
+        "@stdlib/napi-create-double"
+      ]
+    },
+    {
+      "task": "benchmark",
+      "wasm": false,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/blas-base-shared",
+        "@stdlib/strided-base-stride2offset"
+      ]
+    },
+    {
+      "task": "examples",
+      "wasm": false,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/blas-base-shared",
+        "@stdlib/strided-base-stride2offset"
+      ]
+    },
+    {
+      "task": "",
+      "wasm": true,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/blas-base-shared",
+        "@stdlib/strided-base-stride2offset"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@stdlib/stats-strided-dvariancewd",
+  "version": "0.1.0",
+  "description": "Calculate the variance of a double-precision floating-point strided array using Welford's algorithm.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "browser": "./lib/main.js",
+  "gypfile": false,
+  "directories": {
+    "doc": "./docs",
+    "include": "./include",
+    "lib": "./lib",
+    "src": "./src",
+    "dist": "./dist"
+  },
+  "types": "./docs/types",
+  "scripts": {},
+  "homepage": "https://stdlib.io",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stats-strided-dvariancewd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {
+    "@stdlib/assert-is-error": "^0.2.2",
+    "@stdlib/blas-base-shared": "^0.1.0",
+    "@stdlib/napi-argv": "^0.2.2",
+    "@stdlib/napi-argv-double": "^0.2.1",
+    "@stdlib/napi-argv-int64": "^0.2.2",
+    "@stdlib/napi-argv-strided-float64array": "^0.2.2",
+    "@stdlib/napi-create-double": "^0.0.2",
+    "@stdlib/napi-export": "^0.3.0",
+    "@stdlib/strided-base-stride2offset": "^0.1.0",
+    "@stdlib/utils-define-nonenumerable-read-only-property": "^0.2.2",
+    "@stdlib/utils-library-manifest": "^0.2.3",
+    "@stdlib/utils-try-require": "^0.2.2"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "stdmath",
+    "statistics",
+    "stats",
+    "mathematics",
+    "math",
+    "variance",
+    "var",
+    "deviation",
+    "dispersion",
+    "sample variance",
+    "unbiased",
+    "stdev",
+    "std",
+    "standard deviation",
+    "welford",
+    "strided",
+    "strided array",
+    "typed",
+    "array",
+    "float64",
+    "double",
+    "float64array"
+  ],
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/stdlib"
+  }
+}

package/src/addon.c

@@ -0,0 +1,64 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+#include "stdlib/stats/strided/dvariancewd.h"
+#include "stdlib/blas/base/shared.h"
+#include "stdlib/napi/export.h"
+#include "stdlib/napi/argv.h"
+#include "stdlib/napi/argv_int64.h"
+#include "stdlib/napi/argv_strided_float64array.h"
+#include "stdlib/napi/create_double.h"
+#include "stdlib/napi/argv_double.h"
+#include <node_api.h>
+
+/**
+* Receives JavaScript callback invocation data.
+*
+* @param env    environment under which the function is invoked
+* @param info   callback data
+* @return       Node-API value
+*/
+static napi_value addon( napi_env env, napi_callback_info info ) {
+	STDLIB_NAPI_ARGV( env, info, argv, argc, 4 );
+	STDLIB_NAPI_ARGV_INT64( env, N, argv, 0 );
+	STDLIB_NAPI_ARGV_DOUBLE( env, correction, argv, 1 );
+	STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 3 );
+	STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 2 )
+	STDLIB_NAPI_CREATE_DOUBLE( env, API_SUFFIX(stdlib_strided_dvariancewd)( N, correction, X, strideX ), v );
+	return v;
+}
+
+/**
+* Receives JavaScript callback invocation data.
+*
+* @param env    environment under which the function is invoked
+* @param info   callback data
+* @return       Node-API value
+*/
+static napi_value addon_method( napi_env env, napi_callback_info info ) {
+	STDLIB_NAPI_ARGV( env, info, argv, argc, 5 );
+	STDLIB_NAPI_ARGV_INT64( env, N, argv, 0 );
+	STDLIB_NAPI_ARGV_DOUBLE( env, correction, argv, 1 );
+	STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 3 );
+	STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 2 );
+	STDLIB_NAPI_ARGV_INT64( env, offsetX, argv, 4 );
+	STDLIB_NAPI_CREATE_DOUBLE( env, API_SUFFIX(stdlib_strided_dvariancewd_ndarray)( N, correction, X, strideX, offsetX ), v );
+	return v;
+}
+
+STDLIB_NAPI_MODULE_EXPORT_FCN_WITH_METHOD( addon, "ndarray", addon_method )

package/src/main.c

@@ -0,0 +1,113 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+#include "stdlib/stats/strided/dvariancewd.h"
+#include "stdlib/blas/base/shared.h"
+#include "stdlib/strided/base/stride2offset.h"
+
+/**
+* Computes the variance of a double-precision floating-point strided array using Welford's algorithm.
+*
+* ## Method
+*
+* -   This implementation uses Welford's algorithm for efficient computation, which can be derived as follows. Let
+*
+*     ```tex
+*     \begin{align*}
+*     S_n &= n \sigma_n^2 \\
+*         &= \sum_{i=1}^{n} (x_i - \mu_n)^2 \\
+*         &= \biggl(\sum_{i=1}^{n} x_i^2 \biggr) - n\mu_n^2
+*     \end{align*}
+*     ```
+*
+*     Accordingly,
+*
+*     ```tex
+*     \begin{align*}
+*     S_n - S_{n-1} &= \sum_{i=1}^{n} x_i^2 - n\mu_n^2 - \sum_{i=1}^{n-1} x_i^2 + (n-1)\mu_{n-1}^2 \\
+*                   &= x_n^2 - n\mu_n^2 + (n-1)\mu_{n-1}^2 \\
+*                   &= x_n^2 - \mu_{n-1}^2 + n(\mu_{n-1}^2 - \mu_n^2) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + n(\mu_{n-1} - \mu_n)(\mu_{n-1} + \mu_n) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + (\mu_{n-1} - x_n)(\mu_{n-1} + \mu_n) \\
+*                   &= x_n^2 - \mu_{n-1}^2 + \mu_{n-1}^2 - x_n\mu_n - x_n\mu_{n-1} + \mu_n\mu_{n-1} \\
+*                   &= x_n^2 - x_n\mu_n - x_n\mu_{n-1} + \mu_n\mu_{n-1} \\
+*                   &= (x_n - \mu_{n-1})(x_n - \mu_n) \\
+*                   &= S_{n-1} + (x_n - \mu_{n-1})(x_n - \mu_n)
+*     \end{align*}
+*     ```
+*
+*     where we use the identity
+*
+*     ```tex
+*     x_n - \mu_{n-1} = n (\mu_n - \mu_{n-1})
+*     ```
+*
+* ## References
+*
+* -   Welford, B. P. 1962. "Note on a Method for Calculating Corrected Sums of Squares and Products." _Technometrics_ 4 (3). Taylor & Francis: 419–20. doi:[10.1080/00401706.1962.10490022](https://doi.org/10.1080/00401706.1962.10490022).
+* -   van Reeken, A. J. 1968. "Letters to the Editor: Dealing with Neely's Algorithms." _Communications of the ACM_ 11 (3): 149–50. doi:[10.1145/362929.362961](https://doi.org/10.1145/362929.362961).
+*
+* @param N            number of indexed elements
+* @param correction   degrees of freedom adjustment
+* @param X            input array
+* @param strideX      stride length
+* @return             output value
+*/
+double API_SUFFIX(stdlib_strided_dvariancewd)( const CBLAS_INT N, const double correction, const double *X, const CBLAS_INT strideX ) {
+	const CBLAS_INT ox = stdlib_strided_stride2offset( N, strideX );
+	return API_SUFFIX(stdlib_strided_dvariancewd_ndarray)( N, correction, X, strideX, ox );
+}
+
+/**
+* Computes the variance of a double-precision floating-point strided array using Welford's algorithm and alternative indexing semantics.
+*
+* @param N            number of indexed elements
+* @param correction   degrees of freedom adjustment
+* @param X            input array
+* @param strideX      stride length
+* @param offsetX      starting index for X
+* @return             output value
+*/
+double API_SUFFIX(stdlib_strided_dvariancewd_ndarray)( const CBLAS_INT N, const double correction, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ) {
+	double delta;
+	CBLAS_INT ix;
+	CBLAS_INT i;
+	double mu;
+	double M2;
+	double n;
+	double v;
+
+	n = (double)N - correction;
+	if ( N <= 0 || n <= 0.0 ) {
+		return 0.0 / 0.0; // NaN
+	}
+	if ( N == 1 || strideX == 0 ) {
+		return 0.0;
+	}
+	ix = offsetX;
+	M2 = 0.0;
+	mu = 0.0;
+	for ( i = 0; i < N; i++ ) {
+		v = X[ ix ];
+		delta = v - mu;
+		mu += delta / (double)(i+1);
+		M2 += delta * ( v - mu );
+		ix += strideX;
+	}
+	return M2 / n;
+}