# Relative Difference
> Compute the [relative difference][relative-difference] of two real numbers.
The [relative difference][relative-difference] of two real `numbers` is defined as
where `|x-y|` is the [absolute difference][@stdlib/math/base/utils/absolute-difference] and `f(x,y)` is a scale function. Common scale functions include
The choice of scale function depends on application context.
## Usage
```javascript
var reldiff = require( '@stdlib/math/base/utils/relative-difference' );
```
#### reldiff( x, y\[, scale] )
Computes the [relative difference][relative-difference] of two real numbers.
```javascript
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][@stdlib/math/base/special/abs] of `x` and `y` (_default_).
- **max**: maximum value of `x` and `y`.
- **min-abs**: minimum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`.
- **min**: minimum value of `x` and `y`.
- **mean-abs**: arithmetic mean of the [absolute values][@stdlib/math/base/special/abs] 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][@stdlib/math/base/utils/absolute-difference] by dividing the [absolute difference][@stdlib/math/base/utils/absolute-difference] by the maximum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`. To scale by a different function, specify a scale function name.
```javascript
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`.
```javascript
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][@stdlib/math/base/utils/absolute-difference] of `x` and `y` is `0`, the relative difference is **always** `0`.
```javascript
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`.
```javascript
var d = reldiff( Infinity, Infinity );
// returns NaN
d = reldiff( -Infinity, -Infinity );
// returns NaN
```
- If `|x| = |-y| = infinity`, the relative difference is `+infinity`.
```javascript
var d = reldiff( Infinity, -Infinity );
// returns Infinity
d = reldiff( -Infinity, Infinity );
// returns Infinity
```
- If a `scale` function returns `0`, the function returns `NaN`.
```javascript
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
```javascript
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] );
}
}
```
[@stdlib/math/base/special/abs]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/special/abs
[@stdlib/math/base/utils/absolute-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/absolute-difference
[relative-difference]: https://en.wikipedia.org/wiki/Relative_change_and_difference
