time-to-botec

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

README.md (3950B)

      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 > [Poisson][poisson-distribution] distribution [quantile function][quantile-function].
     24 
     25 <section class="intro">
     26 
     27 The [quantile function][quantile-function] for a [Poisson][poisson-distribution] random variable returns for `0 <= p <= 1` the smallest nonnegative integer for which
     28 
     29 <!-- <equation class="equation" label="eq:poisson_condition" align="center" raw="F(x;\lambda) \ge p" alt="Quantile condition."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="F(x;\lambda) \ge p" data-equation="eq:poisson_condition">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/poisson/quantile/docs/img/equation_poisson_condition.svg" alt="Quantile condition.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 where `F` is the cumulative distribution function (CDF) of a Poisson distribution with mean parameter `lambda > 0`.
     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/poisson/quantile' );
     50 ```
     51 
     52 #### quantile( p, lambda )
     53 
     54 Evaluates the [quantile function][quantile-function] for a [Poisson][poisson-distribution] distribution with mean parameter `lambda` at a probability `p`.
     55 
     56 ```javascript
     57 var y = quantile( 0.5, 2.0 );
     58 // returns 2
     59 
     60 y = quantile( 0.9, 4.0 );
     61 // returns 7
     62 
     63 y = quantile( 0.1, 200.0 );
     64 // returns 182
     65 ```
     66 
     67 If provided an input probability `p` outside the interval `[0,1]`, the function returns `NaN`.
     68 
     69 ```javascript
     70 var y = quantile( 1.9, 0.5 );
     71 // returns NaN
     72 
     73 y = quantile( -0.1, 0.5 );
     74 // returns NaN
     75 ```
     76 
     77 If provided `NaN` as any argument, the function returns `NaN`.
     78 
     79 ```javascript
     80 var y = quantile( NaN, 1.0 );
     81 // returns NaN
     82 
     83 y = quantile( 0.0, NaN );
     84 // returns NaN
     85 ```
     86 
     87 If provided a negative `lambda`, the function returns `NaN`.
     88 
     89 ```javascript
     90 var y = quantile( 0.4, -1.0 );
     91 // returns NaN
     92 ```
     93 
     94 If provided `lambda = 0`, the function evaluates the [quantile function][quantile-function] of a [degenerate distribution][degenerate-distribution] centered at `0.0`.
     95 
     96 ```javascript
     97 var y = quantile( 0.1, 0.0 );
     98 // returns 0.0
     99 
    100 y = quantile( 0.9, 0.0 );
    101 // returns 0.0
    102 ```
    103 
    104 #### quantile.factory( lambda )
    105 
    106 Returns a function for evaluating the [quantile function][quantile-function] of a [Poisson][poisson-distribution] distribution with mean parameter `lambda`.
    107 
    108 ```javascript
    109 var myquantile = quantile.factory( 5.0 );
    110 var y = myquantile( 0.4 );
    111 // returns 4
    112 
    113 y = myquantile( 0.8 );
    114 // returns 7
    115 
    116 y = myquantile( 1.0 );
    117 // returns Infinity
    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 quantile = require( '@stdlib/stats/base/dists/poisson/quantile' );
    133 
    134 var lambda;
    135 var p;
    136 var y;
    137 var i;
    138 
    139 for ( i = 0; i < 10; i++ ) {
    140     p = randu();
    141     lambda = randu() * 10.0;
    142     y = quantile( p, lambda );
    143     console.log( 'p: %d, λ: %d, Q(p;λ): %d', p.toFixed( 4 ), lambda.toFixed( 4 ), y );
    144 }
    145 ```
    146 
    147 </section>
    148 
    149 <!-- /.examples -->
    150 
    151 <section class="links">
    152 
    153 [poisson-distribution]: https://en.wikipedia.org/wiki/Poisson_distribution
    154 
    155 [quantile-function]: https://en.wikipedia.org/wiki/Quantile_function
    156 
    157 [degenerate-distribution]: https://en.wikipedia.org/wiki/Degenerate_distribution
    158 
    159 </section>
    160 
    161 <!-- /.links -->