time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (4601B)

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