README.md (7040B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Relative Difference 22 23 > Compute the [relative difference][relative-difference] of two real numbers. 24 25 <section class="intro"> 26 27 The [relative difference][relative-difference] of two real `numbers` is defined as 28 29 <!-- <equation class="equation" label="eq:relative_difference" align="center" raw="\Delta(x,y) = \frac{|x - y|}{|f(x,y)|} = \left|\frac{x - y}{f(x,y)}\right|" alt="Relative difference"> --> 30 31 <div class="equation" align="center" data-raw-text="\Delta(x,y) = \frac{|x - y|}{|f(x,y)|} = \left|\frac{x - y}{f(x,y)}\right|" data-equation="eq:relative_difference"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@bb29798906e119fcb2af99e94b60407a270c9b32/lib/node_modules/@stdlib/math/base/utils/relative-difference/docs/img/equation_relative_difference.svg" alt="Relative difference"> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 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 39 40 <!-- <equation class="equation" label="eq:scale_functions" align="center" raw="\begin{align*}f(x,y) &= \max(|x|, |y|)\\f(x,y) &= \max(x,y)\\ f(x,y) &= \min(|x|,|y|)\\f(x,y) &= \min(x,y) \\f(x,y) &= \frac{|x|+|y|}{2} \\f(x,y) &= \frac{x + y}{2}\end{align*}" alt="Scale functions"> --> 41 42 <div class="equation" align="center" data-raw-text="\begin{align*}f(x,y) &= \max(|x|, |y|)\\f(x,y) &= \max(x,y)\\ f(x,y) &= \min(|x|,|y|)\\f(x,y) &= \min(x,y) \\f(x,y) &= \frac{|x|+|y|}{2} \\f(x,y) &= \frac{x + y}{2}\end{align*}" data-equation="eq:scale_functions"> 43 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@bb29798906e119fcb2af99e94b60407a270c9b32/lib/node_modules/@stdlib/math/base/utils/relative-difference/docs/img/equation_scale_functions.svg" alt="Scale functions"> 44 <br> 45 </div> 46 47 <!-- </equation> --> 48 49 The choice of scale function depends on application context. 50 51 </section> 52 53 <!-- /.intro --> 54 55 <section class="usage"> 56 57 ## Usage 58 59 ```javascript 60 var reldiff = require( '@stdlib/math/base/utils/relative-difference' ); 61 ``` 62 63 #### reldiff( x, y\[, scale] ) 64 65 Computes the [relative difference][relative-difference] of two real numbers. 66 67 ```javascript 68 var d = reldiff( 2.0, 5.0 ); // => 3/5 69 // returns 0.6 70 71 d = reldiff( -1.0, 3.14 ); // => 4.14/3.14 72 // returns ~1.318 73 ``` 74 75 The following `scale` functions are supported: 76 77 - **max-abs**: maximum [absolute value][@stdlib/math/base/special/abs] of `x` and `y` (_default_). 78 - **max**: maximum value of `x` and `y`. 79 - **min-abs**: minimum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`. 80 - **min**: minimum value of `x` and `y`. 81 - **mean-abs**: arithmetic mean of the [absolute values][@stdlib/math/base/special/abs] of `x` and `y`. 82 - **mean**: arithmetic mean of `x` and `y`. 83 - **x**: `x` (_noncommutative_). 84 - **y**: `y` (_noncommutative_). 85 86 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. 87 88 ```javascript 89 var d = reldiff( -2.0, 5.0 ); // => |-7/5| 90 // returns 1.4 91 92 d = reldiff( -2.0, 5.0, 'max-abs' ); // => |-7/5| 93 // returns 1.4 94 95 d = reldiff( -2.0, 5.0, 'max' ); // => |-7/5| 96 // returns 1.4 97 98 d = reldiff( -2.0, 5.0, 'min-abs' ); // => |-7/2| 99 // returns 3.5 100 101 d = reldiff( -2.0, 5.0, 'min' ); // => |-7/-2| 102 // returns 3.5 103 104 d = reldiff( -2.0, 5.0, 'mean-abs' ); // => |-7/3.5| 105 // returns 2.0 106 107 d = reldiff( -2.0, 5.0, 'mean' ); // => |-7/1.5| 108 // returns ~4.67 109 110 d = reldiff( -2.0, 5.0, 'x' ); // => |-7/-2| 111 // returns 3.5 112 113 d = reldiff( 5.0, -2.0, 'x' ); // => |7/5| 114 // returns 1.4 115 116 d = reldiff( -2.0, 5.0, 'y' ); // => |-7/5| 117 // returns 1.4 118 119 d = reldiff( 5.0, -2.0, 'y' ); // => |7/-2| 120 // returns 3.5 121 ``` 122 123 To use a custom scale `function`, provide a `function` which accepts two numeric arguments `x` and `y`. 124 125 ```javascript 126 var abs = require( '@stdlib/math/base/special/abs' ); 127 var EPS = require( '@stdlib/constants/float64/eps' ); 128 129 function scale( x, y ) { 130 var s; 131 x = abs( x ); 132 y = abs( y ); 133 134 // Maximum absolute value: 135 s = (x < y ) ? y : x; 136 137 // Scale in units of epsilon: 138 return s * EPS; 139 } 140 141 var d = reldiff( 12.15, 12.149999999999999, scale ); 142 // returns ~0.658 143 ``` 144 145 </section> 146 147 <!-- /.usage --> 148 149 <section class="notes"> 150 151 ## Notes 152 153 - If the [absolute difference][@stdlib/math/base/utils/absolute-difference] of `x` and `y` is `0`, the relative difference is **always** `0`. 154 155 ```javascript 156 var d = reldiff( 0.0, 0.0 ); 157 // returns 0.0 158 159 d = reldiff( 3.14, 3.14 ); 160 // returns 0.0 161 ``` 162 163 - If `|x| = |y| = infinity`, the function returns `NaN`. 164 165 ```javascript 166 var d = reldiff( Infinity, Infinity ); 167 // returns NaN 168 169 d = reldiff( -Infinity, -Infinity ); 170 // returns NaN 171 ``` 172 173 - If `|x| = |-y| = infinity`, the relative difference is `+infinity`. 174 175 ```javascript 176 var d = reldiff( Infinity, -Infinity ); 177 // returns Infinity 178 179 d = reldiff( -Infinity, Infinity ); 180 // returns Infinity 181 ``` 182 183 - If a `scale` function returns `0`, the function returns `NaN`. 184 185 ```javascript 186 var d = reldiff( 0.0, 2.0, 'mean' ); // => |2/1| 187 // returns 2.0 188 189 d = reldiff( -1.0, 1.0, 'mean' ); // => |2/0| 190 // returns NaN 191 ``` 192 193 </section> 194 195 <!-- /.notes --> 196 197 <section class="examples"> 198 199 ## Examples 200 201 <!-- eslint no-undef: "error" --> 202 203 ```javascript 204 var randu = require( '@stdlib/random/base/randu' ); 205 var reldiff = require( '@stdlib/math/base/utils/relative-difference' ); 206 207 var scales = [ 'max-abs', 'max', 'min-abs', 'min', 'mean-abs', 'mean', 'x', 'y' ]; 208 var x; 209 var y; 210 var d; 211 var i; 212 var j; 213 214 for ( i = 0; i < 100; i++ ) { 215 x = ( randu()*1.0e4 ) - 5.0e3; 216 y = ( randu()*1.0e4 ) - 5.0e3; 217 for ( j = 0; j < scales.length; j++ ) { 218 d = reldiff( x, y, scales[j] ); 219 console.log( 'x = %d. y = %d. d = %d. scale: %s.', x, y, d, scales[j] ); 220 } 221 } 222 ``` 223 224 </section> 225 226 <!-- /.examples --> 227 228 <section class="links"> 229 230 [@stdlib/math/base/special/abs]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/special/abs 231 232 [@stdlib/math/base/utils/absolute-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/absolute-difference 233 234 [relative-difference]: https://en.wikipedia.org/wiki/Relative_change_and_difference 235 236 </section> 237 238 <!-- /.links -->