@stdlib/stats-base-dists-wald-pdf 0.1.0

package/docs/types/index.d.ts

@@ -0,0 +1,124 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* Evaluates the probability density function (PDF) for a Wald distribution.
+*
+* @param x - input value
+* @returns evaluated PDF
+*/
+type Unary = ( x: number ) => number;
+
+/**
+* Interface for the probability density function (PDF) of a Wald distribution.
+*/
+interface PDF {
+	/**
+	* Evaluates the probability density function (PDF) for a Wald distribution with mean `mu` and shape parameter `lambda` at a value `x`.
+	*
+	* ## Notes
+	*
+	* -   If provided `mu <= 0` or `lambda < 0`, the function returns `NaN`.
+	*
+	* @param x - input value
+	* @param mu - mean parameter
+	* @param lambda - shape parameter
+	* @returns evaluated probability density function
+	*
+	* @example
+	* var y = pdf( 2.0, 1.0, 1.0 );
+	* // returns ~0.110
+	*
+	* @example
+	* var y = pdf( 5.0, 3.0, 2.0 );
+	* // returns ~0.046
+	*
+	* @example
+	* var y = pdf( NaN, 1.0, 1.0 );
+	* // returns NaN
+	*
+	* @example
+	* var y = pdf( 2.0, NaN, 1.0 );
+	* // returns NaN
+	*
+	* @example
+	* var y = pdf( 2.0, 1.0, NaN );
+	* // returns NaN
+	*
+	* @example
+	* // Non-positive mean:
+	* var y = pdf( 2.0, 0.0, 1.0 );
+	* // returns NaN
+	*
+	* @example
+	* // Negative shape parameter:
+	* var y = pdf( 2.0, 1.0, -1.0 );
+	* // returns NaN
+	*
+	* @example
+	* var y = pdf( 2.0, 1.0, 0.0 );
+	* // returns 0.0
+	*
+	* @example
+	* var y = pdf( 1.0, 1.0, 0.0 );
+	* // returns Infinity
+	*/
+	( x: number, mu: number, lambda: number ): number;
+
+	/**
+	* Returns a function for evaluating the probability density function (PDF) for a Wald distribution.
+	*
+	* @param mu - mean parameter
+	* @param lambda - shape parameter
+	* @returns function to evaluate the probability density function
+	*
+	* @example
+	* var myPDF = pdf.factory( 3.0, 2.0 );
+	* var y = myPDF( 2.0 );
+	* // returns ~0.189
+	*
+	* y = myPDF( 5.0 );
+	* // returns ~0.046
+	*/
+	factory( mu: number, lambda: number ): Unary;
+}
+
+/**
+* Wald distribution probability density function (PDF).
+*
+* @param x - input value
+* @param mu - mean parameter
+* @param lambda - shape parameter
+* @returns evaluated PDF
+*
+* @example
+* var y = pdf( 2.0, 1.0, 1.0 );
+* // returns ~0.110
+*
+* var myPDF = pdf.factory( 3.0, 2.0 );
+* y = myPDF( 2.0 );
+* // returns ~0.189
+*/
+declare var pdf: PDF;
+
+
+// EXPORTS //
+
+export = pdf;

package/include/stdlib/stats/base/dists/wald/pdf.h

@@ -0,0 +1,38 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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.
+*/
+
+#ifndef STDLIB_STATS_BASE_DISTS_WALD_PDF_H
+#define STDLIB_STATS_BASE_DISTS_WALD_PDF_H
+
+/*
+* If C++, prevent name mangling so that the compiler emits a binary file having undecorated names, thus mirroring the behavior of a C compiler.
+*/
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+* Evaluates the probability density function (PDF) for a Wald distribution with mean `mu` and shape parameter `lambda` at a value `x`.
+*/
+double stdlib_base_dists_wald_pdf( const double x, const double mu, const double lambda );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // !STDLIB_STATS_BASE_DISTS_WALD_PDF_H

package/lib/factory.js

