@stdlib/stats
Version:
Standard library statistical functions.
480 lines (447 loc) • 13.2 kB
JavaScript
/**
* @license Apache-2.0
*
* Copyright (c) 2018 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.
*/
/* eslint-disable no-restricted-syntax, no-invalid-this */
'use strict';
// MODULES //
var defineProperty = require( '@stdlib/utils/define-property' );
var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
var setReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' );
var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var entropy = require( './../../../../../base/dists/triangular/entropy' );
var kurtosis = require( './../../../../../base/dists/triangular/kurtosis' );
var mean = require( './../../../../../base/dists/triangular/mean' );
var median = require( './../../../../../base/dists/triangular/median' );
var mode = require( './../../../../../base/dists/triangular/mode' );
var skewness = require( './../../../../../base/dists/triangular/skewness' );
var stdev = require( './../../../../../base/dists/triangular/stdev' );
var variance = require( './../../../../../base/dists/triangular/variance' );
var cdf = require( './../../../../../base/dists/triangular/cdf' );
var logcdf = require( './../../../../../base/dists/triangular/logcdf' );
var logpdf = require( './../../../../../base/dists/triangular/logpdf' );
var mgf = require( './../../../../../base/dists/triangular/mgf' );
var pdf = require( './../../../../../base/dists/triangular/pdf' );
var quantile = require( './../../../../../base/dists/triangular/quantile' );
var format = require( '@stdlib/string/format' );
// FUNCTIONS //
/**
* Evaluates the cumulative distribution function (CDF).
*
* @private
* @param {number} x - input value
* @returns {Probability} evaluated CDF
*/
function triangularCDF( x ) {
return cdf( x, this.a, this.b, this.c );
}
/**
* Evaluates the natural logarithm of the cumulative distribution function (CDF).
*
* @private
* @param {number} x - input value
* @returns {number} evaluated logCDF
*/
function triangularLogCDF( x ) {
return logcdf( x, this.a, this.b, this.c );
}
/**
* Evaluates the natural logarithm of the probability density function (PDF).
*
* @private
* @param {number} x - input value
* @returns {number} evaluated logPDF
*/
function triangularLogPDF( x ) {
return logpdf( x, this.a, this.b, this.c );
}
/**
* Evaluates the moment-generating function (MGF).
*
* @private
* @param {number} t - input value
* @returns {number} evaluated MGF
*/
function triangularMGF( t ) {
return mgf( t, this.a, this.b, this.c );
}
/**
* Evaluates the probability density function (PDF).
*
* @private
* @param {number} x - input value
* @returns {number} evaluated PDF
*/
function triangularPDF( x ) {
return pdf( x, this.a, this.b, this.c );
}
/**
* Evaluates the quantile function.
*
* @private
* @param {Probability} p - input probability
* @returns {number} evaluated quantile function
*/
function triangularQuantile( p ) {
return quantile( p, this.a, this.b, this.c );
}
// MAIN //
/**
* Triangular distribution constructor.
*
* @constructor
* @param {number} [a=0.0] - minimum support
* @param {number} [b=1.0] - maximum support
* @param {number} [c=0.5] - mode
* @throws {TypeError} `a` must be a number
* @throws {TypeError} `b` must be a number
* @throws {TypeError} `c` must be a number
* @throws {RangeError} `a` must be less than or equal to `b` and `c`
* @throws {RangeError} `b` must be greater than or equal to `a` and `b`
* @throws {RangeError} `c` must be greater than or equal to `a` and smaller than or equal to `b`
* @returns {Triangular} distribution instance
*
* @example
* var triangular = new Triangular( 0.0, 1.0, 0.25 );
*
* var y = triangular.cdf( 0.8 );
* // returns ~0.947
*
* var mu = triangular.mean;
* // returns ~0.417
*/
function Triangular() {
var a;
var b;
var c;
if ( !(this instanceof Triangular) ) {
if ( arguments.length === 0 ) {
return new Triangular();
}
return new Triangular( arguments[ 0 ], arguments[ 1 ], arguments[ 2 ] );
}
if ( arguments.length ) {
a = arguments[ 0 ];
b = arguments[ 1 ];
c = arguments[ 2 ];
if ( !isNumber( a ) || isnan( a ) ) {
throw new TypeError( format( 'invalid argument. Minimum support must be a number. Value: `%s`.', a ) );
}
if ( !isNumber( b ) || isnan( b ) ) {
throw new TypeError( format( 'invalid argument. Maximum support must be a number. Value: `%s`.', b ) );
}
if ( !isNumber( c ) || isnan( c ) ) {
throw new TypeError( format( 'invalid argument. Mode must be a number. Value: `%s`.', c ) );
}
if ( !( a <= c && c <= b ) ) {
throw new RangeError( format( 'invalid arguments. Parameters must satisfy the following condition: %s. a: `%f`. b: `%f`. c: `%f`.', 'a <= c <= b', a, b, c ) );
}
} else {
a = 0.0;
b = 1.0;
c = 0.5;
}
defineProperty( this, 'a', {
'configurable': false,
'enumerable': true,
'get': function get() {
return a;
},
'set': function set( value ) {
if ( !isNumber( value ) || isnan( value ) ) {
throw new TypeError( format( 'invalid assignment. Must be a number. Value: `%s`.', value ) );
}
if ( value > b || value > c ) {
throw new RangeError( format( 'invalid assignment. Must be less than or equal to both the maximum support and the mode. Value: `%f`.', value ) );
}
a = value;
}
});
defineProperty( this, 'b', {
'configurable': false,
'enumerable': true,
'get': function get() {
return b;
},
'set': function set( value ) {
if ( !isNumber( value ) || isnan( value ) ) {
throw new TypeError( format( 'invalid assignment. Must be a number. Value: `%s`.', value ) );
}
if ( a > value || c > value ) {
throw new RangeError( format( 'invalid assignment. Must be greater than or equal to both the minimum support and the mode. Value: `%f`.', value ) );
}
b = value;
}
});
defineProperty( this, 'c', {
'configurable': false,
'enumerable': true,
'get': function get() {
return c;
},
'set': function set( value ) {
if ( !isNumber( value ) || isnan( value ) ) {
throw new TypeError( format( 'invalid assignment. Must be a number. Value: `%s`.', value ) );
}
if ( a > value || b < value ) {
throw new RangeError( format( 'invalid assignment. Must be greater than or equal to the minimum support and less than or equal to the maximum support. Value: `%f`.', value ) );
}
c = value;
}
});
return this;
}
/**
* Triangular distribution differential entropy.
*
* @name entropy
* @memberof Triangular.prototype
* @type {number}
* @see [differential entropy]{@link https://en.wikipedia.org/wiki/Entropy_%28information_theory%29}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.entropy;
* // returns ~1.886
*/
setReadOnlyAccessor( Triangular.prototype, 'entropy', function get() {
return entropy( this.a, this.b, this.c );
});
/**
* Triangular distribution excess kurtosis.
*
* @name kurtosis
* @memberof Triangular.prototype
* @type {number}
* @see [kurtosis]{@link https://en.wikipedia.org/wiki/Kurtosis}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.kurtosis;
* // returns -0.6
*/
setReadOnlyAccessor( Triangular.prototype, 'kurtosis', function get() {
return kurtosis( this.a, this.b, this.c );
});
/**
* Triangular distribution expected value.
*
* @name mean
* @memberof Triangular.prototype
* @type {number}
* @see [expected value]{@link https://en.wikipedia.org/wiki/Expected_value}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.mean;
* // returns ~8.667
*/
setReadOnlyAccessor( Triangular.prototype, 'mean', function get() {
return mean( this.a, this.b, this.c );
});
/**
* Triangular distribution median.
*
* @name median
* @memberof Triangular.prototype
* @type {number}
* @see [median]{@link https://en.wikipedia.org/wiki/Median}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.median;
* // returns ~8.899
*/
setReadOnlyAccessor( Triangular.prototype, 'median', function get() {
return median( this.a, this.b, this.c );
});
/**
* Triangular distribution mode.
*
* @name mode
* @memberof Triangular.prototype
* @type {number}
* @see [mode]{@link https://en.wikipedia.org/wiki/Mode_%28statistics%29}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.mode;
* // returns 10.0
*/
setReadOnlyAccessor( Triangular.prototype, 'mode', function get() {
return mode( this.a, this.b, this.c );
});
/**
* Triangular distribution skewness.
*
* @name skewness
* @memberof Triangular.prototype
* @type {number}
* @see [skewness]{@link https://en.wikipedia.org/wiki/Skewness}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.skewness;
* // returns ~-0.422
*/
setReadOnlyAccessor( Triangular.prototype, 'skewness', function get() {
return skewness( this.a, this.b, this.c );
});
/**
* Triangular distribution standard deviation.
*
* @name stdev
* @memberof Triangular.prototype
* @type {PositiveNumber}
* @see [standard deviation]{@link https://en.wikipedia.org/wiki/Standard_deviation}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.stdev;
* // returns ~1.7
*/
setReadOnlyAccessor( Triangular.prototype, 'stdev', function get() {
return stdev( this.a, this.b, this.c );
});
/**
* Triangular distribution variance.
*
* @name variance
* @memberof Triangular.prototype
* @type {PositiveNumber}
* @see [variance]{@link https://en.wikipedia.org/wiki/Variance}
*
* @example
* var triangular = new Triangular( 4.0, 12.0, 10.0 );
*
* var v = triangular.variance;
* // returns ~2.889
*/
setReadOnlyAccessor( Triangular.prototype, 'variance', function get() {
return variance( this.a, this.b, this.c );
});
/**
* Evaluates the cumulative distribution function (CDF).
*
* @name cdf
* @memberof Triangular.prototype
* @type {Function}
* @param {number} x - input value
* @returns {Probability} evaluated CDF
* @see [cdf]{@link https://en.wikipedia.org/wiki/Cumulative_distribution_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.cdf( 3.0 );
* // returns 0.5
*/
setReadOnly( Triangular.prototype, 'cdf', triangularCDF );
/**
* Evaluates the natural logarithm of the cumulative distribution function (CDF).
*
* @name logcdf
* @memberof Triangular.prototype
* @type {Function}
* @param {number} x - input value
* @returns {number} evaluated logCDF
* @see [cdf]{@link https://en.wikipedia.org/wiki/Cumulative_distribution_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.logcdf( 3.0 );
* // returns ~-0.693
*/
setReadOnly( Triangular.prototype, 'logcdf', triangularLogCDF );
/**
* Evaluates the natural logarithm of the probability density function (PDF).
*
* @name logpdf
* @memberof Triangular.prototype
* @type {Function}
* @param {number} x - input value
* @returns {number} evaluated logPDF
* @see [pdf]{@link https://en.wikipedia.org/wiki/Probability_density_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.logpdf( 2.4 );
* // returns ~-0.916
*/
setReadOnly( Triangular.prototype, 'logpdf', triangularLogPDF );
/**
* Evaluates the moment-generating function (MGF).
*
* @name mgf
* @memberof Triangular.prototype
* @type {Function}
* @param {number} t - input value
* @returns {number} evaluated MGF
* @see [mgf]{@link https://en.wikipedia.org/wiki/Moment-generating_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.mgf( 0.5 );
* // returns ~4.576
*/
setReadOnly( Triangular.prototype, 'mgf', triangularMGF );
/**
* Evaluates the probability density function (PDF).
*
* @name pdf
* @memberof Triangular.prototype
* @type {Function}
* @param {number} x - input value
* @returns {number} evaluated PDF
* @see [pdf]{@link https://en.wikipedia.org/wiki/Probability_density_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.pdf( 2.4 );
* // returns ~0.40
*/
setReadOnly( Triangular.prototype, 'pdf', triangularPDF );
/**
* Evaluates the quantile function.
*
* @name quantile
* @memberof Triangular.prototype
* @type {Function}
* @param {Probability} p - input probability
* @returns {number} evaluated quantile function
* @see [quantile function]{@link https://en.wikipedia.org/wiki/Quantile_function}
*
* @example
* var triangular = new Triangular( 2.0, 4.0, 3.0 );
*
* var v = triangular.quantile( 0.5 );
* // returns 3.0
*/
setReadOnly( Triangular.prototype, 'quantile', triangularQuantile );
// EXPORTS //
module.exports = Triangular;