-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathstatslib.html
396 lines (303 loc) · 16.8 KB
/
statslib.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="StatsLib is a templated C++ library for fast computation of statistical distribution functions.">
<meta name="author" content="Keith O'Hara">
<meta name="keywords" content="Statistics, Probability, Distributions, C++, Cpp, C++11, constexpr, Econometrics" />
<link rel="shortcut icon" type="image/x-icon" href="siteicon.ico">
<title>StatsLib</title>
<!-- Bootstrap Core CSS -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<!-- Custom CSS -->
<link href="css/modern-business.css" rel="stylesheet">
<!-- Custom Fonts -->
<link href="font-awesome/css/font-awesome.min.css" rel="stylesheet" type="text/css">
<!-- Additional Settings -->
<link href="css/yuxuan_settings.css" rel="stylesheet">
<!-- Syntax Highlighter -->
<script type="text/javascript" src="js/syntaxhighlighter.js"></script>
<link type="text/css" rel="stylesheet" href="css/swift_theme.css">
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-93902857-1', 'auto');
ga('send', 'pageview');
</script>
<script async defer src="https://buttons.github.io/buttons.js"></script>
<script src="js/jquery.js"></script>
<script>
$(function(){
$("#mynavbar").load("navbar.html")
$("#statshead").load("statslib_header.html")
$("#myfooter").load("footer.html")
});
</script>
</head>
<style>
pre {
display: inline-block;
}
</style>
<body>
<!-- Navigation -->
<div id="mynavbar"></div>
<!-- Page Content -->
<div class="container">
<!-- Page Heading/Breadcrumbs -->
<div id="statshead"></div>
<!-- -->
<div class="row">
<div class="col-md-1"></div>
<div class="col-md-2 hidden-xs hidden-sm">
<img src="pics/stats_pnorm.png" class="img-responsive center-block">
</div>
<div class="col-md-6">
<br>
<h3 style="text-align: center;"><strong style="font-size: 130%;"><u>StatsLib</u></strong></h3>
<p style="text-align: center;"><a class="github-button" href="https://github.com/kthohr/stats/subscription" data-icon="octicon-eye" data-show-count="true" aria-label="Watch kthohr/stats on GitHub">Watch</a>
<a class="github-button" href="https://github.com/kthohr/stats" data-icon="octicon-star" data-show-count="true" aria-label="Star kthohr/stats on GitHub">Star</a>
<a class="github-button" href="https://github.com/kthohr/stats/fork" data-icon="octicon-repo-forked" data-show-count="true" aria-label="Fork kthohr/stats on GitHub">Fork</a>
</p>
<p style="text-align: center;"><a href="https://github.com/fffaraz/awesome-cpp#math" target="_blank"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Cpp"></a>
<a href="https://travis-ci.org/kthohr/stats" target="_blank"><img src="https://travis-ci.org/kthohr/stats.svg?branch=master" alt="StatsLib Build"></a>
<a href="https://codecov.io/github/kthohr/stats?branch=master" target="_blank"><img src="https://codecov.io/github/kthohr/stats/coverage.svg?branch=master" alt="Coverage Status"></a>
<a href="https://www.codacy.com/app/kthohr/stats?utm_source=github.com&utm_medium=referral&utm_content=kthohr/stats&utm_campaign=Badge_Grade" target="_blank"><img src="https://api.codacy.com/project/badge/Grade/d6460e046dd5428aac53d28a1ce58401" alt="Code Quality"></a>
</p>
</div>
<div class="col-md-2 hidden-xs hidden-sm">
<img src="pics/stats_qlaplace.png" class="img-responsive center-block">
</div>
</div>
<br>
<div class="row">
<div class="col-md-2"></div>
<div class="col-md-8">
<!-- <p>StatsLib is a templated C++ library for random variable generation and fast computation of statistical distribution functions.</p> -->
<p>StatsLib is a templated C++ library of statistical distribution functions, featuring unique compile-time computing capabilities and seamless integration with several popular linear algebra libraries.</p>
<hr>
<p><strong>Features</strong></p>
<ul>
<li>A header-only library of probability density functions, cumulative distribution functions, quantile functions, and random sampling methods.</li>
<li>Functions are written in a specialized C++11 <code>constexpr</code> format, enabling the library to operate as both a compile-time and run-time computation engine.</li>
<li>Designed with a simple <strong>R</strong>-like syntax.</li>
<li>Optional vector-matrix functionality with wrappers to support:</li>
<ul>
<li><a href="http://arma.sourceforge.net/" target="_blank">Armadillo</a></li>
<li><a href="https://bitbucket.org/blaze-lib/blaze" target="_blank">Blaze</a></li>
<li><a href="http://eigen.tuxfamily.org/index.php" target="_blank">Eigen</a></li>
</ul>
<li>Matrix-based operations are parallelizable with OpenMP.</li>
<li>Released under a permissive, non-GPL license.</li>
</ul>
<br>
<p><strong>Author</strong>: Keith O'Hara</p>
<p><a href="https://raw.githubusercontent.com/kthohr/stats/master/LICENSE" target="_blank"><img src="https://img.shields.io/badge/Licence-Apache%202.0-blue.svg" alt="License"></a></p>
<hr>
<p><strong>Contents</strong></p>
<ul>
<li><a href="#distributions">Distributions</a></li>
<li><a href="#installation">Download and Installation</a></li>
<li><a href="#jupyter-notebook">Jupyter Notebook</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#syntax-and-examples">Syntax and Examples</a></li>
<li><a href="#compile-time-computation-capabilities">Compile-time Computation Capabilities</a></li>
</ul>
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="distributions"><strong style="font-size: 95%;">Distributions</strong></h3>
<p>Functions to compute the cdf, pdf, and quantile, as well as random sampling methods, are available for the following distributions:</p>
<ul>
<li><a href="statslib_docs_bern.html" target="_blank">Bernoulli</a></li>
<li><a href="statslib_docs_beta.html" target="_blank">Beta</a></li>
<li><a href="statslib_docs_binom.html" target="_blank">Binomial</a></li>
<li><a href="statslib_docs_cauchy.html" target="_blank">Cauchy</a></li>
<li><a href="statslib_docs_chisq.html" target="_blank">Chi-squared</a></li>
<li><a href="statslib_docs_exp.html" target="_blank">Exponential</a></li>
<li><a href="statslib_docs_f.html" target="_blank">F</a></li>
<li><a href="statslib_docs_gamma.html" target="_blank">Gamma</a></li>
<li><a href="statslib_docs_invgamma.html" target="_blank">Inverse-Gamma</a></li>
<li><a href="statslib_docs_laplace.html" target="_blank">Laplace</a></li>
<li><a href="statslib_docs_lnorm.html" target="_blank">Log-Normal</a></li>
<li><a href="statslib_docs_logis.html" target="_blank">Logistic</a></li>
<li><a href="statslib_docs_norm.html" target="_blank">Normal</a></li>
<li><a href="statslib_docs_pois.html" target="_blank">Poisson</a></li>
<li><a href="statslib_docs_t.html" target="_blank">Student t</a></li>
<li><a href="statslib_docs_unif.html" target="_blank">Uniform</a></li>
<li><a href="statslib_docs_weibull.html" target="_blank">Weibull</a></li>
</ul>
In addition, pdf and randomization functions are available for several multivariate distributions:
<ul>
<li><a href="statslib_docs_invwish.html" target="_blank">Inverse-Wishart</a></li>
<li><a href="statslib_docs_mvnorm.html" target="_blank">Multivariate Normal</a></li>
<li><a href="statslib_docs_wish.html" target="_blank">Wishart</a></li>
</ul>
<!-- -->
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="installation"><strong style="font-size: 95%;">Download and Installation</strong></h3>
<ul>
<li>The source code is available on <a href="https://github.com/kthohr/stats" target="_blank">GitHub</a>.Download the latest version with git:</li>
<pre class="brush: bash;">
git clone -b master --single-branch https://github.com/kthohr/stats ./stats</pre>
</ul>
<p>StatsLib is a <strong>header-only library</strong>. Simply add the header files to your project using</p>
<pre class="brush: cpp;">
#include "stats.hpp"</pre>
<p>The only dependencies are a C++11-compatible compiler and the <a href="gcem.html" target="_blank">GCE-Math library</a> which comes pre-packaged with StatsLib.</p>
<hr>
<p>To build the test files:</p>
<pre class="brush: bash;">
# clone stats
git clone -b master --single-branch https://github.com/kthohr/stats ./stats
# compile tests
cd ./stats/tests
./setup
cd dens
./configure && make</pre>
<!-- -->
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="jupyter-notebook"><strong style="font-size: 95%;">Jupyter Notebook</strong></h3>
<p>You can test the library online using an interactive Jupyter notebook:</p>
<a href="https://mybinder.org/v2/gh/kthohr/stats/master?filepath=notebooks%2Fstats.ipynb" target="_blank"><img src="https://mybinder.org/badge.svg" alt="Binder"></a>
<!-- -->
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="options"><strong style="font-size: 95%;">Options</strong></h3>
<p>The following options should be declared <strong>before</strong> including the StatsLib header files.</p>
<ul>
<li>For inline-only functionality (i.e., no <code>constexpr</code> specifiers):</li>
<pre class="brush: c++;">
#define STATS_GO_INLINE</pre>
<li>OpenMP functionality is enabled by default if the <code>_OPENMP</code> macro is detected (e.g., by invoking <code>-fopenmp</code> with a GCC or Clang compiler). To explicitly enable OpenMP features use:</li>
<pre class="brush: c++;">
#define STATS_USE_OPENMP</pre>
<li>To disable OpenMP functionality:</li>
<pre class="brush: c++;">
#define STATS_DONT_USE_OPENMP</pre>
<li>To use StatsLib with Armadillo, Blaze or Eigen:</li>
<pre class="brush: c++;">
#define STATS_USE_ARMA
#define STATS_USE_BLAZE
#define STATS_USE_EIGEN</pre>
</ul>
<!-- -->
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="syntax-and-examples"><strong style="font-size: 95%;">Syntax and Examples</strong></h3>
<p>Functions are called using an R-like syntax. Some general rules:</p>
<ul>
<li><code>stats::d*</code> density functions. For example, the <a href="statslib_docs_norm.html#density" target="_blank">Normal (Gaussian) density</a> is called using</li>
<pre class="brush: c++;">
stats::dnorm(<value>,<mean parameter>,<standard deviation>);</pre>
<li><code>stats::p*</code> cumulative distribution functions. For example, the <a href="statslib_docs_gamma.html#probability" target="_blank">Gamma CDF</a> is called using</li>
<pre class="brush: c++;">
stats::pgamma(<value>,<shape parameter>,<scale parameter>);</pre>
<li><code>stats::q*</code> quantile functions. For example, the <a href="statslib_docs_beta.html#quantile" target="_blank">Beta quantile</a> is called using</li>
<pre class="brush: c++;">
stats::qbeta(<value>,<a parameter>,<b parameter>);</pre>
<li><code>stats::r*</code> random sampling. For example, to generate a single <a href="statslib_docs_logis.html#random" target="_blank">draw from the Logistic distribution</a>:</li>
<pre class="brush: c++;">
stats::rlogis(<location parameter>,<scale parameter>,<seed value or random number engine>);</pre>
</ul>
<hr>
<h4 style="text-align: left;"><strong style="font-size: 95%;">Matrices</strong></h4>
<p>All of these functions have matrix-based equivalents using Armadillo, Blaze, and Eigen dense matrices.</p>
<ul>
<li>The pdf, cdf, and quantile functions can take matrix-valued arguments. For example,</li>
<pre class="brush: c++;">
// Using Armadillo:
arma::mat norm_pdf_vals = stats::dnorm(arma::ones(10,20),1.0,2.0);</pre>
<li>The randomization functions (<code>r*</code>) can output random matrices of arbitrary size. For example,
<pre class="brush: c++;">
// Armadillo:
arma::mat gamma_rvs = stats::rgamma<arma::mat>(100,50,3.0,2.0);
// Blaze:
blaze::DynamicMatrix<double> gamma_rvs = stats::rgamma<blaze::DynamicMatrix<double>>(100,50,3.0,2.0);
// Eigen:
Eigen::MatrixXd gamma_rvs = stats::rgamma<Eigen::MatrixXd>(100,50,3.0,2.0);</pre>
will generate a 100-by-50 matrix of iid draws from a Gamma(3,2) distribution.</li>
<li>All matrix-based operations are parallelizable with OpenMP. For GCC and Clang compilers, simply include the <code>-fopenmp</code> option during compilation.</li>
</ul>
<hr>
<h4 style="text-align: left;"><strong style="font-size: 95%;">Seeding</strong></h4>
<p>Random number seeding is available in two formats: seed values and random number engines.</p>
<ul>
<li>Seed values are passed as unsigned integers. For example, to generate a draw from a normal distribution N(1,2) with seed value 1776:</li>
<pre class="brush: c++;">
stats::rnorm(1,2,1776);</pre>
<li>Random engines in StatsLib use the 64-bit Mersenne-Twister generator (std::mt19937_64) and are passed by reference. Example:</li>
<pre class="brush: c++;">
std::mt19937_64 engine(1776);
stats::rnorm(1,2,engine);</pre>
</ul>
<hr>
<h4 style="text-align: left;"><strong style="font-size: 95%;">Examples</strong></h4>
<p>More examples with code:</p>
<pre class="brush: c++;">
// evaluate the normal PDF at x = 1, mu = 0, sigma = 1
double dval_1 = stats::dnorm(1.0,0.0,1.0)
// evaluate the normal PDF at x = 1, mu = 0, sigma = 1, and return the log value
double dval_2 = stats::dnorm(1.0,0.0,1.0,true)
// evaluate the normal CDF at x = 1, mu = 0, sigma = 1
double pval_1 = stats::pnorm(1.0,0.0,1.0)
// evaluate the Laplacian quantile at p = 0.1, mu = 0, sigma = 1
double qval_1 = stats::qlaplace(0.1,0.0,1.0)
// draw from a t-distribution with dof = 30
double rval = stats::rt(30);
// matrix output
arma::mat beta_rvs = stats::rbeta<arma::mat>(100,100,3.0,2.0);
// matrix input
arma::mat beta_cdf_vals = stats::pbeta(beta_rvs,3.0,2.0);
</pre>
<!-- -->
<hr style="height:2px;border-width:0;background-color:black">
<h3 style="text-align: left;" id="compile-time-computation-capabilities"><strong style="font-size: 95%;">Compile-time Computation Capabilities</strong></h3>
<p>StatsLib is designed to operate equally well as a compile-time computation engine. Compile-time computation allows the compiler to replace function calls (e.g., <code>dnorm(0,0,1)</code>) with static values in the source code. That is, functions are evaluated during the compilation process, rather than at run-time. This capability is made possible due to the templated <code>constexpr</code> design of the library and can be verified by inspecting the assembly code generated by the compiler.</p>
<p>The compile-time features are enabled using the <code>constexpr</code> specifier. The example below computes the pdf, cdf, and quantile function of the Laplace distribution:</p>
<pre class="brush: c++;">
#include "stats.hpp"
int main()
{
constexpr double dens_1 = stats::dlaplace(1.0,1.0,2.0); // answer = 0.25
constexpr double prob_1 = stats::plaplace(1.0,1.0,2.0); // answer = 0.5
constexpr double quant_1 = stats::qlaplace(0.1,1.0,2.0); // answer = -2.218875...
return 0;
}
</pre>
<p>Assembly code generated by Clang without any optimization:</p>
<pre class="brush: text;">
LCPI0_0:
.quad -4611193153885729483 ## double -2.2188758248682015
LCPI0_1:
.quad 4602678819172646912 ## double 0.5
LCPI0_2:
.quad 4598175219545276417 ## double 0.25000000000000006
.section __TEXT,__text,regular,pure_instructions
.globl _main
.p2align 4, 0x90
_main: ## @main
push rbp
mov rbp, rsp
xor eax, eax
movsd xmm0, qword ptr [rip + LCPI0_0] ## xmm0 = mem[0],zero
movsd xmm1, qword ptr [rip + LCPI0_1] ## xmm1 = mem[0],zero
movsd xmm2, qword ptr [rip + LCPI0_2] ## xmm2 = mem[0],zero
mov dword ptr [rbp - 4], 0
movsd qword ptr [rbp - 16], xmm2
movsd qword ptr [rbp - 24], xmm1
movsd qword ptr [rbp - 32], xmm0
pop rbp
ret
</pre>
<hr>
</div>
</div>
</div>
<div id="myfooter"></div>
<!-- jQuery -->
<!--<script src="js/jquery.js"></script>-->
<!-- Bootstrap Core JavaScript -->
<script src="js/bootstrap.min.js"></script>
</body>
</html>