time-to-botec

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

README.md (4184B)

      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 > [Fréchet][frechet-distribution] distribution [quantile function][quantile].
     24 
     25 <section class="intro">
     26 
     27 The [quantile function][quantile] for a [Fréchet][frechet-distribution] random variable is
     28 
     29 <!-- <equation class="equation" label="eq:frechet_quantile" align="center" raw="Q\left( p; \alpha, s, m \right ) = m + s ( -\ln p )^{-\tfrac{1}{\alpha}}" alt="Quantile function for a Fréchet distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="Q\left( p; \alpha, s, m \right ) = m + s ( -\ln p )^{-\tfrac{1}{\alpha}}" data-equation="eq:frechet_quantile">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/frechet/quantile/docs/img/equation_frechet_quantile.svg" alt="Quantile function for a Fréchet distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 where `alpha > 0` is the shape, `s > 0` the scale, and `m` the location 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/frechet/quantile' );
     50 ```
     51 
     52 #### quantile( p, alpha, s, m )
     53 
     54 Evaluates the [quantile function][quantile] for a [Fréchet][frechet-distribution] distribution with shape `alpha`, scale `s`, and location `m` at a probability `p`.
     55 
     56 ```javascript
     57 var y = quantile( 0.8, 2.0, 3.0, 5.0 );
     58 // returns ~11.351
     59 
     60 y = quantile( 0.1, 1.0, 2.0, -4.0 );
     61 // returns ~-3.131
     62 
     63 y = quantile( 0.3, 2.0, 1.0, -1.0 );
     64 // returns ~-0.089
     65 ```
     66 
     67 If provided a probability `p` outside the interval `[0,1]`, the function returns `NaN`.
     68 
     69 ```javascript
     70 var y = quantile( 1.9, 2.0, 2.0, 0.0 );
     71 // returns NaN
     72 
     73 y = quantile( -0.1, 2.0, 2.0, 0.0 );
     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, 1.0, 0.0 );
     81 // returns NaN
     82 
     83 y = quantile( 0.9, NaN, 1.0, 0.0 );
     84 // returns NaN
     85 
     86 y = quantile( 0.9, 1.0, NaN, 0.0);
     87 // returns NaN
     88 
     89 y = quantile( 0.9, 1.0, 1.0, NaN );
     90 // returns NaN
     91 ```
     92 
     93 If provided `alpha <= 0`, the function returns `NaN`.
     94 
     95 ```javascript
     96 var y = quantile( 0.1, -0.1, 1.0, 1.0 );
     97 // returns NaN
     98 
     99 y = quantile( 0.1, 0.0, 1.0, 1.0 );
    100 // returns NaN
    101 ```
    102 
    103 If provided `s <= 0`, the function returns `NaN`.
    104 
    105 ```javascript
    106 var y = quantile( 0.3, 1.0, -1.0, 1.0 );
    107 // returns NaN
    108 
    109 y = quantile( 0.3, 1.0, 0.0, 1.0 );
    110 // returns NaN
    111 ```
    112 
    113 #### quantile.factory( alpha, s, m )
    114 
    115 Returns a function for evaluating the [quantile function][quantile] of a [Fréchet][frechet-distribution] distribution with shape `alpha`, scale `s`, and location `m`.
    116 
    117 ```javascript
    118 var myQuantile = quantile.factory( 3.0, 3.0, 5.0 );
    119 
    120 var y = myQuantile( 0.7 );
    121 // returns ~9.23
    122 
    123 y = myQuantile( 0.2 );
    124 // returns ~7.56
    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 quantile = require( '@stdlib/stats/base/dists/frechet/quantile' );
    140 
    141 var alpha;
    142 var m;
    143 var s;
    144 var p;
    145 var y;
    146 var i;
    147 
    148 for ( i = 0; i < 100; i++ ) {
    149     alpha = randu() * 10.0;
    150     p = randu();
    151     s = randu() * 10.0;
    152     m = randu() * 10.0;
    153     y = quantile( p, alpha, s, m );
    154     console.log( 'x: %d, α: %d, s: %d, m: %d, Q(p;α,s,m): %d', p.toFixed( 4 ), alpha.toFixed( 4 ), s.toFixed( 4 ), m.toFixed( 4 ), y.toFixed( 4 ) );
    155 }
    156 ```
    157 
    158 </section>
    159 
    160 <!-- /.examples -->
    161 
    162 <section class="links">
    163 
    164 [frechet-distribution]: https://en.wikipedia.org/wiki/Fr%C3%A9chet_distribution
    165 
    166 [quantile]: https://en.wikipedia.org/wiki/Quantile_function
    167 
    168 </section>
    169 
    170 <!-- /.links -->