time-to-botec

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

README.md (4093B)

      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 > [Binomial][binomial-distribution] distribution [quantile function][quantile-function].
     24 
     25 <section class="intro">
     26 
     27 The [quantile function][quantile-function] for a [binomial][binomial-distribution] random variable returns, for any `r` satisfying `0 <= r <= 1`, the value `x` for which the relation
     28 
     29 <!-- <equation class="equation" label="eq:binomial_quantile_function" align="center" raw="F(x-1;n,p) < r \le F(x;n,p)" alt="Quantile value for a binomial distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="F(x-1;n,p) &lt; r \le F(x;n,p)" data-equation="eq:binomial_quantile_function">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/binomial/quantile/docs/img/equation_binomial_quantile_function.svg" alt="Quantile value for a binomial distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 holds, where `F` is the cumulative distribution function (CDF) of a binomial random variable, `n` is the number of trials, and `0 <= p <= 1` is the success probability.
     39 
     40 </section>
     41 
     42 <!-- /.intro -->
     43 
     44 <section class="usage">
     45 
     46 ## Usage
     47 
     48 ```javascript
     49 var quantile = require( '@stdlib/stats/base/dists/binomial/quantile' );
     50 ```
     51 
     52 #### quantile( r, n, p )
     53 
     54 Evaluates the [quantile function][quantile-function] for a [binomial][binomial-distribution] distribution with number of trials `n` and success probability `p` at value `r`.
     55 
     56 ```javascript
     57 var y = quantile( 0.4, 20, 0.2 );
     58 // returns 3
     59 
     60 y = quantile( 0.8, 20, 0.2 );
     61 // returns 5
     62 
     63 y = quantile( 0.5, 10, 0.4 );
     64 // returns 4
     65 
     66 y = quantile( 0.0, 10, 0.4 );
     67 // returns 0
     68 
     69 y = quantile( 1.0, 10, 0.4 );
     70 // returns 10
     71 ```
     72 
     73 If provided `NaN` as any argument, the function returns `NaN`.
     74 
     75 ```javascript
     76 var y = quantile( NaN, 20, 0.5 );
     77 // returns NaN
     78 
     79 y = quantile( 0.2, NaN, 0.5 );
     80 // returns NaN
     81 
     82 y = quantile( 0.2, 20, NaN );
     83 // returns NaN
     84 ```
     85 
     86 If provided a number of trials `n` which is not a nonnegative integer, the function returns `NaN`.
     87 
     88 ```javascript
     89 var y = quantile( 0.5, 1.5, 0.5 );
     90 // returns NaN
     91 
     92 y = quantile( 0.5, -2.0, 0.5 );
     93 // returns NaN
     94 ```
     95 
     96 If provided a success probability `p` outside of `[0,1]`, the function returns `NaN`.
     97 
     98 ```javascript
     99 var y = quantile( 0.5, 20, -1.0 );
    100 // returns NaN
    101 
    102 y = quantile( 0.5, 20, 1.5 );
    103 // returns NaN
    104 ```
    105 
    106 #### quantile.factory( n, p )
    107 
    108 Returns a function for evaluating the [quantile function][quantile-function] of a [binomial][binomial-distribution] distribution with number of trials `n` and success probability `p`.
    109 
    110 ```javascript
    111 var myquantile = quantile.factory( 10, 0.5 );
    112 
    113 var y = myquantile( 0.1 );
    114 // returns 3
    115 
    116 y = myquantile( 0.9 );
    117 // returns 7
    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 quantile = require( '@stdlib/stats/base/dists/binomial/quantile' );
    134 
    135 var r;
    136 var i;
    137 var n;
    138 var p;
    139 var y;
    140 
    141 for ( i = 0; i < 10; i++ ) {
    142     r = randu();
    143     n = round( randu() * 100.0 );
    144     p = randu();
    145     y = quantile( r, n, p );
    146     console.log( 'r: %d, n: %d, p: %d, Q(r;n,p): %d', r.toFixed( 4 ), n, p.toFixed( 4 ) );
    147 }
    148 ```
    149 
    150 </section>
    151 
    152 <!-- /.examples -->
    153 
    154 <section class="links">
    155 
    156 [binomial-distribution]: https://en.wikipedia.org/wiki/Binomial_distribution
    157 
    158 [quantile-function]: https://en.wikipedia.org/wiki/Quantile_function
    159 
    160 </section>
    161 
    162 <!-- /.links -->