time-to-botec

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

README.md (4612B)

      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 > [Erlang][erlang-distribution] distribution [quantile function][quantile-function].
     24 
     25 <section class="intro">
     26 
     27 The [quantile function][quantile-function] for an [Erlang][erlang-distribution] random variable is
     28 
     29 <!-- <equation class="equation" label="eq:erlang_quantile_function" align="center" raw="Q(p;k,\lambda) = \frac{1}{\lambda} P^{-1}\left( p, k \right )" alt="Quantile function for a Erlang distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="Q(p;k,\lambda) = \frac{1}{\lambda} P^{-1}\left( p, k \right )" data-equation="eq:erlang_quantile_function">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/erlang/quantile/docs/img/equation_erlang_quantile_function.svg" alt="Quantile function for a Erlang distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 for `0 <= p < 1`, where `k` is the shape parameter and `lambda` is the rate parameter of the distribution.  `P^{-1}` is the inverse of the lower regularized incomplete gamma function. The [Erlang][erlang-distribution] distribution is a special case of the gamma distribution, as `k` is constrained to the natural numbers.
     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/erlang/quantile' );
     50 ```
     51 
     52 #### quantile( p, k, lambda )
     53 
     54 Evaluates the [quantile function][quantile-function] for an [Erlang][erlang-distribution] distribution with parameters `k` (shape parameter) and `lambda` (rate parameter).
     55 
     56 ```javascript
     57 var y = quantile( 0.8, 2, 1.0 );
     58 // returns ~2.994
     59 
     60 y = quantile( 0.5, 4, 2.0 );
     61 // returns ~1.836
     62 ```
     63 
     64 If provided a probability `p` outside the interval `[0,1]`, the function returns `NaN`.
     65 
     66 ```javascript
     67 var y = quantile( 1.9, 1, 1.0 );
     68 // returns NaN
     69 
     70 y = quantile( -0.1, 1, 1.0 );
     71 // returns NaN
     72 ```
     73 
     74 If provided `NaN` as any argument, the function returns `NaN`.
     75 
     76 ```javascript
     77 var y = quantile( NaN, 1, 1.0 );
     78 // returns NaN
     79 
     80 y = quantile( 0.0, NaN, 1.0 );
     81 // returns NaN
     82 
     83 y = quantile( 0.0, 1, NaN );
     84 // returns NaN
     85 ```
     86 
     87 If provided a `k` which is not a nonnegative integer, the function returns `NaN`.
     88 
     89 ```javascript
     90 var y = quantile( 0.4, -1, 1.0 );
     91 // returns NaN
     92 
     93 y = quantile( 0.4, 2.5, 1.0 );
     94 // returns NaN
     95 ```
     96 
     97 If provided `k = 0`, the function evaluates the [quantile function][quantile-function] of a [degenerate distribution][degenerate-distribution] centered at `0`.
     98 
     99 ```javascript
    100 var y = quantile( 0.3, 0, 2.0 );
    101 // returns 0.0
    102 
    103 y = quantile( 0.9, 0, 2.0 );
    104 // returns 0.0
    105 ```
    106 
    107 If provided `lambda <= 0`, the function returns `NaN`.
    108 
    109 ```javascript
    110 var y = quantile( 0.4, 1, -1.0 );
    111 // returns NaN
    112 ```
    113 
    114 #### quantile.factory( k, lambda )
    115 
    116 Returns a function for evaluating the [quantile function][quantile-function] of an [Erlang][erlang-distribution] distribution with parameters `k` (shape parameter) and `lambda` (rate parameter).
    117 
    118 ```javascript
    119 var myquantile = quantile.factory( 2, 2.0 );
    120 var y = myquantile( 0.8 );
    121 // returns ~1.497
    122 
    123 y = myquantile( 0.4 );
    124 // returns ~0.688
    125 ```
    126 
    127 </section>
    128 
    129 <!-- /.usage -->
    130 
    131 <section class="examples">
    132 
    133 ## Examples
    134 
    135 <!-- eslint no-undef: "error" -->
    136 
    137 ```javascript
    138 var randu = require( '@stdlib/random/base/randu' );
    139 var round = require( '@stdlib/math/base/special/round' );
    140 var quantile = require( '@stdlib/stats/base/dists/erlang/quantile' );
    141 
    142 var lambda;
    143 var k;
    144 var p;
    145 var y;
    146 var i;
    147 
    148 for ( i = 0; i < 20; i++ ) {
    149     p = randu();
    150     k = round( randu() * 10.0 );
    151     lambda = randu() * 5.0;
    152     y = quantile( p, k, lambda );
    153     console.log( 'p: %d, k: %d, λ: %d, Q(p;k,λ): %d', p.toFixed( 4 ), k, lambda.toFixed( 4 ), y.toFixed( 4 ) );
    154 }
    155 ```
    156 
    157 </section>
    158 
    159 <!-- /.examples -->
    160 
    161 <section class="links">
    162 
    163 [degenerate-distribution]: https://en.wikipedia.org/wiki/Degenerate_distribution
    164 
    165 [erlang-distribution]: https://en.wikipedia.org/wiki/Erlang_distribution
    166 
    167 [quantile-function]: https://en.wikipedia.org/wiki/Quantile_function
    168 
    169 </section>
    170 
    171 <!-- /.links -->