README.md (4590B)
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 # Entropy 22 23 > [Fréchet][frechet-distribution] distribution [differential entropy][entropy]. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 The [differential entropy][entropy] for a [Fréchet][frechet-distribution] random variable shape `α > 0`, scale `s > 0`, and location parameter `m` is 30 31 <!-- <equation class="equation" label="eq:frechet_entropy" align="center" raw="h\left( X \right) = 1+{\frac{\gamma }{\alpha }}+\gamma +\ln \left({\frac{s}{\alpha }}\right)" alt="Differential entropy for a Fréchet distribution."> --> 32 33 <div class="equation" align="center" data-raw-text="h\left( X \right) = 1+{\frac{\gamma }{\alpha }}+\gamma +\ln \left({\frac{s}{\alpha }}\right)" data-equation="eq:frechet_entropy"> 34 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/frechet/entropy/docs/img/equation_frechet_entropy.svg" alt="Differential entropy for a Fréchet distribution."> 35 <br> 36 </div> 37 38 <!-- </equation> --> 39 40 where `γ` is the [Euler–Mascheroni constant][euler-mascheroni]. 41 42 </section> 43 44 <!-- /.intro --> 45 46 <!-- Package usage documentation. --> 47 48 <section class="usage"> 49 50 ## Usage 51 52 ```javascript 53 var entropy = require( '@stdlib/stats/base/dists/frechet/entropy' ); 54 ``` 55 56 #### entropy( alpha, s, m ) 57 58 Returns the [differential entropy][entropy] for a [Fréchet][frechet-distribution] distribution with shape `alpha > 0`, scale `s > 0`, and location parameter `m` (in [nats][nats]). 59 60 ```javascript 61 var y = entropy( 2.0, 1.0, 1.0 ); 62 // returns ~1.173 63 64 y = entropy( 1.0, 1.0, -1.0 ); 65 // returns ~2.154 66 67 y = entropy( 1.0, 1.0, 2.0 ); 68 // returns ~2.154 69 ``` 70 71 If provided `NaN` as any argument, the function returns `NaN`. 72 73 ```javascript 74 var y = entropy( NaN, 1.0, -2.0 ); 75 // returns NaN 76 77 y = entropy( 1.0, NaN, -2.0 ); 78 // returns NaN 79 80 y = entropy( 1.0, 1.0, NaN ); 81 // returns NaN 82 ``` 83 84 If provided `alpha <= 0`, the function returns `NaN`. 85 86 ```javascript 87 var y = entropy( 0.0, 3.0, 2.0 ); 88 // returns NaN 89 90 y = entropy( 0.0, -1.0, 2.0 ); 91 // returns NaN 92 ``` 93 94 If provided `s <= 0`, the function returns `NaN`. 95 96 ```javascript 97 var y = entropy( 1.0, 0.0, 2.0 ); 98 // returns NaN 99 100 y = entropy( 1.0, -1.0, 2.0 ); 101 // returns NaN 102 ``` 103 104 </section> 105 106 <!-- /.usage --> 107 108 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 109 110 <section class="notes"> 111 112 </section> 113 114 <!-- /.notes --> 115 116 <!-- Package usage examples. --> 117 118 <section class="examples"> 119 120 ## Examples 121 122 <!-- eslint no-undef: "error" --> 123 124 ```javascript 125 var randu = require( '@stdlib/random/base/randu' ); 126 var EPS = require( '@stdlib/constants/float64/eps' ); 127 var entropy = require( '@stdlib/stats/base/dists/frechet/entropy' ); 128 129 var alpha; 130 var m; 131 var s; 132 var y; 133 var i; 134 135 for ( i = 0; i < 10; i++ ) { 136 alpha = ( randu()*20.0 ) + EPS; 137 s = ( randu()*20.0 ) + EPS; 138 m = ( randu()*20.0 ) - 40.0; 139 y = entropy( alpha, s, m ); 140 console.log( 'α: %d, s: %d, m: %d, h(X;α,s,m): %d', alpha.toFixed( 4 ), s.toFixed( 4 ), m.toFixed( 4 ), y.toFixed( 4 ) ); 141 } 142 ``` 143 144 </section> 145 146 <!-- /.examples --> 147 148 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 149 150 <section class="references"> 151 152 </section> 153 154 <!-- /.references --> 155 156 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 157 158 <section class="links"> 159 160 [euler-mascheroni]: https://en.wikipedia.org/wiki/Euler%E2%80%93Mascheroni_constant 161 162 [frechet-distribution]: https://en.wikipedia.org/wiki/Fr%C3%A9chet_distribution 163 164 [entropy]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29 165 166 [nats]: https://en.wikipedia.org/wiki/Nat_%28unit%29 167 168 </section> 169 170 <!-- /.links -->