time-to-botec

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

README.md (4298B)

      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 > [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution [quantile function][quantile].
     24 
     25 <section class="intro">
     26 
     27 The [quantile function][quantile] for a [Kumaraswamy's double bounded][kumaraswamy-distribution] random variable is
     28 
     29 <!-- <equation class="equation" label="eq:beta_quantile_function" align="center" raw="Q(p;a,b) = \left( 1 - (1-p)^{\tfrac{1}{b}} \right)^{\tfrac{1}{a}}" alt="Quantile function for a Kumaraswamy's double bounded distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="Q(p;a,b) = \left( 1 - (1-p)^{\tfrac{1}{b}} \right)^{\tfrac{1}{a}}" data-equation="eq:beta_quantile_function">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/kumaraswamy/quantile/docs/img/equation_beta_quantile_function.svg" alt="Quantile function for a Kumaraswamy's double bounded distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 for `0 <= p <= 1`, where `a > 0` is the first shape parameter and `b > 0` is the second shape parameter.
     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/kumaraswamy/quantile' );
     50 ```
     51 
     52 #### quantile( p, a, b )
     53 
     54 Evaluates the [quantile function][quantile] for a [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution with parameters `a` (first shape parameter) and `b` (second shape parameter).
     55 
     56 ```javascript
     57 var y = quantile( 0.5, 1.0, 1.0 );
     58 // returns 0.5
     59 
     60 y = quantile( 0.5, 2.0, 4.0 );
     61 // returns ~0.399
     62 
     63 y = quantile( 0.2, 2.0, 2.0 );
     64 // returns ~0.325
     65 
     66 y = quantile( 0.8, 4.0, 4.0 );
     67 // returns ~0.759
     68 ```
     69 
     70 If provided a probability `p` outside the interval `[0,1]`, the function returns `NaN`.
     71 
     72 ```javascript
     73 var y = quantile( -0.5, 4.0, 2.0 );
     74 // returns NaN
     75 
     76 y = quantile( 1.5, 4.0, 2.0 );
     77 // returns NaN
     78 ```
     79 
     80 If provided `NaN` as any argument, the function returns `NaN`.
     81 
     82 ```javascript
     83 var y = quantile( NaN, 1.0, 1.0 );
     84 // returns NaN
     85 
     86 y = quantile( 0.2, NaN, 1.0 );
     87 // returns NaN
     88 
     89 y = quantile( 0.2, 1.0, NaN );
     90 // returns NaN
     91 ```
     92 
     93 If provided `a <= 0`, the function returns `NaN`.
     94 
     95 ```javascript
     96 var y = quantile( 0.2, -1.0, 0.5 );
     97 // returns NaN
     98 
     99 y = quantile( 0.2, 0.0, 0.5 );
    100 // returns NaN
    101 ```
    102 
    103 If provided `b <= 0`, the function returns `NaN`.
    104 
    105 ```javascript
    106 var y = quantile( 0.2, 0.5, -1.0 );
    107 // returns NaN
    108 
    109 y = quantile( 0.2, 0.5, 0.0 );
    110 // returns NaN
    111 ```
    112 
    113 #### quantile.factory( a, b )
    114 
    115 Returns a function for evaluating the [quantile function][quantile] for a [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution with parameters `a` (first shape parameter) and `b` (second shape parameter).
    116 
    117 ```javascript
    118 var myQuantile = quantile.factory( 0.5, 0.5 );
    119 
    120 var y = myQuantile( 0.8 );
    121 // returns ~0.922
    122 
    123 y = myQuantile( 0.3 );
    124 // returns ~0.26
    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 EPS = require( '@stdlib/constants/float64/eps' );
    140 var quantile = require( '@stdlib/stats/base/dists/kumaraswamy/quantile' );
    141 
    142 var a;
    143 var b;
    144 var p;
    145 var y;
    146 var i;
    147 
    148 for ( i = 0; i < 10; i++ ) {
    149     p = randu();
    150     a = ( randu()*5.0 ) + EPS;
    151     b = ( randu()*5.0 ) + EPS;
    152     y = quantile( p, a, b );
    153     console.log( 'p: %d, a: %d, b: %d, Q(p;a,b): %d', p.toFixed( 4 ), a.toFixed( 4 ), b.toFixed( 4 ), y.toFixed( 4 ) );
    154 }
    155 ```
    156 
    157 </section>
    158 
    159 <!-- /.examples -->
    160 
    161 <section class="links">
    162 
    163 [kumaraswamy-distribution]: https://en.wikipedia.org/wiki/Kumaraswamy_distribution
    164 
    165 [quantile]: https://en.wikipedia.org/wiki/Quantile_function
    166 
    167 </section>
    168 
    169 <!-- /.links -->