time-to-botec/js/node_modules/@stdlib/math/base/utils/relative-difference/README.md

Relative Difference

Compute the relative difference of two real numbers.

The relative difference of two real numbers is defined as

where |x-y| is the absolute difference and f(x,y) is a scale function. Common scale functions include

The choice of scale function depends on application context.

Usage

var reldiff = require( '@stdlib/math/base/utils/relative-difference' );

reldiff( x, y[, scale] )

Computes the relative difference of two real numbers.

var d = reldiff( 2.0, 5.0 ); // => 3/5
// returns 0.6

d = reldiff( -1.0, 3.14 ); // => 4.14/3.14
// returns ~1.318

The following scale functions are supported:

• max-abs: maximum absolute value of x and y (default).
• max: maximum value of x and y.
• min-abs: minimum absolute value of x and y.
• min: minimum value of x and y.
• mean-abs: arithmetic mean of the absolute values of x and y.
• mean: arithmetic mean of x and y.
• x: x (noncommutative).
• y: y (noncommutative).

By default, the function scales the absolute difference by dividing the absolute difference by the maximum absolute value of x and y. To scale by a different function, specify a scale function name.

var d = reldiff( -2.0, 5.0 ); // => |-7/5|
// returns 1.4

d = reldiff( -2.0, 5.0, 'max-abs' ); // => |-7/5|
// returns 1.4

d = reldiff( -2.0, 5.0, 'max' ); // => |-7/5|
// returns 1.4

d = reldiff( -2.0, 5.0, 'min-abs' ); // => |-7/2|
// returns 3.5

d = reldiff( -2.0, 5.0, 'min' ); // => |-7/-2|
// returns 3.5

d = reldiff( -2.0, 5.0, 'mean-abs' ); // => |-7/3.5|
// returns 2.0

d = reldiff( -2.0, 5.0, 'mean' ); // => |-7/1.5|
// returns ~4.67

d = reldiff( -2.0, 5.0, 'x' ); // => |-7/-2|
// returns 3.5

d = reldiff( 5.0, -2.0, 'x' ); // => |7/5|
// returns 1.4

d = reldiff( -2.0, 5.0, 'y' ); // => |-7/5|
// returns 1.4

d = reldiff( 5.0, -2.0, 'y' ); // => |7/-2|
// returns 3.5

To use a custom scale function, provide a function which accepts two numeric arguments x and y.

var abs = require( '@stdlib/math/base/special/abs' );
var EPS = require( '@stdlib/constants/float64/eps' );

function scale( x, y ) {
    var s;
    x = abs( x );
    y = abs( y );

    // Maximum absolute value:
    s = (x < y ) ? y : x;

    // Scale in units of epsilon:
    return s * EPS;
}

var d = reldiff( 12.15, 12.149999999999999, scale );
// returns ~0.658

Notes

• If the absolute difference of x and y is 0, the relative difference is always 0.

  var d = reldiff( 0.0, 0.0 );
  // returns 0.0
  
  d = reldiff( 3.14, 3.14 );
  // returns 0.0
  

• If |x| = |y| = infinity, the function returns NaN.

  var d = reldiff( Infinity, Infinity );
  // returns NaN
  
  d = reldiff( -Infinity, -Infinity );
  // returns NaN
  

• If |x| = |-y| = infinity, the relative difference is +infinity.

  var d = reldiff( Infinity, -Infinity );
  // returns Infinity
  
  d = reldiff( -Infinity, Infinity );
  // returns Infinity
  

• If a scale function returns 0, the function returns NaN.

  var d = reldiff( 0.0, 2.0, 'mean' ); // => |2/1|
  // returns 2.0
  
  d = reldiff( -1.0, 1.0, 'mean' ); // => |2/0|
  // returns NaN
  

Examples

var randu = require( '@stdlib/random/base/randu' );
var reldiff = require( '@stdlib/math/base/utils/relative-difference' );

var scales = [ 'max-abs', 'max', 'min-abs', 'min', 'mean-abs', 'mean', 'x', 'y' ];
var x;
var y;
var d;
var i;
var j;

for ( i = 0; i < 100; i++ ) {
    x = ( randu()*1.0e4 ) - 5.0e3;
    y = ( randu()*1.0e4 ) - 5.0e3;
    for ( j = 0; j < scales.length; j++ ) {
        d = reldiff( x, y, scales[j] );
        console.log( 'x = %d. y = %d. d = %d. scale: %s.', x, y, d, scales[j] );
    }
}