README.md (4121B)
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 > [Student's t][t-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] (in [nats][nats]) for a [Student's t][t-distribution] random variable with degrees of freedom `ν` is 30 31 <!-- <equation class="equation" label="eq:t_entropy" align="center" raw="h\left( X \right) = \frac{\nu +1}{2} \left[\psi\left({\frac{1+\nu }{2}}\right)-\psi\left({\frac{\nu }{2}}\right)\right]+\ln{\left[{\sqrt {\nu }}B\left({\frac{\nu }{2}},{\frac{1}{2}}\right)\right]}" alt="Differential entropy for a Student's t distribution."> --> 32 33 <div class="equation" align="center" data-raw-text="h\left( X \right) = \frac{\nu +1}{2} \left[\psi\left({\frac{1+\nu }{2}}\right)-\psi\left({\frac{\nu }{2}}\right)\right]+\ln{\left[{\sqrt {\nu }}B\left({\frac{\nu }{2}},{\frac{1}{2}}\right)\right]}" data-equation="eq:t_entropy"> 34 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/t/entropy/docs/img/equation_t_entropy.svg" alt="Differential entropy for a Student's t distribution."> 35 <br> 36 </div> 37 38 <!-- </equation> --> 39 40 where `Β` and `ψ` denote the [beta][beta-function] and [digamma][digamma] functions, respectively. 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/t/entropy' ); 54 ``` 55 56 #### entropy( v ) 57 58 Returns the [differential entropy][entropy] of a [Student's t][t-distribution] distribution with degrees of freedom `v` (in [nats][nats]). 59 60 ```javascript 61 var y = entropy( 9.0 ); 62 // returns ~1.533 63 64 y = entropy( 3.5 ); 65 // returns ~1.721 66 ``` 67 68 If provided `v <= 0`, the function returns `NaN`. 69 70 ```javascript 71 var y = entropy( -1.0 ); 72 // returns NaN 73 74 y = entropy( 0.0 ); 75 // returns NaN 76 ``` 77 78 </section> 79 80 <!-- /.usage --> 81 82 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 83 84 <section class="notes"> 85 86 </section> 87 88 <!-- /.notes --> 89 90 <!-- Package usage examples. --> 91 92 <section class="examples"> 93 94 ## Examples 95 96 <!-- eslint no-undef: "error" --> 97 98 ```javascript 99 var randu = require( '@stdlib/random/base/randu' ); 100 var round = require( '@stdlib/math/base/special/round' ); 101 var entropy = require( '@stdlib/stats/base/dists/t/entropy' ); 102 103 var v; 104 var y; 105 var i; 106 107 for ( i = 0; i < 10; i++ ) { 108 v = randu() * 20.0; 109 y = entropy( v ); 110 console.log( 'v: %d, h(X,v): %d', v.toFixed( 4 ), y.toFixed( 4 ) ); 111 } 112 ``` 113 114 </section> 115 116 <!-- /.examples --> 117 118 <!-- 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. --> 119 120 <section class="references"> 121 122 </section> 123 124 <!-- /.references --> 125 126 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 127 128 <section class="links"> 129 130 [t-distribution]: https://en.wikipedia.org/wiki/Student%27s_t-distribution 131 132 [entropy]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29 133 134 [nats]: https://en.wikipedia.org/wiki/Nat_%28unit%29 135 136 [beta-function]: https://en.wikipedia.org/wiki/Beta_function 137 138 [digamma]: https://en.wikipedia.org/wiki/Digamma_function 139 140 </section> 141 142 <!-- /.links -->