forked from google-deepmind/torch-distributions
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
472 lines (355 loc) · 17.4 KB
/
index.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
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<title>Probability distributions for Torch</title>
<link rel="stylesheet" href="stylesheets/styles.css">
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div class="wrapper">
<div id="navcontainer">
<ul>
<li>
<a href="#toc_0">Probability distributions for Torch</a>
<ul>
<li>
<a href="#toc_1">Example</a>
<ul>
<li>
<a href="#toc_2">Getting/setting the seed and the state</a>
</li>
</ul>
</li>
<li>
<a href="#toc_3">Installation</a>
</li>
<li>
<a href="#toc_4">List of Distributions</a>
<ul>
<li>
<a href="#toc_5">Poisson: poisson</a>
<ul>
<li>
<a href="#toc_6">poisson.pdf(x, lambda)</a>
</li>
<li>
<a href="#toc_7">poisson.logpdf(x, lambda)</a>
</li>
<li>
<a href="#toc_8">poisson.cdf(x, lambda)</a>
</li>
</ul>
</li>
<li>
<a href="#toc_9">Normal/Gaussian: norm</a>
<ul>
<li>
<a href="#toc_10">norm.pdf(x, mu, sigma)</a>
</li>
<li>
<a href="#toc_11">norm.logpdf(x, mu, sigma)</a>
</li>
<li>
<a href="#toc_12">norm.cdf(x, mu, sigma)</a>
</li>
</ul>
</li>
<li>
<a href="#toc_13">Multivariate Normal: mvn</a>
<ul>
<li>
<a href="#toc_14">mnv.pdf(x, mu, M, [options])</a>
</li>
<li>
<a href="#toc_15">mvn.logpdf(x, mu, M, [options])</a>
</li>
<li>
<a href="#toc_16">mvn.rnd([res,] mu, M, [options])</a>
</li>
</ul>
</li>
<li>
<a href="#toc_17">Categorical/Multinomial: cat</a>
<ul>
<li>
<a href="#toc_18">cat.pdf(x, p, [options])</a>
</li>
<li>
<a href="#toc_19">cat.logpdf(x, p, [options])</a>
</li>
<li>
<a href="#toc_20">cat.rnd([res|N,] p, [options])</a>
</li>
</ul>
</li>
<li>
<a href="#toc_21">Multiple Categorical: mvcat</a>
<ul>
<li>
<a href="#toc_22">mvcat.pdf(x, p, [options])</a>
</li>
<li>
<a href="#toc_23">mvcat.logpdf(x, p, [options])</a>
</li>
<li>
<a href="#toc_24">mvcat.rnd([res|N,] p, [options])</a>
</li>
</ul>
</li>
<li>
<a href="#toc_25">Cauchy: cauchy</a>
<ul>
<li>
<a href="#toc_26">cauch.pdf(x, a, b)</a>
</li>
<li>
<a href="#toc_27">cauchy.logpdf(x, a, b)</a>
</li>
<li>
<a href="#toc_28">cauchy.cdf(x, a, b)</a>
</li>
</ul>
</li>
<li>
<a href="#toc_29">Chi square: chi2</a>
<ul>
<li>
<a href="#toc_30">chi2.pdf(x, dof)</a>
</li>
<li>
<a href="#toc_31">chi2.logpdf(x, dof)</a>
</li>
<li>
<a href="#toc_32">chi2.cdf(x, dof)</a>
</li>
</ul>
</li>
<li>
<a href="#toc_33">Laplace: laplace</a>
<ul>
<li>
<a href="#toc_34">laplace.pdf(x, loc, scale)</a>
</li>
<li>
<a href="#toc_35">laplace.logpdf(x, loc, scale)</a>
</li>
<li>
<a href="#toc_36">laplace.cdf(x, loc, scale)</a>
</li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#toc_37">Hypothesis Testing</a>
<ul>
<li>
<a href="#toc_38">ksone(x1, cdf)</a>
</li>
<li>
<a href="#toc_39">kstwo(x1, x2)</a>
</li>
<li>
<a href="#toc_40">chi2Uniform(x, [low, up, nBins])</a>
</li>
<li>
<a href="#toc_41">chi2TestCDF(x, cdf, cdfParams, [nBins])</a>
</li>
<li>
<a href="#toc_42">chi2Gaussian(x, mu, sigma, [nBins])</a>
</li>
</ul>
</li>
<li>
<a href="#toc_43">Unit Tests</a>
</li>
</ul>
</li>
</ul>
</div>
<section>
<h1 id="toc_0">Probability distributions for Torch</h1>
<h2 id="toc_1">Example</h2>
<p>TODO</p>
<h3 id="toc_2">Getting/setting the seed and the state</h3>
<p>Distributions is transparently integrated with Torch's random stream: just use <code>torch.manualSeed(seed)</code>, <code>torch.getRNGState()</code>, and <code>torch.setRNGState(state)</code> as usual.</p>
<h2 id="toc_3">Installation</h2>
<p>From a terminal:</p>
<div class="highlight"><pre><code class="bash language-bash" data-lang="bash">luarocks install https://raw.github.com/jucor/torch-distributions/master/distributions-0-0.rockspec
</code></pre></div>
<h2 id="toc_4">List of Distributions</h2>
<h3 id="toc_5">Poisson: poisson</h3>
<h4 id="toc_6">poisson.pdf(x, lambda)</h4>
<p>Probability density function of a Poisson distribution with mean <code>lambda</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_7">poisson.logpdf(x, lambda)</h4>
<p>Log of probability density function of a Poisson distribution with mean <code>lambda</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_8">poisson.cdf(x, lambda)</h4>
<p>Cumulative distribution function of a Poisson distribution with mean <code>lambda</code>, evaluated at <code>x</code>.</p>
<h3 id="toc_9">Normal/Gaussian: norm</h3>
<h4 id="toc_10">norm.pdf(x, mu, sigma)</h4>
<p>Probability density function of a Normal distribution with mean <code>mu</code> and standard deviation <code>sigma</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_11">norm.logpdf(x, mu, sigma)</h4>
<p>Log probability density function of a Normal distribution with mean <code>mu</code> and standard deviation <code>sigma</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_12">norm.cdf(x, mu, sigma)</h4>
<p>Cumulative distribution function of a Normal distribution with mean <code>mu</code> and standard deviation <code>sigma</code>, evaluated at <code>x</code>.</p>
<h3 id="toc_13">Multivariate Normal: mvn</h3>
<p>The covariance matrix passed to multivariate gaussian functions needs only be positive <strong>semi</strong>-definite: we deal gracefully with the degenerate case of rank-deficient covariance. </p>
<p>Those functions also accept the upper-triangular Cholesky decomposition instead, by setting the field <code>cholesky = true</code> in the optional table <code>options</code>.</p>
<h4 id="toc_14">mnv.pdf(x, mu, M, [options])</h4>
<p>Probability density function of a multivariate Normal distribution with mean <code>mu</code> and covariance or cholesky of the covariance specified in <code>M</code>, evaluated at <code>x</code>. </p>
<p>By defaut, the matrix <code>M</code> is the covariance matrix. However, it is possible to pass the upper-triangular Cholesky decomposition instead, by setting the field <code>cholesky = true</code> in the optional table <code>options</code>.</p>
<p>For a D-dimensional Normal, the following forms are valid:</p>
<ul>
<li><code>mvn.pdf([D], [D], [D, D])</code> - returns a number.</li>
<li><code>mvn.pdf([N, D], [D], [D, D])</code> - returns a Tensor.</li>
<li><code>mvn.pdf([D], [N, D], [D, D])</code> - returns a Tensor.</li>
<li><code>mvn.pdf([N, D], [N, D], [D, D])</code> - returns a Tensor.</li>
</ul>
<p>In the case of a diagonal covariance <code>cov</code>, you may also opt to pass a vector containing only the diagonal elements:</p>
<ul>
<li><code>mvn.pdf([D], [D], [D])</code> - returns a number.</li>
<li><code>mvn.pdf([N, D], [D], [D])</code> - returns a Tensor.</li>
<li><code>mvn.pdf([D], [N, D], [D])</code> - returns a Tensor.</li>
<li><code>mvn.pdf([N, D], [N, D], [D])</code> - returns a Tensor.</li>
</ul>
<h4 id="toc_15">mvn.logpdf(x, mu, M, [options])</h4>
<p>Probability density function of a multivariate Normal distribution with mean <code>mu</code> and covariance matrix <code>M</code>, evaluated at <code>x</code>.</p>
<p>See <code>mvn.pdf()</code> for description of valid forms for x, mu and cov and options.</p>
<h4 id="toc_16">mvn.rnd([res,] mu, M, [options])</h4>
<p>Sample from a multivariate Normal distribution with mean <code>mu</code> and covariance matrix <code>M</code>.</p>
<p>For a D-dimensional Normal, the following forms are valid:</p>
<ul>
<li><code>mvn.rnd([D], [D, D])</code> - returns 1 sample in a 1-by-D Tensor</li>
<li><code>mvn.rnd([N, D], [D, D])</code> - returns N samples in a N-by-D Tensor</li>
<li><code>mvn.rnd([N, D], [D], [D, D])</code> - stores and returns N samples in the N-by-D Tensor</li>
<li><code>mvn.rnd([N, D], [N, D], [D, D])</code> - stores and returns N samples in the N-by-D Tensor</li>
</ul>
<p>In the case of a diagonal covariance <code>cov</code>, you may also opt to pass a vector (not a matrix) containing only the diagonal elements.</p>
<p>By defaut, the matrix <code>M</code> is the covariance matrix. However, it is possible to pass the upper-triangular Cholesky decomposition instead, by setting the field <code>cholesky = true</code> in the optional table <code>options</code>.</p>
<h3 id="toc_17">Categorical/Multinomial: cat</h3>
<p>Categorical distributions on indices from 1 to K = p:numel().</p>
<p>Not vectorized in p. See mvcat for vectorized version.</p>
<h4 id="toc_18">cat.pdf(x, p, [options])</h4>
<p>Not implemented</p>
<h4 id="toc_19">cat.logpdf(x, p, [options])</h4>
<p>Not implemented</p>
<h4 id="toc_20">cat.rnd([res|N,] p, [options])</h4>
<p>Sample <code>N = size(res,1)</code> amongst <code>K = 1 ... p:numel()</code>, where the probability of category k is given by p[k]/p:sum().</p>
<p>Options is a table containing:</p>
<ul>
<li><p>options.type Type of sampler:</p>
<ul>
<li><code>nil</code> or <code>'iid'</code>: default, i.i.d samples, use linear search in O(N log N + max(K, N)), best when K/N is close to 1.</li>
<li>'dichotomy': dichotomic search, same variance, faster when small K large N</li>
<li>'stratified': sorted stratified samples, sample has lower variance than i.i.d. but not independent, best when K/N is close to 1</li>
</ul></li>
<li><p>options.categories Categories to sample from</p>
<ul>
<li><code>nil</code>: default, returns integers between 1 and K</li>
<li>K-by-D tensor: each row is a category, must have has many rows as p:numel()</li>
</ul></li>
</ul>
<p>Returns a LongTensor vector with N elements in the resulting tensor if no categories is given,
or a new tensor of N rows corresponding to the categories given.</p>
<p>Note that it is not yet possible to use a result tensor <em>and</em> categories at the same time. This will be possible once <a href="https://github.com/torch/torch7-distro/issues/202">torch's index() accepts result tensor</a>.</p>
<h3 id="toc_21">Multiple Categorical: mvcat</h3>
<p>Vectorized version of <code>cat</code>, where <code>p</code> is now a matrix where each row represents a vector of probabilities. It samples independently for each row of <code>p</code>.</p>
<h4 id="toc_22">mvcat.pdf(x, p, [options])</h4>
<p>Not implemented</p>
<h4 id="toc_23">mvcat.logpdf(x, p, [options])</h4>
<p>Not implemented</p>
<h4 id="toc_24">mvcat.rnd([res|N,] p, [options])</h4>
<p>For each row <code>r = 1 ... R</code> of the matrix <code>p</code>, sample <code>N = size(res, 2)</code> amongst <code>K = 1 ... p:size(2)</code>, where the probability of category k is given by p[r][k]/p:sum(1).</p>
<p>Options is a table containing:</p>
<ul>
<li>options.type Type of sampler:
<ul>
<li><code>nil</code> or <code>'iid'</code>: default, i.i.d samples, use linear search in O(N log N + max(K, N)), best when K/N is close to 1.</li>
<li>'dichotomy': dichotomic search, same variance, faster when small K large N</li>
<li>'stratified': sorted stratified samples, sample has lower variance than i.i.d. but not independent, best when K/N is close to 1</li>
</ul></li>
</ul>
<p>Returns a LongTensor vector with R-by-N elements in the resulting tensor.
or a new tensor of R rows with N columns corresponding to the categories given.</p>
<p>Note that <code>mvcat</code>, unlike <code>cat</code>, only returns tensor of integers: it does not allow for specifying a tensor of categories, to keep the handling of dimensions simple.</p>
<h3 id="toc_25">Cauchy: cauchy</h3>
<h4 id="toc_26">cauch.pdf(x, a, b)</h4>
<p>Probability density function of a Cauchy distribution with location <code>a</code> and scale <code>b</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_27">cauchy.logpdf(x, a, b)</h4>
<p>Log of probability density function of a Cauchy distribution with location <code>a</code> and scale <code>b</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_28">cauchy.cdf(x, a, b)</h4>
<p>Cumulative distribution function of a Cauchy distribution with location <code>a</code> and scale <code>b</code>, evaluated at <code>x</code>.</p>
<h3 id="toc_29">Chi square: chi2</h3>
<h4 id="toc_30">chi2.pdf(x, dof)</h4>
<p>Probability density function of a Chi square distribution with <code>dof</code> degrees of freedom, evaluated at <code>x</code>.</p>
<h4 id="toc_31">chi2.logpdf(x, dof)</h4>
<p>Log of probability density function of a Chi square distribution with <code>dof</code> degrees of freedom, evaluated at <code>x</code>.</p>
<h4 id="toc_32">chi2.cdf(x, dof)</h4>
<p>Cumulative distribution function of a Chi square distribution with <code>dof</code> degrees of freedom, evaluated at <code>x</code>.</p>
<h3 id="toc_33">Laplace: laplace</h3>
<h4 id="toc_34">laplace.pdf(x, loc, scale)</h4>
<p>Probability density function of a Laplace distribution with location <code>loc</code> and scale <code>scale</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_35">laplace.logpdf(x, loc, scale)</h4>
<p>Log of probability density function of a Laplace distribution with location <code>loc</code> and scale <code>scale</code>, evaluated at <code>x</code>.</p>
<h4 id="toc_36">laplace.cdf(x, loc, scale)</h4>
<p>Cumulative distribution function of a Laplace distribution with location <code>loc</code> and scale <code>scale</code>, evaluated at <code>x</code>.</p>
<h2 id="toc_37">Hypothesis Testing</h2>
<p>Besides the generators, there are some functions for checking whether two samples come from the same unspecified distribution using <a href="http://en.wikipedia.org/wiki/Kolmogorov%E2%80%93Smirnov_test#Two-sample_Kolmogorov.E2.80.93Smirnov_test"><code>Kolmogorov-Smirnov two-sample test</code></a>, and whether a sample fits a particular distribution, using <a href="http://en.wikipedia.org/wiki/Pearson's_chi-squared_test"><code>Pearson's chi-squared test</code></a>.</p>
<h3 id="toc_38">ksone(x1, cdf)</h3>
<p>Perform a one-sample Kolmogorov-Smirnov test, with null hypothesis "sample x comes from the distribution whose cumulative distribution function is given".</p>
<ul>
<li><code>x</code> should be a vector of sample values to test</li>
<li><code>cdf</code> should be a function that takes a number and return the cumulative distribution function at this point</li>
</ul>
<p>Returns: <code>p</code>, <code>d</code> - the p-value and the statistic the test, respectively.</p>
<h3 id="toc_39">kstwo(x1, x2)</h3>
<p>Perform a two-sample Kolmogorov-Smirnov test, with null hypothesis "sample x1 and sample x2 come from the same distribution".</p>
<ul>
<li><code>x1</code> should be a vector of sample values to test </li>
<li><code>x2</code> should be a vector of sample values to test </li>
</ul>
<p>Returns: <code>p</code>, <code>d</code> - the p-value and the statistic the test, respectively.</p>
<h3 id="toc_40">chi2Uniform(x, [low, up, nBins])</h3>
<p>Perform a chi-squared test, with null hypothesis "sample x is from a continuous uniform distribution on the interval <code>[low, up]</code>".</p>
<ul>
<li><code>x</code> should be a vector of sample values to test</li>
<li><code>low</code> is the lower end of the uniform distribution's support interval (default: 0)</li>
<li><code>up</code> is the upper end of the uniform distribution's support interval (default: 1)</li>
<li><code>nBins</code> is number of frequency buckets to use for the test (default: 100)</li>
</ul>
<p>Returns: <code>p</code>, <code>chi2</code> - the p-value and the chi-squared score of the test, respectively.</p>
<h3 id="toc_41">chi2TestCDF(x, cdf, cdfParams, [nBins])</h3>
<p>Perform a chi-squared test, with null hypothesis "sample x is from a distribution with cdf <code>cdf</code>, parameterised by <code>cdfParams</code>".</p>
<ul>
<li><code>x</code> should be a vector of sample values to test</li>
<li><code>cdf</code> should be a function which takes a number of parameters followed by a sample value and returns the cumulative density of the distribution up to that point</li>
<li><code>cdfParams</code> should be a table of parameters which will be passed to <code>cdf</code></li>
<li><code>nBins</code> is number of frequency buckets to use for the test (default: 100)</li>
</ul>
<p>Returns: <code>p</code>, <code>chi2</code> - the p-value and the chi-squared score of the test, respectively.</p>
<h3 id="toc_42">chi2Gaussian(x, mu, sigma, [nBins])</h3>
<p>Perform a chi-squared test, with null hypothesis "sample x is from a Normal distribution with mean <code>mu</code> and variance <code>sigma</code>".</p>
<ul>
<li><code>x</code> should be a vector of sample values to test</li>
<li><code>mu</code> should be a number - the mean</li>
<li><code>sigma</code> should be a positive number - the variance</li>
<li><code>nBins</code> is number of frequency buckets to use for the test (default: 100)</li>
</ul>
<p>Returns: <code>p</code>, <code>chi2</code> - the p-value and the chi-squared score of the test, respectively.</p>
<h2 id="toc_43">Unit Tests</h2>
<p>Last but not least, the unit tests are in the folder
<a href="https://github.com/jucor/torch-distributions/tree/master/distributions/tests"><code>distributions/tests</code></a>. You can run them from your local clone of the repostiory with:</p>
<div class="highlight"><pre><code class="bash language-bash" data-lang="bash">git clone https://www.github.com/jucor/torch-distributions
find torch-distributions/distributions/tests -name <span class="s2">"test*lua"</span> -exec torch <span class="o">{}</span> <span class="se">\;</span>
</code></pre></div>
<p>Those tests will soone be automatically installed with the package, once I sort out a bit of CMake resistance.</p>
</section>
</div>
<script src="javascripts/scale.fix.js"></script>
</body>
</html>