diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/README.md b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/README.md new file mode 100644 index 000000000000..074530da64c0 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/README.md @@ -0,0 +1,158 @@ + + +# Cumulative Distribution Function + +> [Half-normal][half-normal-distribution] distribution [cumulative distribution function][cdf]. + +
+ +The [cumulative distribution function][cdf] for a [half-normal][half-normal-distribution] random variable is + +```math +F(x;\mu,\sigma) = \mathop{\mathrm{erf}}\left( \frac{x-\mu}{\sigma\sqrt{2}} \right) +``` + +where `µ` is the location parameter and `σ` is the scale parameter. + +
+ + + +
+ +## Usage + +```javascript +var cdf = require( '@stdlib/stats/base/dists/halfnormal/cdf' ); +``` + +#### cdf( x, mu, sigma ) + +Evaluates the [cumulative distribution function][cdf] (CDF) for a [half-normal][half-normal-distribution] distribution with parameters `mu` (location) and `sigma` (scale). + +```javascript +var y = cdf( 2.0, 0.0, 1.0 ); +// returns ~0.9545 + +y = cdf( -1.0, 0.0, 1.0 ); +// returns 0.0 + +y = cdf( -1.0, 2.0, 2.0 ); +// returns 0.0 +``` + +If provided `NaN` as any argument, the function returns `NaN`. + +```javascript +var y = cdf( NaN, 0.0, 1.0 ); +// returns NaN + +y = cdf( 0.0, NaN, 1.0 ); +// returns NaN + +y = cdf( 0.0, 0.0, NaN ); +// returns NaN +``` + +If provided `sigma < 0`, the function returns `NaN`. + +```javascript +var y = cdf( 2.0, 0.0, -1.0 ); +// returns NaN +``` + +If provided `sigma = 0`, the function evaluates the [CDF][cdf] of a [degenerate distribution][degenerate-distribution] centered at `mu`. + +```javascript +var y = cdf( 2.0, 8.0, 0.0 ); +// returns 0.0 + +y = cdf( 8.0, 8.0, 0.0 ); +// returns 1.0 + +y = cdf( 10.0, 8.0, 0.0 ); +// returns 1.0 +``` + +#### cdf.factory( mu, sigma ) + +Returns a function for evaluating the [cumulative distribution function][cdf] of a [half-normal][half-normal-distribution] distribution with parameters `mu` and `sigma`. + +```javascript +var mycdf = cdf.factory( 0.0, 1.0 ); + +var y = mycdf( 2.0 ); +// returns ~0.9545 + +y = mycdf( -1.0 ); +// returns 0.0 +``` + +
+ + + +
+ +## Examples + + + +```javascript +var uniform = require( '@stdlib/random/array/uniform' ); +var logEachMap = require( '@stdlib/console/log-each-map' ); +var cdf = require( '@stdlib/stats/base/dists/halfnormal/cdf' ); + +var opts = { + 'dtype': 'float64' +}; +var x = uniform( 10, 0.0, 10.0, opts ); +var mu = uniform( 10, 0.0, 5.0, opts ); +var sigma = uniform( 10, 0.0, 10.0, opts ); + +logEachMap( 'x: %0.4f, µ: %0.4f, σ: %0.4f, F(x;µ,σ): %0.4f', x, mu, sigma, cdf ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +[cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function + +[half-normal-distribution]: https://en.wikipedia.org/wiki/Half-normal_distribution + +[degenerate-distribution]: https://en.wikipedia.org/wiki/Degenerate_distribution + +
+ + diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/benchmark/benchmark.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/benchmark/benchmark.js new file mode 100644 index 000000000000..b10abc1e4e57 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/benchmark/benchmark.js @@ -0,0 +1,87 @@ +/** +* @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 bench = require( '@stdlib/bench' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var EPS = require( '@stdlib/constants/float64/eps' ); +var pkg = require( './../package.json' ).name; +var cdf = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var sigma; + var len; + var mu; + var x; + var y; + var i; + + len = 100; + x = uniform( len, 0.0, 100.0 ); + mu = uniform( len, 0.0, 50.0 ); + sigma = uniform( len, EPS, 20.0 + EPS ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + y = cdf( x[i % len], mu[i % len], sigma[i % len] ); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':factory', function benchmark( b ) { + var mycdf; + var sigma; + var mu; + var x; + var y; + var i; + + mu = 0.0; + sigma = 1.5; + mycdf = cdf.factory( mu, sigma ); + x = uniform( 100, 0.0, 10.0 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + y = mycdf( x[i % x.length] ); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/repl.txt b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/repl.txt new file mode 100644 index 000000000000..c68e2e9de592 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/repl.txt @@ -0,0 +1,79 @@ + +{{alias}}( x, μ, σ ) + Evaluates the cumulative distribution function (CDF) for a half-normal + distribution with location `μ` and scale `σ` at a value `x`. + + If provided `NaN` as any argument, the function returns `NaN`. + + If provided `σ < 0`, the function returns `NaN`. + + Parameters + ---------- + x: number + Input value. + + μ: number + Location parameter. + + σ: number + Scale parameter. + + Returns + ------- + out: number + Evaluated CDF. + + Examples + -------- + > var y = {{alias}}( 2.0, 0.0, 1.0 ) + 0.9544997361036416 + > y = {{alias}}( -1.0, 0.0, 1.0 ) + 0.0 + > y = {{alias}}( -1.0, 2.0, 2.0 ) + 0.0 + > y = {{alias}}( NaN, 0.0, 1.0 ) + NaN + > y = {{alias}}( 0.0, NaN, 1.0 ) + NaN + > y = {{alias}}( 0.0, 0.0, NaN ) + NaN + + // Negative scale parameter: + > y = {{alias}}( 2.0, 0.0, -1.0 ) + NaN + + // Degenerate distribution centered at `μ` when `σ = 0.0`: + > y = {{alias}}( 2.0, 8.0, 0.0 ) + 0.0 + > y = {{alias}}( 8.0, 8.0, 0.0 ) + 1.0 + > y = {{alias}}( 10.0, 8.0, 0.0 ) + 1.0 + + +{{alias}}.factory( μ, σ ) + Returns a function for evaluating the cumulative distribution function (CDF) + of a half-normal distribution with location `μ` and scale `σ`. + + Parameters + ---------- + μ: number + Location parameter. + + σ: number + Scale parameter. + + Returns + ------- + cdf: Function + Cumulative distribution function (CDF). + + Examples + -------- + > var myCDF = {{alias}}.factory( 0.0, 1.0 ); + > var y = myCDF( 2.0 ) + 0.9544997361036416 + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/index.d.ts b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/index.d.ts new file mode 100644 index 000000000000..3fbde0c01697 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/index.d.ts @@ -0,0 +1,115 @@ +/* +* @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 cumulative distribution function (CDF) for a half-normal distribution. +* +* @param x - input value +* @returns evaluated CDF +*/ +type Unary = ( x: number ) => number; + +/** +* Interface for the cumulative distribution function (CDF) of a half-normal distribution. +*/ +interface CDF { + /** + * Evaluates the cumulative distribution function (CDF) for a half-normal distribution with location `mu` and scale `sigma` at a value `x`. + * + * ## Notes + * + * - If provided `sigma < 0`, the function returns `NaN`. + * + * @param x - input value + * @param mu - location parameter + * @param sigma - scale parameter + * @returns evaluated cumulative distribution function + * + * @example + * var y = cdf( 2.0, 0.0, 1.0 ); + * // returns 0.9544997361036416 + * + * @example + * var y = cdf( -1.0, 0.0, 1.0 ); + * // returns 0.0 + * + * @example + * var y = cdf( -1.0, 2.0, 2.0 ); + * // returns 0.0 + * + * @example + * var y = cdf( NaN, 0.0, 1.0 ); + * // returns NaN + * + * @example + * var y = cdf( 0.0, NaN, 1.0 ); + * // returns NaN + * + * @example + * var y = cdf( 0.0, 0.0, NaN ); + * // returns NaN + * + * @example + * // Negative scale parameter: + * var y = cdf( 2.0, 0.0, -1.0 ); + * // returns NaN + */ + ( x: number, mu: number, sigma: number ): number; + + /** + * Returns a function for evaluating the cumulative distribution function (CDF) for a half-normal distribution. + * + * @param mu - location parameter + * @param sigma - scale parameter + * @returns function to evaluate the cumulative distribution function + * + * @example + * var myCDF = cdf.factory( 0.0, 1.0 ); + * var y = myCDF( 2.0 ); + * // returns 0.9544997361036416 + * + * y = myCDF( -1.0 ); + * // returns 0.0 + */ + factory( mu: number, sigma: number ): Unary; +} + +/** +* Half-normal distribution cumulative distribution function (CDF). +* +* @param x - input value +* @param mu - location parameter +* @param sigma - scale parameter +* @returns evaluated CDF +* +* @example +* var y = cdf( 2.0, 0.0, 1.0 ); +* // returns 0.9544997361036416 +* +* var myCDF = cdf.factory( 0.0, 1.0 ); +* y = myCDF( 2.0 ); +* // returns 0.9544997361036416 +*/ +declare var cdf: CDF; + + +// EXPORTS // + +export = cdf; diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/test.ts b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/test.ts new file mode 100644 index 000000000000..49f2fa380ea4 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/docs/types/test.ts @@ -0,0 +1,119 @@ +/* +* @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. +*/ + +import cdf = require( './index' ); + + +// TESTS // + +// The function returns a number... +{ + cdf( 2, 0, 1 ); // $ExpectType number + cdf( 1, 2, 1 ); // $ExpectType number +} + +// The compiler throws an error if the function is provided values other than three numbers... +{ + cdf( true, 3, 1 ); // $ExpectError + cdf( false, 2, 1 ); // $ExpectError + cdf( '5', 1, 1 ); // $ExpectError + cdf( [], 1, 1 ); // $ExpectError + cdf( {}, 2, 1 ); // $ExpectError + cdf( ( x: number ): number => x, 2, 1 ); // $ExpectError + + cdf( 9, true, 1 ); // $ExpectError + cdf( 9, false, 1 ); // $ExpectError + cdf( 5, '5', 1 ); // $ExpectError + cdf( 8, [], 1 ); // $ExpectError + cdf( 9, {}, 1 ); // $ExpectError + cdf( 8, ( x: number ): number => x, 1 ); // $ExpectError + + cdf( 9, 3, true ); // $ExpectError + cdf( 9, 2, false ); // $ExpectError + cdf( 5, 1, '5' ); // $ExpectError + cdf( 8, 1, [] ); // $ExpectError + cdf( 9, 2, {} ); // $ExpectError + cdf( 8, 2, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + cdf(); // $ExpectError + cdf( 2 ); // $ExpectError + cdf( 2, 0 ); // $ExpectError + cdf( 2, 0, 1, 4 ); // $ExpectError +} + +// Attached to main export is a `factory` method which returns a function... +{ + cdf.factory( 0, 1 ); // $ExpectType Unary +} + +// The `factory` method returns a function which returns a number... +{ + const fcn = cdf.factory( 0, 1 ); + fcn( 2 ); // $ExpectType number +} + +// The compiler throws an error if the function returned by the `factory` method is provided invalid arguments... +{ + const fcn = cdf.factory( 0, 1 ); + fcn( true ); // $ExpectError + fcn( false ); // $ExpectError + fcn( '5' ); // $ExpectError + fcn( [] ); // $ExpectError + fcn( {} ); // $ExpectError + fcn( ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function returned by the `factory` method is provided an unsupported number of arguments... +{ + const fcn = cdf.factory( 0, 1 ); + fcn(); // $ExpectError + fcn( 2, 0 ); // $ExpectError + fcn( 2, 0, 1 ); // $ExpectError +} + +// The compiler throws an error if the `factory` method is provided values other than two numbers... +{ + cdf.factory( true, 1 ); // $ExpectError + cdf.factory( false, 1 ); // $ExpectError + cdf.factory( '5', 1 ); // $ExpectError + cdf.factory( [], 1 ); // $ExpectError + cdf.factory( {}, 1 ); // $ExpectError + cdf.factory( ( x: number ): number => x, 1 ); // $ExpectError + + cdf.factory( 9, true ); // $ExpectError + cdf.factory( 9, false ); // $ExpectError + cdf.factory( 5, '5' ); // $ExpectError + cdf.factory( 8, [] ); // $ExpectError + cdf.factory( 9, {} ); // $ExpectError + cdf.factory( 8, ( x: number ): number => x ); // $ExpectError + + cdf.factory( [], true ); // $ExpectError + cdf.factory( {}, false ); // $ExpectError + cdf.factory( false, '5' ); // $ExpectError + cdf.factory( {}, [] ); // $ExpectError + cdf.factory( '5', ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the `factory` method is provided an unsupported number of arguments... +{ + cdf.factory( 0 ); // $ExpectError + cdf.factory( 0, 1, 4 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/examples/index.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/examples/index.js new file mode 100644 index 000000000000..6a190022b4e4 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/examples/index.js @@ -0,0 +1,32 @@ +/** +* @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'; + +var uniform = require( '@stdlib/random/array/uniform' ); +var logEachMap = require( '@stdlib/console/log-each-map' ); +var cdf = require( './../lib' ); + +var opts = { + 'dtype': 'float64' +}; +var x = uniform( 10, 0.0, 10.0, opts ); +var mu = uniform( 10, 0.0, 5.0, opts ); +var sigma = uniform( 10, 0.0, 10.0, opts ); + +logEachMap( 'x: %0.4f, µ: %0.4f, σ: %0.4f, F(x;µ,σ): %0.4f', x, mu, sigma, cdf ); diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/factory.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/factory.js new file mode 100644 index 000000000000..14012cd145c5 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/factory.js @@ -0,0 +1,89 @@ +/** +* @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/cdf' ).factory; +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 {number} mu - location parameter +* @param {NonNegativeNumber} sigma - scale parameter +* @returns {Function} function to evaluate the cumulative distribution function +* +* @example +* var cdf = factory( 0.0, 1.0 ); +* var y = cdf( 2.0 ); +* // returns 0.9544997361036416 +* +* y = cdf( -1.0 ); +* // returns 0.0 +*/ +function factory( mu, sigma ) { + var denom; + if ( + isnan( mu ) || + isnan( sigma ) || + sigma < 0.0 + ) { + return constantFunction( NaN ); + } + if ( sigma === 0.0 ) { + return degenerate( mu ); + } + 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 CDF + * + * @example + * var y = cdf( 2.0 ); + * // returns + */ + function cdf( x ) { + var xc; + if ( isnan( x ) ) { + return NaN; + } + if ( x < mu ) { + return 0.0; + } + xc = x - mu; + return erf( xc / denom ); + } +} + + +// EXPORTS // + +module.exports = factory; diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/index.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/index.js new file mode 100644 index 000000000000..dee51b9d9677 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/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'; + +/** +* 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, 0.0, 1.0 ); +* // returns 0.9544997361036416 +* +* var myCDF = cdf.factory( 0.0, 1.0 ); +* y = myCDF( 2.0 ); +* // returns 0.9544997361036416 +*/ + +// 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; diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/main.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/main.js new file mode 100644 index 000000000000..3252024dd67c --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/lib/main.js @@ -0,0 +1,92 @@ +/** +* @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 erf = require( '@stdlib/math/base/special/erf' ); +var sqrt = require( '@stdlib/math/base/special/sqrt' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); + + +// MAIN // + +/** +* Evaluates the cumulative distribution function (CDF) for a half-normal distribution with location `mu` and scale `sigma` at a value `x`. +* +* @param {number} x - input value +* @param {number} mu - location parameter +* @param {NonNegativeNumber} sigma - scale parameter +* @returns {Probability} evaluated cumulative distribution function +* +* @example +* var y = cdf( 2.0, 0.0, 1.0 ); +* // returns ~0.9545 +* +* @example +* var y = cdf( -1.0, 0.0, 1.0 ); +* // returns 0.0 +* +* @example +* var y = cdf( -1.0, 2.0, 2.0 ); +* // returns 0.0 +* +* @example +* var y = cdf( NaN, 0.0, 1.0 ); +* // returns NaN +* +* @example +* var y = cdf( 0.0, NaN, 1.0 ); +* // returns NaN +* +* @example +* var y = cdf( 0.0, 0.0, NaN ); +* // returns NaN +* +* @example +* // Negative scale parameter: +* var y = cdf( 2.0, 0.0, -1.0 ); +* // returns NaN +*/ +function cdf( x, mu, sigma ) { + var denom; + var xc; + if ( + isnan( x ) || + isnan( mu ) || + isnan( sigma ) || + sigma < 0.0 + ) { + return NaN; + } + if ( sigma === 0.0 ) { + return (x < mu) ? 0.0 : 1.0; + } + if ( x < mu ) { + return 0.0; + } + denom = sigma * sqrt( 2.0 ); + xc = x - mu; + return erf( xc / denom ); +} + + +// EXPORTS // + +module.exports = cdf; diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/package.json b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/package.json new file mode 100644 index 000000000000..063556a6e78c --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/package.json @@ -0,0 +1,68 @@ +{ + "name": "@stdlib/stats/base/dists/halfnormal/cdf", + "version": "0.0.0", + "description": "Half-normal distribution cumulative distribution function (CDF).", + "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", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "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", + "probability", + "cdf", + "cumulative distribution", + "distribution function", + "halfnormal", + "half-normal", + "halfnorm", + "univariate", + "continuous" + ] +} diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/REQUIRE b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/REQUIRE new file mode 100644 index 000000000000..8a033e353f0e --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/REQUIRE @@ -0,0 +1,2 @@ +Distributions 0.8 +JSON 0.9 diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/runner.jl b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/runner.jl new file mode 100644 index 000000000000..2b39797aea51 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/fixtures/julia/runner.jl @@ -0,0 +1,95 @@ +#!/usr/bin/env julia +# +# @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. + +import Distributions: cdf, Normal +import JSON + +""" + gen( x, mu, sigma, name ) + +Generate fixture data and write to file. + +# Arguments + +* `x`: input value +* `mu`: location parameter +* `sigma`: scale parameter +* `name::AbstractString`: output filename + +# Examples + +``` julia +julia> x = rand( 1000 ) .* 15; +julia> mu = rand( 1000 ) .* 10.0; +julia> sigma = rand( 1000 ) .* 5.0; +julia> gen( x, mu, sigma, "data.json" ); +``` +""" +function gen( x, mu, sigma, name ) + z = Array{Float64}( undef, length(x) ); + for i in eachindex(x) + # Half-normal CDF using error function + if x[i] < mu[i] + z[i] = 0.0; + else + xc = (x[i] - mu[i]) / (sigma[i] * sqrt(2.0)); + z[i] = erf(xc); + end + end + + # Store data to be written to file as a collection: + data = Dict([ + ("x", x), + ("mu", mu), + ("sigma", sigma), + ("expected", z) + ]); + + # Based on the script directory, create an output filepath: + filepath = joinpath( dir, name ); + + # Write the data to the output filepath as JSON: + outfile = open( filepath, "w" ); + write( outfile, JSON.json(data) ); + write( outfile, "\n" ); + close( outfile ); +end + +# Get the filename: +file = @__FILE__; + +# Extract the directory in which this file resides: +dir = dirname( file ); + +# Positive location: +x = rand( 1000 ) .* 10.0; +mu = rand( 1000 ) .* 5.0; +sigma = rand( 1000 ) .* 3.0; +gen( x, mu, sigma, "positive_location.json" ); + +# Zero location: +x = rand( 1000 ) .* 10.0; +mu = zeros( 1000 ); +sigma = rand( 1000 ) .* 5.0; +gen( x, mu, sigma, "zero_location.json" ); + +# Large scale: +x = rand( 1000 ) .* 20.0; +mu = rand( 1000 ) .* 2.0; +sigma = rand( 1000 ) .* 20.0; +gen( x, mu, sigma, "large_scale.json" ); diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.cdf.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.cdf.js new file mode 100644 index 000000000000..41354ed637e5 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.cdf.js @@ -0,0 +1,181 @@ +/** +* @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 tape = require( 'tape' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var isAlmostSameValue = require( '@stdlib/assert/is-almost-same-value' ); +var PINF = require( '@stdlib/constants/float64/pinf' ); +var NINF = require( '@stdlib/constants/float64/ninf' ); +var cdf = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof cdf, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'if provided `NaN` for any parameter, the function returns `NaN`', function test( t ) { + var y = cdf( NaN, 0.0, 1.0 ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + y = cdf( 0.0, NaN, 1.0 ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + y = cdf( 0.0, 0.0, NaN ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'if provided `+infinity` for `x` and a valid `mu` and `sigma`, the function returns `1`', function test( t ) { + var y = cdf( PINF, 0.0, 1.0 ); + t.strictEqual( y, 1.0, 'returns expected value' ); + t.end(); +}); + +tape( 'if provided `-infinity` for `x` and a valid `mu` and `sigma`, the function returns `0`', function test( t ) { + var y = cdf( NINF, 0.0, 1.0 ); + t.strictEqual( y, 0.0, 'returns expected value' ); + t.end(); +}); + +tape( 'if provided a negative `sigma`, the function always returns `NaN`', function test( t ) { + var y; + + y = cdf( 2.0, 0.0, -1.0 ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + y = cdf( 0.0, 0.0, -1.0 ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + y = cdf( 2.0, 0.0, NINF ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + y = cdf( 2.0, PINF, NINF ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + y = cdf( 2.0, NINF, NINF ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + y = cdf( 2.0, NaN, NINF ); + t.strictEqual( isnan( y ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'if provided `sigma` equals `0`, the function evaluates a degenerate distribution centered at `mu`', function test( t ) { + var y; + + y = cdf( 2.0, 2.0, 0.0 ); + t.strictEqual( y, 1.0, 'returns 1 for x equal to mu' ); + + y = cdf( 3.0, 2.0, 0.0 ); + t.strictEqual( y, 1.0, 'returns 1 for x greater than mu' ); + + y = cdf( 1.0, 2.0, 0.0 ); + t.strictEqual( y, 0.0, 'returns 0 for x less than mu' ); + + t.end(); +}); + +tape( 'if provided `x < mu`, the function returns `0`', function test( t ) { + var y; + + y = cdf( -1.0, 0.0, 1.0 ); + t.strictEqual( y, 0.0, 'returns 0' ); + + y = cdf( 0.0, 1.0, 1.0 ); + t.strictEqual( y, 0.0, 'returns 0' ); + + y = cdf( 1.0, 5.0, 2.0 ); + t.strictEqual( y, 0.0, 'returns 0' ); + + t.end(); +}); + +tape( 'the function evaluates the CDF for a half-normal distribution', function test( t ) { + var expected; + var sigma; + var mu; + var x; + var y; + var i; + + expected = [ + 0.0, + 0.6826894921370859, + 0.9544997361036416, + 0.0, + 0.6826894921370859, + 0.9544997361036416 + ]; + x = [ + 0.0, + 1.0, + 2.0, + 2.0, + 4.0, + 6.0 + ]; + mu = [ + 0.0, + 0.0, + 0.0, + 2.0, + 2.0, + 2.0 + ]; + sigma = [ + 1.0, + 1.0, + 1.0, + 2.0, + 2.0, + 2.0 + ]; + + for ( i = 0; i < x.length; i++ ) { + y = cdf( x[i], mu[i], sigma[i] ); + t.ok( isAlmostSameValue( y, expected[i], 2 ), 'x: ' + x[i] + ', mu: ' + mu[i] + ', sigma: ' + sigma[i] + ', y: ' + y + ', expected: ' + expected[i] ); + } + t.end(); +}); + +tape( 'the function evaluates the CDF for a half-normal distribution (mu=0, sigma=1)', function test( t ) { + var expected; + var y; + + // x = 0 + y = cdf( 0.0, 0.0, 1.0 ); + t.equal( y, 0.0, 'returns 0' ); + + // x = 1 (approx 0.6826894921370859) + y = cdf( 1.0, 0.0, 1.0 ); + expected = 0.6826894921370859; + t.ok( isAlmostSameValue( y, expected, 2 ), 'returns correct value for x=1' ); + + // x = -1 + y = cdf( -1.0, 0.0, 1.0 ); + t.equal( y, 0.0, 'returns 0 for x < mu' ); + + t.end(); +}); diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.factory.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.factory.js new file mode 100644 index 000000000000..a52da21f28fe --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.factory.js @@ -0,0 +1,141 @@ +/** +* @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 tape = require( 'tape' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var abs = require( '@stdlib/math/base/special/abs' ); +var factory = require( './../lib/factory.js' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof factory, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns a function', function test( t ) { + var cdf = factory( 0.0, 1.0 ); + t.equal( typeof cdf, 'function', 'returns a function' ); + t.end(); +}); + +tape( 'if provided `NaN` for any parameter, the created function returns `NaN`', function test( t ) { + var cdf; + var y; + + cdf = factory( NaN, 1.0 ); + y = cdf( 0.0 ); + t.equal( isnan( y ), true, 'returns NaN' ); + + cdf = factory( 0.0, NaN ); + y = cdf( 0.0 ); + t.equal( isnan( y ), true, 'returns NaN' ); + + t.end(); +}); + +tape( 'if provided a negative `sigma`, the created function returns `NaN`', function test( t ) { + var cdf; + var y; + + cdf = factory( 0.0, -1.0 ); + y = cdf( 0.0 ); + t.equal( isnan( y ), true, 'returns NaN' ); + + t.end(); +}); + +tape( 'if provided `sigma` equals `0`, the created function evaluates a degenerate distribution centered at `mu`', function test( t ) { + var cdf; + var y; + + cdf = factory( 2.0, 0.0 ); + + y = cdf( 0.0 ); + t.equal( y, 0.0, 'returns 0 for x < mu' ); + + y = cdf( 2.0 ); + t.equal( y, 1.0, 'returns 1 for x >= mu' ); + + y = cdf( 4.0 ); + t.equal( y, 1.0, 'returns 1 for x >= mu' ); + + t.end(); +}); + +tape( 'the created function evaluates the CDF for a half-normal distribution', function test( t ) { + var expected; + var sigma; + var cdf; + var del; + var mu; + var x; + var y; + var i; + + expected = [ + 0.0, + 0.6826894921370859, + 0.9544997361036416, + 0.0, + 0.6826894921370859, + 0.9544997361036416 + ]; + x = [ + 0.0, + 1.0, + 2.0, + 2.0, + 4.0, + 6.0 + ]; + mu = [ + 0.0, + 0.0, + 0.0, + 2.0, + 2.0, + 2.0 + ]; + sigma = [ + 1.0, + 1.0, + 1.0, + 2.0, + 2.0, + 2.0 + ]; + + for ( i = 0; i < x.length; i++ ) { + cdf = factory( mu[i], sigma[i] ); + y = cdf( x[i] ); + if ( y === expected[i] ) { + t.equal( y, expected[i], 'x: ' + x[i] + ', mu: ' + mu[i] + ', sigma: ' + sigma[i] + ', y: ' + y + ', expected: ' + expected[i] ); + } else { + del = abs( y - expected[i] ); + t.ok( del <= 1e-14, 'within tolerance. x: ' + x[i] + '. y: ' + y + '. E: ' + expected[i] + '. Delt: ' + del ); + } + } + t.end(); +}); diff --git a/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.js b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.js new file mode 100644 index 000000000000..85a2b4b63e97 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/base/dists/halfnormal/cdf/test/test.js @@ -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. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var cdf = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof cdf, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the main export is a factory method for generating `cdf` functions', function test( t ) { + t.strictEqual( typeof cdf.factory, 'function', 'exports a factory method' ); + t.end(); +});