main.js (2541B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2018 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var abs = require( './../../../../base/special/abs' ); 24 var isnan = require( './../../../../base/assert/is-nan' ); 25 var isPositiveZero = require( './../../../../base/assert/is-positive-zero' ); 26 var ln = require( './../../../../base/special/ln' ); 27 var expm1 = require( './../../../../base/special/expm1' ); 28 var NINF = require( '@stdlib/constants/float64/ninf' ); 29 30 31 // MAIN // 32 33 /** 34 * Computes a one-parameter Box-Cox transformation. 35 * 36 * ## Method 37 * 38 * - If \\( \lambda << 1 \\) and \\( \ln( x ) < 1.0 \\), then the product \\( \lambda \cdot \ln(x) \\) can lose precision, and, furthermore, \\( \operatorname{expm1}(x) = x \\) for \\( x < \epsilon \\). 39 * - For double-precision floating-point numbers, the range of the natural log is \\( \[-744.44, 709.78\] and \\( \epsilon \\) is the smallest value produced. 40 * - The value range means that we will have \\( |\lambda \cdot \ln(x)| < \epsilon \\) whenever \\( |\lambda| \leq \frac{\epsilon}{-\ln(d) \\), where \\( d \\) is the minimum double-precision floating-point number, thus corresponding to the value \\( \approx 2.98 \times 10^{-19} \\). 41 * 42 * @param {number} x - input value 43 * @param {number} lambda - power parameter 44 * @returns {number} Box-Cox transformation 45 * 46 * @example 47 * var v = boxcox( 1.0, 2.5 ); 48 * // returns 0.0 49 * 50 * @example 51 * var v = boxcox( 4.0, 2.5 ); 52 * // returns 12.4 53 * 54 * @example 55 * var v = boxcox( 10.0, 2.5 ); 56 * // returns ~126.0911 57 * 58 * @example 59 * var v = boxcox( 2.0, 0.0 ); 60 * // returns ~0.6931 61 * 62 * @example 63 * var v = boxcox( -1.0, 2.5 ); 64 * // returns NaN 65 * 66 * @example 67 * var v = boxcox( 0.0, -1.0 ); 68 * // returns -Infinity 69 */ 70 function boxcox( x, lambda ) { 71 if ( isnan( x ) || isnan( lambda ) ) { 72 return NaN; 73 } 74 if ( isPositiveZero( x ) && lambda < 0.0 ) { 75 return NINF; 76 } 77 if ( abs( lambda ) < 1.0e-19 ) { 78 return ln( x ); 79 } 80 return expm1( lambda*ln( x ) ) / lambda; 81 } 82 83 84 // EXPORTS // 85 86 module.exports = boxcox;