feat: added complete implementation for stats/base/dists/halfnormal

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

@@ -0,0 +1,247 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 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.
+
+-->
+
+# Half-Normal
+
+> Half-normal distribution.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var halfnormal = require( '@stdlib/stats/base/dists/halfnormal' );
+```
+
+#### halfnormal
+
+Half-normal distribution.
+
+```javascript
+var dist = halfnormal;
+// returns {...}
+```
+
+The namespace contains the following distribution functions:
+
+<!-- <toc pattern="*+(cdf|pdf|mgf|quantile)*"> -->
+
+<div class="namespace-toc">
+
+-   <span class="signature">[`cdf( x, sigma )`][@stdlib/stats/base/dists/halfnormal/cdf]</span><span class="delimiter">: </span><span class="description">half-normal distribution cumulative distribution function.</span>
+-   <span class="signature">[`logcdf( x, sigma )`][@stdlib/stats/base/dists/halfnormal/logcdf]</span><span class="delimiter">: </span><span class="description">evaluate the natural logarithm of the cumulative distribution function (CDF) for a half-normal distribution.</span>
+-   <span class="signature">[`logpdf( x, sigma )`][@stdlib/stats/base/dists/halfnormal/logpdf]</span><span class="delimiter">: </span><span class="description">evaluate the natural logarithm of the probability density function (PDF) for a half-normal distribution.</span>
+-   <span class="signature">[`mgf( t, sigma )`][@stdlib/stats/base/dists/halfnormal/mgf]</span><span class="delimiter">: </span><span class="description">half-normal distribution moment-generating function (MGF).</span>
+-   <span class="signature">[`pdf( x, sigma )`][@stdlib/stats/base/dists/halfnormal/pdf]</span><span class="delimiter">: </span><span class="description">half-normal distribution probability density function (PDF).</span>
+-   <span class="signature">[`quantile( p, sigma )`][@stdlib/stats/base/dists/halfnormal/quantile]</span><span class="delimiter">: </span><span class="description">half-normal distribution quantile function.</span>
+
+</div>
+
+<!-- </toc> -->
+
+The namespace contains the following functions for calculating distribution properties:
+
+<!-- <toc pattern="*+(entropy|kurtosis|mean|median|mode|skewness|stdev|variance)*"> -->
+
+<div class="namespace-toc">
+
+-   <span class="signature">[`entropy( sigma )`][@stdlib/stats/base/dists/halfnormal/entropy]</span><span class="delimiter">: </span><span class="description">half-normal distribution differential entropy.</span>
+-   <span class="signature">[`kurtosis( sigma )`][@stdlib/stats/base/dists/halfnormal/kurtosis]</span><span class="delimiter">: </span><span class="description">half-normal distribution excess kurtosis.</span>
+-   <span class="signature">[`mean( sigma )`][@stdlib/stats/base/dists/halfnormal/mean]</span><span class="delimiter">: </span><span class="description">half-normal distribution expected value.</span>
+-   <span class="signature">[`median( sigma )`][@stdlib/stats/base/dists/halfnormal/median]</span><span class="delimiter">: </span><span class="description">half-normal distribution median.</span>
+-   <span class="signature">[`mode( sigma )`][@stdlib/stats/base/dists/halfnormal/mode]</span><span class="delimiter">: </span><span class="description">half-normal distribution mode.</span>
+-   <span class="signature">[`skewness( sigma )`][@stdlib/stats/base/dists/halfnormal/skewness]</span><span class="delimiter">: </span><span class="description">half-normal distribution skewness.</span>
+-   <span class="signature">[`stdev( sigma )`][@stdlib/stats/base/dists/halfnormal/stdev]</span><span class="delimiter">: </span><span class="description">half-normal distribution standard deviation.</span>
+-   <span class="signature">[`variance( sigma )`][@stdlib/stats/base/dists/halfnormal/variance]</span><span class="delimiter">: </span><span class="description">half-normal distribution variance.</span>
+
+</div>
+
+<!-- </toc> -->
+
+The namespace contains a constructor function for creating a [half-normal][halfnormal-distribution] distribution object.
+
+<!-- <toc pattern="*ctor*"> -->
+
+<div class="namespace-toc">
+
+-   <span class="signature">[`HalfNormal( [sigma] )`][@stdlib/stats/base/dists/halfnormal/ctor]</span><span class="delimiter">: </span><span class="description">half-normal distribution constructor.</span>
+
+</div>
+
+<!-- </toc> -->
+
+```javascript
+var HalfNormal = require( '@stdlib/stats/base/dists/halfnormal' ).HalfNormal;
+
+var dist = new HalfNormal( 2.0 );
+
+var y = dist.pdf( 1.0 );
+// returns 0.3520653267642996
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var halfnormal = require( '@stdlib/stats/base/dists/halfnormal' );
+
+/*
+A quality control engineer is analyzing the absolute deviations of product measurements from their target specification.
+
+The absolute deviations follow a half-normal distribution with scale parameter σ (sigma) = 2.0 mm.
+
+We can model these absolute deviations using a half-normal distribution with σ = 2.0.
+*/
+
+var sigma = 2.0;
+
+var halfnormalDist = new halfnormal.HalfNormal( sigma );
+
+// Output the scale parameter:
+console.log( halfnormalDist.sigma );
+// => 2.0
+
+// Mean absolute deviation:
+console.log( halfnormalDist.mean );
+// => ~1.596
+
+// Median absolute deviation:
+console.log( halfnormalDist.median );
+// => ~1.349
+
+// Mode (most common deviation):
+console.log( halfnormalDist.mode );
+// => 0.0
+
+// Variance of absolute deviations:
+console.log( halfnormalDist.variance );
+// => 1.4535209105296745
+
+// Probability density function at 1.0 mm deviation:
+console.log( halfnormal.pdf( 1.0, sigma ) );
+// => 0.3520653267642996
+
+// Cumulative distribution function at 2.0 mm (portion of deviations ≤ 2.0 mm):
+console.log( halfnormal.cdf( 2.0, sigma ) );
+// => ~0.683
+
+// 90th percentile of absolute deviations:
+console.log( halfnormal.quantile( 0.9, sigma ) );
+// => 3.289707253902946
+
+// Moment-generating function value at 0.5:
+console.log( halfnormal.mgf( 0.5, sigma ) );
+// => 2.7742859576700094
+
+// Entropy (measure of uncertainty):
+console.log( halfnormal.entropy( sigma ) );
+// => 1.4189385332046727
+
+// Skewness (measure of asymmetry):
+console.log( halfnormal.skewness( sigma ) );
+// => ~0.995
+
+// Excess kurtosis (measure of tail heaviness):
+console.log( halfnormal.kurtosis( sigma ) );
+// => ~0.869
+
+var myquantile = halfnormal.quantile.factory( 2.0 );
+
+// 25th percentile:
+console.log( myquantile( 0.25 ) );
+// => 0.6372787279287504
+
+// 75th percentile:
+console.log( myquantile( 0.75 ) );
+// => 2.300698760752016
+
+var mylogpdf = halfnormal.logpdf.factory( 2.0 );
+
+// Logarithm of PDF at 1.0 mm:
+console.log( mylogpdf( 1.0 ) );
+// => -1.0439385332046727
+
+// Logarithm of PDF at 3.0 mm:
+console.log( mylogpdf( 3.0 ) );
+// => -2.0439385332046727
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[halfnormal-distribution]: https://en.wikipedia.org/wiki/Half-normal_distribution
+
+<!-- <toc-links> -->
+
+[@stdlib/stats/base/dists/halfnormal/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/ctor
+
+[@stdlib/stats/base/dists/halfnormal/entropy]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/entropy
+
+[@stdlib/stats/base/dists/halfnormal/kurtosis]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/kurtosis
+
+[@stdlib/stats/base/dists/halfnormal/mean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/mean
+
+[@stdlib/stats/base/dists/halfnormal/median]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/median
+
+[@stdlib/stats/base/dists/halfnormal/mode]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/mode
+
+[@stdlib/stats/base/dists/halfnormal/skewness]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/skewness
+
+[@stdlib/stats/base/dists/halfnormal/stdev]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/stdev
+
+[@stdlib/stats/base/dists/halfnormal/variance]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/variance
+
+[@stdlib/stats/base/dists/halfnormal/cdf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/cdf
+
+[@stdlib/stats/base/dists/halfnormal/logcdf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/logcdf
+
+[@stdlib/stats/base/dists/halfnormal/logpdf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/logpdf
+
+[@stdlib/stats/base/dists/halfnormal/mgf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/mgf
+
+[@stdlib/stats/base/dists/halfnormal/pdf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/pdf
+
+[@stdlib/stats/base/dists/halfnormal/quantile]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists/halfnormal/quantile
+
+<!-- </toc-links> -->
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/factory.js

@@ -0,0 +1,87 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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 isnan = require( '@stdlib/math/base/assert/is-nan' );
+var sqrt = require( '@stdlib/math/base/special/sqrt' );
+var erf = require( '@stdlib/math/base/special/erf' );
+
+
+// MAIN //
+
+/**
+* Returns a function for evaluating the cumulative distribution function (CDF) for a half-normal distribution.
+*
+* @param {PositiveNumber} sigma - scale parameter
+* @returns {Function} function to evaluate the cumulative distribution function
+*
+* @example
+* var cdf = factory( 2.0 );
+* var y = cdf( 1.0 );
+* // returns 0.3829249225480262
+*
+* y = cdf( 0.0 );
+* // returns 0.0
+*/
+function factory( sigma ) {
+	var denom;
+	if (
+		isnan( sigma ) ||
+		sigma < 0.0
+	) {
+		return constantFunction( NaN );
+	}
+	if ( sigma === 0.0 ) {
+		return cdf;
+	}
+	denom = sigma * sqrt( 2.0 );
+	return cdf;
+
+	/**
+	* Evaluates the cumulative distribution function (CDF) for a half-normal distribution.
+	*
+	* @private
+	* @param {number} x - input value
+	* @returns {Probability} evaluated cumulative distribution function
+	*
+	* @example
+	* var y = cdf( 2.0 );
+	* // returns <number>
+	*/
+	function cdf( x ) {
+		if ( isnan( x ) ) {
+			return NaN;
+		}
+		if ( x < 0.0 ) {
+			return 0.0;
+		}
+		if ( sigma === 0.0 ) {
+			return ( x >= 0.0 ) ? 1.0 : 0.0;
+		}
+		return erf( x / denom );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;

lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/index.js

@@ -0,0 +1,51 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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';
+
+/**
+* Half-normal distribution cumulative distribution function (CDF).
+*
+* @module @stdlib/stats/base/dists/halfnormal/cdf
+*
+* @example
+* var cdf = require( '@stdlib/stats/base/dists/halfnormal/cdf' );
+*
+* var y = cdf( 2.0, 1.0 );
+* // returns 0.9544997361036416
+*
+* var myCDF = cdf.factory( 2.0 );
+* y = myCDF( 1.0 );
+* // returns 0.3829249225480262
+*/
+
+// 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;