math-relative-difference v1.0.0

Relative Difference

Computes 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.

Installation

$ npm install math-relative-difference

Usage

var diff = require( 'math-relative-difference' );

diff( x, y, scale )

Computes the relative difference of two real numbers.

var d = diff( 2, 5 );
// returns 3/5 = 0.6

d = diff( -1, 3.14 );
// returns 4.14/3.14 = ~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 = diff( -2, 5 );
// returns |-7/5| = 1.4

d = diff( -2, 5, 'max-abs' );
// returns |-7/5| = 1.4

d = diff( -2, 5, 'max' )
// returns |-7/5| = 1.4

d = diff( -2, 5, 'min-abs' );
// returns |-7/2| = 3.5

d = diff( -2, 5, 'min' );
// returns |-7/-2| = 3.5

d = diff( -2, 5, 'mean-abs' );
// returns |-7/3.5| = 2

d = diff( -2, 5, 'mean' );
// returns |-7/1.5| = ~4.67

d = diff( -2, 5, 'x' );
// returns |-7/-2| = 3.5

d = diff( 5, -2, 'x' );
// returns |7/5| = 1.4

d = diff( -2, 5, 'y' );
// returns |-7/5| = 1.4

d = diff( 5, -2, 'y' );
// returns |7/-2| = 3.5

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

var abs = require( 'math-abs' );
var EPS = require( 'const-eps-float64' );

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 = diff( 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 = diff( 0, 0 );
  // returns 0
  
  d = diff( 3.14, 3.14 );
  // returns 0

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

  var PINF = Number.POSITIVE_INFINITY;
  var NINF = Number.NEGATIVE_INFINITY;
  
  var d = diff( PINF, PINF );
  // returns NaN
  
  d = diff( NINF, NINF );
  // returns NaN

• If `|x| = |-y| = infinity`, the relative difference is `+infinity`.
  
  	``` javascript
  	var PINF = Number.POSITIVE_INFINITY;
  	var NINF = Number.NEGATIVE_INFINITY;
  
  	var d = diff( PINF, NINF );
  	// returns +infinity
  
  	d = diff( NINF, PINF );
  	// returns +infinity
  	```

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

  var d = diff( 0, 2, 'mean' );
  // returns |2/1| = 2
  
  d = diff( -1, 1, 'mean' );
  // returns NaN => |2/0|

Examples

var diff = require( 'math-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 = Math.random()*1e4 - 5e3;
	y = Math.random()*1e4 - 5e3;
	for ( j = 0; j < scales.length; j++ ) {
		d = diff( x, y, scales[j] );
		console.log( 'x = %d. y = %d. d = %d. scale: %s.', x, y, d, scales[j] );
	}
}

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

$ make test-browsers

To view the tests in a local web browser,

$ make view-browser-tests

License

MIT license.

Copyright

Copyright © 2016. The Compute.io Authors.