@@ -0,0 +1,93 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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 constantFunction = require( '@stdlib/utils-constant-function' );
+var degenerate = require( '@stdlib/stats-base-dists-degenerate-pdf' ).factory;
+var isnan = require( '@stdlib/math-base-assert-is-nan' );
+var sqrt = require( '@stdlib/math-base-special-sqrt' );
+var exp = require( '@stdlib/math-base-special-exp' );
+var TWO_PI = require( '@stdlib/constants-float64-two-pi' );
+
+
+// MAIN //
+
+/**
+* Returns a function for evaluating the probability density function (PDF) for a Wald distribution.
+*
+* @param {PositiveNumber} mu - mean
+* @param {PositiveNumber} lambda - shape parameter
+* @returns {Function} function to evaluate the probability density function
+*
+* @example
+* var pdf = factory( 1.0, 1.0 );
+* var y = pdf( 2.0 );
+* // returns ~0.110
+*
+* y = pdf( 0.5 );
+* // returns ~0.879
+*/
+function factory( mu, lambda ) {
+	var A;
+	var B;
+	if (
+		isnan( mu ) ||
+		isnan( lambda ) ||
+		mu <= 0.0 ||
+		lambda < 0.0
+	) {
+		return constantFunction( NaN );
+	}
+	if ( lambda === 0.0 ) {
+		return degenerate( mu );
+	}
+	A = sqrt( lambda / TWO_PI );
+	B = -lambda / ( 2.0 * mu * mu );
+	return pdf;
+
+	/**
+	* Evaluates the probability density function (PDF) for a Wald distribution.
+	*
+	* @private
+	* @param {number} x - input value
+	* @returns {number} evaluated probability density function
+	*
+	* @example
+	* var y = pdf( 2.0 );
+	* // returns <number>
+	*/
+	function pdf( x ) {
+		var v;
+		if ( isnan( x ) ) {
+			return NaN;
+		}
+		if ( x <= 0.0 || !isFinite( x ) ) {
+			return 0.0;
+		}
+		v = x - mu;
+		return A / ( x * sqrt( x ) ) * exp( B * v * v / x );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;

package/lib/index.js

@@ -0,0 +1,51 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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';
+
+/**
+* Wald distribution probability density function (PDF).
+*
+* @module @stdlib/stats-base-dists-wald-pdf
+*
+* @example
+* var pdf = require( '@stdlib/stats-base-dists-wald-pdf' );
+*
+* var y = pdf( 2.0, 1.0, 1.0 );
+* // returns ~0.110
+*
+* var myPDF = pdf.factory( 1.0, 1.0 );
+* y = myPDF( 0.5 );
+* // returns ~0.879
+*/
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var main = require( './main.js' );
+var factory = require( './factory.js' );
+
+
+// MAIN //
+
+setReadOnly( main, 'factory', factory );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,120 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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 exp = require( '@stdlib/math-base-special-exp' );
+var sqrt = require( '@stdlib/math-base-special-sqrt' );
+var TWO_PI = require( '@stdlib/constants-float64-two-pi' );
+var PINF = require( '@stdlib/constants-float64-pinf' );
+var isnan = require( '@stdlib/math-base-assert-is-nan' );
+
+
+// MAIN //
+
+/**
+* Evaluates the probability density function (PDF) for a Wald distribution with mean `mu` and shape parameter `lambda` at a value `x`.
+*
+* @param {number} x - input value
+* @param {PositiveNumber} mu - mean
+* @param {PositiveNumber} lambda - shape parameter
+* @returns {number} evaluated probability density function
+*
+* @example
+* var y = pdf( 2.0, 1.0, 1.0 );
+* // returns ~0.110
+*
+* @example
+* var y = pdf( 0.5, 2.0, 3.0 );
+* // returns ~0.362
+*
+* @example
+* var y = pdf( NaN, 1.0, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 1.0, NaN, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 1.0, 1.0, NaN );
+* // returns NaN
+*
+* @example
+* // Non-positive mean:
+* var y = pdf( 2.0, 0.0, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 2.0, -1.0, 1.0 );
+* // returns NaN
+*
+* @example
+* // Negative shape parameter:
+* var y = pdf( 2.0, 1.0, -1.0 );
+* // returns NaN
+*
+* @example
+* // Zero shape parameter (degenerate distribution):
+* var y = pdf( 2.0, 1.0, 0.0 );
+* // returns 0.0
+*
+* @example
+* var y = pdf( 1.0, 1.0, 0.0 );
+* // returns Infinity
+*
+* @example
+* // Non-positive x:
+* var y = pdf( 0.0, 1.0, 1.0 );
+* // returns 0.0
+*
+* @example
+* var y = pdf( -1.0, 1.0, 1.0 );
+* // returns 0.0
+*/
+function pdf( x, mu, lambda ) {
+	var A;
+	var B;
+	var v;
+	if (
+		isnan( x ) ||
+		isnan( mu ) ||
+		isnan( lambda ) ||
+		mu <= 0.0 ||
+		lambda < 0.0
+	) {
+		return NaN;
+	}
+	if ( lambda === 0.0 ) {
+		return ( x === mu ) ? PINF : 0.0;
+	}
+	if ( x <= 0.0 || !isFinite( x ) ) {
+		return 0.0;
+	}
+	A = sqrt( lambda / TWO_PI );
+	B = -lambda / ( 2.0 * mu * mu );
+	v = x - mu;
+	return A / ( x * sqrt( x ) ) * exp( B * v * v / x );
+}
+
+
+// EXPORTS //
+
+module.exports = pdf;

package/lib/native.js

@@ -0,0 +1,96 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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 //
+
+/**
+* Evaluates the probability density function (PDF) for a Wald distribution with mean `mu` and shape parameter `lambda` at a value `x`.
+*
+* @private
+* @param {number} x - input value
+* @param {PositiveNumber} mu - mean
+* @param {PositiveNumber} lambda - shape parameter
+* @returns {number} evaluated probability density function
+*
+* @example
+* var y = pdf( 2.0, 1.0, 1.0 );
+* // returns ~0.110
+*
+* @example
+* var y = pdf( 0.5, 2.0, 3.0 );
+* // returns ~0.362
+*
+* @example
+* var y = pdf( NaN, 1.0, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 1.0, NaN, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 1.0, 1.0, NaN );
+* // returns NaN
+*
+* @example
+* // Non-positive mean:
+* var y = pdf( 2.0, 0.0, 1.0 );
+* // returns NaN
+*
+* @example
+* var y = pdf( 2.0, -1.0, 1.0 );
+* // returns NaN
+*
+* @example
+* // Negative shape parameter:
+* var y = pdf( 2.0, 1.0, -1.0 );
+* // returns NaN
+*
+* @example
+* // Zero shape parameter (degenerate distribution):
+* var y = pdf( 2.0, 1.0, 0.0 );
+* // returns 0.0
+*
+* @example
+* var y = pdf( 1.0, 1.0, 0.0 );
+* // returns Infinity
+*
+* @example
+* // Non-positive x:
+* var y = pdf( 0.0, 1.0, 1.0 );
+* // returns 0.0
+*
+* @example
+* var y = pdf( -1.0, 1.0, 1.0 );
+* // returns 0.0
+*/
+function pdf( x, mu, lambda ) {
+	return addon( x, mu, lambda );
+}
+
+
+// EXPORTS //
+
+module.exports = pdf;

package/manifest.json

@@ -0,0 +1,93 @@
+{
+  "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/math-base-napi-ternary",
+        "@stdlib/constants-float64-two-pi",
+        "@stdlib/math-base-assert-is-nan",
+        "@stdlib/math-base-assert-is-infinite",
+        "@stdlib/math-base-special-sqrt",
+        "@stdlib/math-base-special-exp",
+        "@stdlib/constants-float64-pinf"
+      ]
+    },
+    {
+      "task": "benchmark",
+      "wasm": false,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/constants-float64-two-pi",
+        "@stdlib/math-base-assert-is-nan",
+        "@stdlib/math-base-assert-is-infinite",
+        "@stdlib/math-base-special-sqrt",
+        "@stdlib/math-base-special-exp",
+        "@stdlib/constants-float64-pinf",
+        "@stdlib/constants-float64-eps"
+      ]
+    },
+    {
+      "task": "examples",
+      "wasm": false,
+      "src": [
+        "./src/main.c"
+      ],
+      "include": [
+        "./include"
+      ],
+      "libraries": [],
+      "libpath": [],
+      "dependencies": [
+        "@stdlib/constants-float64-two-pi",
+        "@stdlib/math-base-assert-is-nan",
+        "@stdlib/math-base-assert-is-infinite",
+        "@stdlib/math-base-special-sqrt",
+        "@stdlib/math-base-special-exp",
+        "@stdlib/constants-float64-pinf",
+        "@stdlib/constants-float64-eps"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@stdlib/stats-base-dists-wald-pdf",
+  "version": "0.1.0",
+  "description": "Wald distribution probability density function (PDF).",
+  "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",
+  "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-base-dists-wald-pdf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {
+    "@stdlib/constants-float64-pinf": "^0.2.2",
+    "@stdlib/constants-float64-two-pi": "^0.2.2",
+    "@stdlib/math-base-assert-is-infinite": "^0.2.2",
+    "@stdlib/math-base-assert-is-nan": "^0.2.2",
+    "@stdlib/math-base-napi-ternary": "^0.3.1",
+    "@stdlib/math-base-special-exp": "^0.2.4",
+    "@stdlib/math-base-special-sqrt": "^0.2.2",
+    "@stdlib/stats-base-dists-degenerate-pdf": "^0.3.0",
+    "@stdlib/utils-constant-function": "^0.2.2",
+    "@stdlib/utils-define-nonenumerable-read-only-property": "^0.2.2",
+    "@stdlib/utils-library-manifest": "^0.2.3"
+  },
+  "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",
+    "distribution",
+    "dist",
+    "continuous",
+    "probability",
+    "pdf",
+    "wald",
+    "inverse-gaussian",
+    "inverse gaussian",
+    "univariate"
+  ],
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/stdlib"
+  }
+}