time-to-botec

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

README.md (4060B)

      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 # Cumulative Distribution Function
     22 
     23 > [F][f-distribution] distribution [cumulative distribution function][cdf].
     24 
     25 <section class="intro">
     26 
     27 The [cumulative distribution function][cdf] for a [F][f-distribution] random variable is
     28 
     29 <!-- <equation class="equation" label="eq:f_cdf" align="center" raw="F(x; d_1,d_2)=I_{\frac{d_1 x}{d_1 x + d_2}}\left (\tfrac{d_1}{2}, \tfrac{d_2}{2} \right)" alt="Cumulative distribution function for an F distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="F(x; d_1,d_2)=I_{\frac{d_1 x}{d_1 x + d_2}}\left (\tfrac{d_1}{2}, \tfrac{d_2}{2} \right)" data-equation="eq:f_cdf">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/f/cdf/docs/img/equation_f_cdf.svg" alt="Cumulative distribution function for an F distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 where `d1` is the numerator degrees of freedom, `d2` is the denominator degrees of freedom and `I_{x}(a,b)` is the [lower regularized incomplete beta function][@stdlib/math/base/special/betainc].
     39 
     40 </section>
     41 
     42 <!-- /.intro -->
     43 
     44 <section class="usage">
     45 
     46 ## Usage
     47 
     48 ```javascript
     49 var cdf = require( '@stdlib/stats/base/dists/f/cdf' );
     50 ```
     51 
     52 #### cdf( x, d1, d2 )
     53 
     54 Evaluates the [cumulative distribution function][cdf] (CDF) for a [F][f-distribution] distribution with parameters `d1` (numerator degrees of freedom) and `d2` (denominator degrees of freedom).
     55 
     56 ```javascript
     57 var y = cdf( 2.0, 1.0, 1.0 );
     58 // returns ~0.608
     59 
     60 y = cdf( 2.0, 8.0, 4.0 );
     61 // returns ~0.737
     62 
     63 y = cdf( -Infinity, 4.0, 2.0 );
     64 // returns 0.0
     65 
     66 y = cdf( 0.0, 4.0, 4.0 );
     67 // returns 0.0
     68 
     69 y = cdf( +Infinity, 4.0, 2.0 );
     70 // returns 1.0
     71 ```
     72 
     73 If provided `NaN` as any argument, the function returns `NaN`.
     74 
     75 ```javascript
     76 var y = cdf( NaN, 1.0, 1.0 );
     77 // returns NaN
     78 
     79 y = cdf( 0.0, NaN, 1.0 );
     80 // returns NaN
     81 
     82 y = cdf( 0.0, 1.0, NaN );
     83 // returns NaN
     84 ```
     85 
     86 If provided `d1 <= 0`, the function returns `NaN`.
     87 
     88 ```javascript
     89 var y = cdf( 2.0, -1.0, 0.5 );
     90 // returns NaN
     91 
     92 y = cdf( 2.0, 0.0, 0.5 );
     93 // returns NaN
     94 ```
     95 
     96 If provided `d2 <= 0`, the function returns `NaN`.
     97 
     98 ```javascript
     99 var y = cdf( 2.0, 0.5, -1.0 );
    100 // returns NaN
    101 
    102 y = cdf( 2.0, 0.5, 0.0 );
    103 // returns NaN
    104 ```
    105 
    106 #### cdf.factory( d1, d2 )
    107 
    108 Returns a function for evaluating the [cumulative distribution function][cdf] of a [F][f-distribution] distribution with parameters `d1` (numerator degrees of freedom) and `d2` (denominator degrees of freedom).
    109 
    110 ```javascript
    111 var mycdf = cdf.factory( 10.0, 2.0 );
    112 
    113 var y = mycdf( 10.0 );
    114 // returns ~0.906
    115 
    116 y = mycdf( 8.0 );
    117 // returns ~0.884
    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 cdf = require( '@stdlib/stats/base/dists/f/cdf' );
    133 
    134 var d1;
    135 var d2;
    136 var x;
    137 var y;
    138 var i;
    139 
    140 for ( i = 0; i < 10; i++ ) {
    141     x = randu() * 10.0;
    142     d1 = randu() * 10.0;
    143     d2 = randu() * 10.0;
    144     y = cdf( x, d1, d2 );
    145     console.log( 'x: %d, d1: %d, d2: %d, F(x;d1,d2): %d', x.toFixed( 4 ), d1.toFixed( 4 ), d2.toFixed( 4 ), y.toFixed( 4 ) );
    146 }
    147 ```
    148 
    149 </section>
    150 
    151 <!-- /.examples -->
    152 
    153 <section class="links">
    154 
    155 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function
    156 
    157 [f-distribution]: https://en.wikipedia.org/wiki/F_distribution
    158 
    159 [@stdlib/math/base/special/betainc]: https://www.npmjs.com/package/@stdlib/math-base-special-betainc
    160 
    161 </section>
    162 
    163 <!-- /.links -->