time-to-botec

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

README.md (3888B)

      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 > [Chi-squared][chisquare-distribution] distribution [cumulative distribution function][cdf].
     24 
     25 <section class="intro">
     26 
     27 The [cumulative distribution function][cdf] for a [chi-squared][chisquare-distribution] random variable is
     28 
     29 <!-- <equation class="equation" label="eq:chisquare_cdf" align="center" raw="F(x;\,k) = P\left(\frac{x}{2},\,\frac{k}{2}\right)" alt="Cumulative distribution function for a chi-squared distribution."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="F(x;\,k) = P\left(\frac{x}{2},\,\frac{k}{2}\right)" data-equation="eq:chisquare_cdf">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/chisquare/cdf/docs/img/equation_chisquare_cdf.svg" alt="Cumulative distribution function for a chi-squared distribution.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 where `k` is the degrees of freedom and `P` is the lower regularized incomplete gamma function.
     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/chisquare/cdf' );
     50 ```
     51 
     52 #### cdf( x, k )
     53 
     54 Evaluates the [cumulative distribution function][cdf] (CDF) for a [chi-squared][chisquare-distribution] distribution with degrees of freedom `k`.
     55 
     56 ```javascript
     57 var y = cdf( 2.0, 1.0 );
     58 // returns ~0.843
     59 
     60 y = cdf( 2.0, 3.0 );
     61 // returns ~0.428
     62 
     63 y = cdf( 1.0, 0.5 );
     64 // returns ~0.846
     65 
     66 y = cdf( -1.0, 2.0 );
     67 // returns 0.0
     68 
     69 y = cdf( -Infinity, 4.0 );
     70 // returns 0.0
     71 
     72 y = cdf( +Infinity, 4.0 );
     73 // returns 1.0
     74 ```
     75 
     76 If provided `NaN` as any argument, the function returns `NaN`.
     77 
     78 ```javascript
     79 var y = cdf( NaN, 1.0 );
     80 // returns NaN
     81 
     82 y = cdf( 0.0, NaN );
     83 // returns NaN
     84 ```
     85 
     86 If provided `k < 0`, the function returns `NaN`.
     87 
     88 ```javascript
     89 var y = cdf( 2.0, -2.0 );
     90 // returns NaN
     91 ```
     92 
     93 If provided `k = 0`, the function evaluates the [CDF][cdf] of a [degenerate distribution][degenerate-distribution] centered at `0`.
     94 
     95 ```javascript
     96 var y = cdf( 2.0, 0.0 );
     97 // returns 1.0
     98 
     99 y = cdf( -2.0, 0.0 );
    100 // returns 0.0
    101 
    102 y = cdf( 0.0, 0.0 );
    103 // returns 1.0
    104 ```
    105 
    106 #### cdf.factory( k )
    107 
    108 Returns a function for evaluating the [cumulative distribution function][cdf] for a [chi-squared][chisquare-distribution] distribution with degrees of freedom `k`.
    109 
    110 ```javascript
    111 var mycdf = cdf.factory( 3.0 );
    112 
    113 var y = mycdf( 6.0 );
    114 // returns ~0.888
    115 
    116 y = mycdf( 1.5 );
    117 // returns ~0.318
    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 round = require( '@stdlib/math/base/special/round' );
    133 var cdf = require( '@stdlib/stats/base/dists/chisquare/cdf' );
    134 
    135 var k;
    136 var x;
    137 var y;
    138 var i;
    139 
    140 for ( i = 0; i < 20; i++ ) {
    141     x = randu() * 10.0;
    142     k = round( randu()*5.0 );
    143     y = cdf( x, k );
    144     console.log( 'x: %d, k: %d, F(x;k): %d', x.toFixed( 4 ), k.toFixed( 4 ), y.toFixed( 4 ) );
    145 }
    146 ```
    147 
    148 </section>
    149 
    150 <!-- /.examples -->
    151 
    152 <section class="links">
    153 
    154 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function
    155 
    156 [chisquare-distribution]: https://en.wikipedia.org/wiki/Chi-squared_distribution
    157 
    158 [degenerate-distribution]: https://en.wikipedia.org/wiki/Degenerate_distribution
    159 
    160 </section>
    161 
    162 <!-- /.links -->