README.md (4835B)
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 # Quantile Function 22 23 > [Hypergeometric][hypergeometric-distribution] distribution [quantile function][quantile-function]. 24 25 <section class="intro"> 26 27 Imagine a scenario with a population of size `N`, of which a subpopulation of size `K` can be considered successes. We draw `n` observations from the total population. Defining the random variable `X` as the number of successes in the `n` draws, `X` is said to follow a [hypergeometric distribution][hypergeometric-distribution]. 28 29 The [quantile function][quantile-function] for a [hypergeometric][hypergeometric-distribution] random variable returns for any `0 <= p <= 1` the value `x` for which 30 31 <!-- <equation class="equation" label="eq:hypergeometric_quantile_function" align="center" raw="F(x-1;N,K,n) < p \le F(x;N,K,n)" alt="Quantile value for a hypergeometric distribution."> --> 32 33 <div class="equation" align="center" data-raw-text="F(x-1;N,K,n) < p \le F(x;N,K,n)" data-equation="eq:hypergeometric_quantile_function"> 34 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/hypergeometric/quantile/docs/img/equation_hypergeometric_quantile_function.svg" alt="Quantile value for a hypergeometric distribution."> 35 <br> 36 </div> 37 38 <!-- </equation> --> 39 40 where `F` is the cumulative distribution function (CDF) of a hypergeometric random variable with parameters `N`, `K` and `n`, where `N` is the population size, `K` is the subpopulation size, and `n` is the number of draws. 41 42 </section> 43 44 <!-- /.intro --> 45 46 <section class="usage"> 47 48 ## Usage 49 50 ```javascript 51 var quantile = require( '@stdlib/stats/base/dists/hypergeometric/quantile' ); 52 ``` 53 54 #### quantile( p, N, K, n ) 55 56 Evaluates the [quantile function][quantile-function] for a [hypergeometric][hypergeometric-distribution] distribution with parameters `N` (population size), `K` (subpopulation size), and `n` (number of draws). 57 58 ```javascript 59 var y = quantile( 0.5, 8, 4, 2 ); 60 // returns 1 61 62 y = quantile( 0.9, 120, 80, 20 ); 63 // returns 16 64 65 y = quantile( 0.0, 120, 80, 50 ); 66 // returns 10 67 68 y = quantile( 0.0, 8, 4, 2 ); 69 // returns 0 70 ``` 71 72 If provided `NaN` as any argument, the function returns `NaN`. 73 74 ```javascript 75 var y = quantile( NaN, 10, 5, 2 ); 76 // returns NaN 77 78 y = quantile( 0.4, NaN, 5, 2 ); 79 // returns NaN 80 81 y = quantile( 0.4, 10, NaN, 2 ); 82 // returns NaN 83 84 y = quantile( 0.4, 10, 5, NaN ); 85 // returns NaN 86 ``` 87 88 If provided a population size `N`, subpopulation size `K` or draws `n` which is not a nonnegative integer, the function returns `NaN`. 89 90 ```javascript 91 var y = quantile( 0.2, 6.5, 5, 2 ); 92 // returns NaN 93 94 y = quantile( 0.2, 5, 1.5, 2 ); 95 // returns NaN 96 97 y = quantile( 0.2, 10, 5, -2.0 ); 98 // returns NaN 99 ``` 100 101 If the number of draws `n` or the subpopulation size `K` exceed population size `N`, the function returns `NaN`. 102 103 ```javascript 104 var y = quantile( 0.2, 10, 5, 12 ); 105 // returns NaN 106 107 y = quantile( 0.2, 8, 3, 9 ); 108 // returns NaN 109 ``` 110 111 #### quantile.factory( N, K, n ) 112 113 Returns a function for evaluating the [quantile function][quantile-function] for a [hypergeometric ][hypergeometric-distribution] distribution with parameters `N` (population size), `K` (subpopulation size), and `n` (number of draws). 114 115 ```javascript 116 var myquantile = quantile.factory( 100, 20, 10 ); 117 var y = myquantile( 0.2 ); 118 // returns 1 119 120 y = myquantile( 0.9 ); 121 // returns 4 122 ``` 123 124 </section> 125 126 <!-- /.usage --> 127 128 <section class="examples"> 129 130 ## Examples 131 132 <!-- eslint no-undef: "error" --> 133 134 ```javascript 135 var randu = require( '@stdlib/random/base/randu' ); 136 var round = require( '@stdlib/math/base/special/round' ); 137 var quantile = require( '@stdlib/stats/base/dists/hypergeometric/quantile' ); 138 139 var i; 140 var N; 141 var K; 142 var n; 143 var p; 144 var y; 145 146 for ( i = 0; i < 10; i++ ) { 147 p = randu(); 148 N = round( randu() * 20 ); 149 K = round( randu() * N ); 150 n = round( randu() * K ); 151 y = quantile( p, N, K, n ); 152 console.log( 'p: %d, N: %d, K: %d, n: %d, Q(p;N,K,n): %d', p.toFixed( 4 ), N, K, n, y.toFixed( 4 ) ); 153 } 154 ``` 155 156 </section> 157 158 <!-- /.examples --> 159 160 <section class="links"> 161 162 [hypergeometric-distribution]: https://en.wikipedia.org/wiki/hypergeometric_distribution 163 164 [quantile-function]: https://en.wikipedia.org/wiki/Quantile_function 165 166 </section> 167 168 <!-- /.links -->