0
# Probability Distributions
1

2
PyMC3's comprehensive library of 60+ probability distributions provides the building blocks for Bayesian models. All distributions support automatic broadcasting, shape inference, parameter transformations, and efficient computation through Theano integration.
3

4
## Capabilities
5

6
### Continuous Distributions
7

8
Univariate continuous distributions for modeling real-valued random variables with support on continuous intervals.
9

10
```python { .api }
11
class Normal:
12
    """
13
    Univariate normal (Gaussian) distribution.
14
    
15
    Parameters:
16
    - mu: float or array, mean
17
    - sigma: float or array, standard deviation (> 0)  
18
    - sd: float or array, alias for sigma (standard deviation, > 0)
19
    - tau: float or array, precision (1/sigma^2, > 0)
20
    """
21

22
class Beta:
23
    """
24
    Beta distribution for variables bounded between 0 and 1.
25
    
26
    Parameters:
27
    - alpha: float or array, shape parameter (> 0)
28
    - beta: float or array, shape parameter (> 0)
29
    """
30

31
class Gamma:
32
    """
33
    Gamma distribution for positive continuous variables.
34
    
35
    Parameters:
36
    - alpha: float or array, shape parameter (> 0)
37
    - beta: float or array, rate parameter (> 0)
38
    - mu: float or array, mean (alternative parameterization)
39
    - sigma: float or array, standard deviation (alternative parameterization)
40
    """
41

42
class Exponential:
43
    """
44
    Exponential distribution for positive continuous variables.
45
    
46
    Parameters:
47
    - lam: float or array, rate parameter (> 0)
48
    """
49

50
class StudentT:
51
    """
52
    Student's t-distribution for robust modeling.
53
    
54
    Parameters:
55
    - nu: float or array, degrees of freedom (> 0)
56
    - mu: float or array, location parameter
57
    - sigma: float or array, scale parameter (> 0)
58
    """
59

60
class Uniform:
61
    """
62
    Uniform distribution over continuous interval.
63
    
64
    Parameters:
65
    - lower: float or array, lower bound
66
    - upper: float or array, upper bound (> lower)
67
    """
68

69
class Lognormal:
70
    """
71
    Log-normal distribution for positive variables.
72
    
73
    Parameters:
74
    - mu: float or array, mean of underlying normal
75
    - sigma: float or array, standard deviation of underlying normal (> 0)
76
    """
77

78
class Cauchy:
79
    """
80
    Cauchy distribution with heavy tails.
81
    
82
    Parameters:
83
    - alpha: float or array, location parameter
84
    - beta: float or array, scale parameter (> 0)
85
    """
86

87
class Laplace:
88
    """
89
    Laplace (double exponential) distribution.
90
    
91
    Parameters:
92
    - mu: float or array, location parameter
93
    - b: float or array, scale parameter (> 0)
94
    """
95

96
class AsymmetricLaplace:
97
    """
98
    Asymmetric Laplace distribution.
99
    
100
    Parameters:
101
    - b: float or array, scale parameter (> 0)
102
    - kappa: float or array, asymmetry parameter (> 0)
103
    - mu: float or array, location parameter
104
    """
105

106
class Logistic:
107
    """
108
    Logistic distribution.
109
    
110
    Parameters:
111
    - mu: float or array, location parameter
112
    - s: float or array, scale parameter (> 0)
113
    """
114

115
class LogitNormal:
116
    """
117
    Logit-normal distribution for variables in (0,1).
118
    
119
    Parameters:
120
    - mu: float or array, mean of underlying normal
121
    - sigma: float or array, standard deviation of underlying normal (> 0)
122
    """
123

124
class Weibull:
125
    """
126
    Weibull distribution for survival analysis.
127
    
128
    Parameters:
129
    - alpha: float or array, shape parameter (> 0)
130
    - beta: float or array, scale parameter (> 0)
131
    """
132

133
class Pareto:
134
    """
135
    Pareto distribution for power-law phenomena.
136
    
137
    Parameters:
138
    - alpha: float or array, shape parameter (> 0)
139
    - m: float or array, scale parameter (> 0)
140
    """
141

142
class ChiSquared:
143
    """
144
    Chi-squared distribution.
145
    
146
    Parameters:
147
    - nu: float or array, degrees of freedom (> 0)
148
    """
149

150
class InverseGamma:
151
    """
152
    Inverse gamma distribution.
153
    
154
    Parameters:
155
    - alpha: float or array, shape parameter (> 0)
156
    - beta: float or array, scale parameter (> 0)
157
    """
158

159
class Gumbel:
160
    """
161
    Gumbel distribution for extreme value modeling.
162
    
163
    Parameters:
164
    - mu: float or array, location parameter
165
    - beta: float or array, scale parameter (> 0)
166
    """
167

168
class SkewNormal:
169
    """
170
    Skew-normal distribution.
171
    
172
    Parameters:
173
    - mu: float or array, location parameter
174
    - sigma: float or array, scale parameter (> 0)
175
    - alpha: float or array, shape parameter
176
    """
177

178
class Triangular:
179
    """
180
    Triangular distribution.
181
    
182
    Parameters:
183
    - lower: float or array, lower bound
184
    - upper: float or array, upper bound
185
    - c: float or array, mode
186
    """
187

188
class ExGaussian:
189
    """
190
    Exponentially modified Gaussian distribution.
191
    
192
    Parameters:
193
    - mu: float or array, mean of Gaussian component
194
    - sigma: float or array, standard deviation of Gaussian component (> 0)
195
    - nu: float or array, rate parameter of exponential component (> 0)
196
    """
197

198
class VonMises:
199
    """
200
    Von Mises distribution for circular data.
201
    
202
    Parameters:
203
    - mu: float or array, mean direction
204
    - kappa: float or array, concentration parameter (≥ 0)
205
    """
206

207
class Wald:
208
    """
209
    Wald (inverse Gaussian) distribution.
210
    
211
    Parameters:
212
    - mu: float or array, mean (> 0)
213
    - lam: float or array, shape parameter (> 0)
214
    """
215

216
class Kumaraswamy:
217
    """
218
    Kumaraswamy distribution for variables in (0,1).
219
    
220
    Parameters:
221
    - a: float or array, shape parameter (> 0)
222
    - b: float or array, shape parameter (> 0)
223
    """
224

225
class Rice:
226
    """
227
    Rice distribution.
228
    
229
    Parameters:
230
    - nu: float or array, non-centrality parameter (≥ 0)
231
    - sigma: float or array, scale parameter (> 0)
232
    """
233

234
class Moyal:
235
    """
236
    Moyal distribution.
237
    
238
    Parameters:
239
    - mu: float or array, location parameter
240
    - sigma: float or array, scale parameter (> 0)
241
    """
242

243
class TruncatedNormal:
244
    """
245
    Truncated normal distribution.
246
    
247
    Parameters:
248
    - mu: float or array, mean of untruncated normal
249
    - sigma: float or array, standard deviation of untruncated normal (> 0)
250
    - lower: float or array, lower bound
251
    - upper: float or array, upper bound
252
    """
253
```
254

255
### Half Distributions
256

257
Half distributions for positive-constrained variables, useful for variance parameters and other positive quantities.
258

259
```python { .api }
260
class HalfNormal:
261
    """
262
    Half-normal distribution (normal truncated at zero).
263
    
264
    Parameters:
265
    - sigma: float or array, scale parameter (> 0)
266
    """
267

268
class HalfCauchy:
269
    """
270
    Half-Cauchy distribution (Cauchy truncated at zero).
271
    
272
    Parameters:
273
    - beta: float or array, scale parameter (> 0)
274
    """
275

276
class HalfStudentT:
277
    """
278
    Half-Student's t distribution.
279
    
280
    Parameters:
281
    - nu: float or array, degrees of freedom (> 0)
282
    - sigma: float or array, scale parameter (> 0)
283
    """
284

285
class HalfFlat:
286
    """
287
    Half-flat (improper) prior for positive variables.
288
    """
289
```
290

291
### Flat Distributions
292

293
Improper uniform priors for uninformative modeling.
294

295
```python { .api }
296
class Flat:
297
    """
298
    Flat (improper uniform) prior over entire real line.
299
    """
300
```
301

302
### Discrete Distributions
303

304
Discrete distributions for count data, categorical variables, and other integer-valued outcomes.
305

306
```python { .api }
307
class Binomial:
308
    """
309
    Binomial distribution for number of successes.
310
    
311
    Parameters:
312
    - n: int or array, number of trials (≥ 0)
313
    - p: float or array, probability of success (0 ≤ p ≤ 1)
314
    """
315

316
class Poisson:
317
    """
318
    Poisson distribution for count data.
319
    
320
    Parameters:
321
    - mu: float or array, rate parameter (> 0)
322
    """
323

324
class NegativeBinomial:
325
    """
326
    Negative binomial distribution for overdispersed count data.
327
    
328
    Parameters:
329
    - mu: float or array, mean (> 0)
330
    - alpha: float or array, dispersion parameter (> 0)
331
    """
332

333
class Bernoulli:
334
    """
335
    Bernoulli distribution for binary outcomes.
336
    
337
    Parameters:
338
    - p: float or array, probability of success (0 ≤ p ≤ 1)
339
    """
340

341
class Categorical:
342
    """
343
    Categorical distribution for discrete choices.
344
    
345
    Parameters:
346
    - p: array, probabilities for each category (sums to 1)
347
    """
348

349
class Geometric:
350
    """
351
    Geometric distribution for number of trials until first success.
352
    
353
    Parameters:
354
    - p: float or array, probability of success (0 < p ≤ 1)
355
    """
356

357
class HyperGeometric:
358
    """
359
    Hypergeometric distribution for sampling without replacement.
360
    
361
    Parameters:
362
    - N: int, population size
363
    - K: int, number of success states in population
364
    - n: int, number of draws
365
    """
366

367
class DiscreteUniform:
368
    """
369
    Discrete uniform distribution.
370
    
371
    Parameters:
372
    - lower: int or array, lower bound
373
    - upper: int or array, upper bound
374
    """
375

376
class DiscreteWeibull:
377
    """
378
    Discrete Weibull distribution.
379
    
380
    Parameters:
381
    - q: float or array, shape parameter (0 < q < 1)
382
    - beta: float or array, shape parameter (> 0)
383
    """
384

385
class BetaBinomial:
386
    """
387
    Beta-binomial distribution for overdispersed binomial data.
388
    
389
    Parameters:
390
    - alpha: float or array, shape parameter (> 0)
391
    - beta: float or array, shape parameter (> 0)
392
    - n: int or array, number of trials
393
    """
394

395
class Constant:
396
    """
397
    Constant distribution (degenerate at single value).
398
    
399
    Parameters:
400
    - c: float or array, constant value
401
    """
402
```
403

404
### Zero-Inflated Distributions
405

406
Mixture distributions for count data with excess zeros.
407

408
```python { .api }
409
class ZeroInflatedPoisson:
410
    """
411
    Zero-inflated Poisson distribution.
412
    
413
    Parameters:
414
    - theta: float or array, probability of zero inflation (0 ≤ theta ≤ 1)
415
    - mu: float or array, Poisson rate parameter (> 0)
416
    """
417

418
class ZeroInflatedBinomial:
419
    """
420
    Zero-inflated binomial distribution.
421
    
422
    Parameters:
423
    - theta: float or array, probability of zero inflation (0 ≤ theta ≤ 1)
424
    - n: int or array, number of trials
425
    - p: float or array, probability of success (0 ≤ p ≤ 1)
426
    """
427

428
class ZeroInflatedNegativeBinomial:
429
    """
430
    Zero-inflated negative binomial distribution.
431
    
432
    Parameters:
433
    - theta: float or array, probability of zero inflation (0 ≤ theta ≤ 1)
434
    - mu: float or array, mean parameter (> 0)
435
    - alpha: float or array, dispersion parameter (> 0)
436
    """
437
```
438

439
### Ordered Regression Distributions
440

441
Specialized distributions for ordinal regression models.
442

443
```python { .api }
444
class OrderedLogistic:
445
    """
446
    Ordered logistic regression distribution.
447
    
448
    Parameters:
449
    - eta: float or array, linear predictor
450
    - cutpoints: array, ordered cutpoint parameters
451
    """
452

453
class OrderedProbit:
454
    """
455
    Ordered probit regression distribution.
456
    
457
    Parameters:
458
    - eta: float or array, linear predictor  
459
    - cutpoints: array, ordered cutpoint parameters
460
    """
461
```
462

463
### Multivariate Distributions
464

465
Distributions for vector-valued random variables with dependence structure.
466

467
```python { .api }
468
class MvNormal:
469
    """
470
    Multivariate normal distribution.
471
    
472
    Parameters:
473
    - mu: array, mean vector
474
    - cov: array, covariance matrix (positive definite)
475
    - tau: array, precision matrix (inverse covariance, positive definite)
476
    - chol: array, Cholesky decomposition of covariance
477
    """
478

479
class MvStudentT:
480
    """
481
    Multivariate Student's t distribution.
482
    
483
    Parameters:
484
    - nu: float, degrees of freedom (> 0)
485
    - mu: array, location vector
486
    - cov: array, scale matrix (positive definite)
487
    """
488

489
class Dirichlet:
490
    """
491
    Dirichlet distribution for probability vectors.
492
    
493
    Parameters:
494
    - a: array, concentration parameters (> 0)
495
    """
496

497
class Multinomial:
498
    """
499
    Multinomial distribution for count vectors.
500
    
501
    Parameters:
502
    - n: int or array, number of trials
503
    - p: array, probabilities for each category (sums to 1)
504
    """
505

506
class DirichletMultinomial:
507
    """
508
    Dirichlet-multinomial distribution for overdispersed multinomial data.
509
    
510
    Parameters:
511
    - n: int or array, number of trials
512
    - a: array, concentration parameters (> 0)
513
    """
514

515
class Wishart:
516
    """
517
    Wishart distribution for positive definite matrices.
518
    
519
    Parameters:
520
    - nu: float, degrees of freedom (> dim - 1)
521
    - V: array, scale matrix (positive definite)
522
    """
523

524
class WishartBartlett:
525
    """
526
    Wishart distribution using Bartlett decomposition.
527
    
528
    Parameters:
529
    - nu: float, degrees of freedom (> dim - 1)
530
    - S: array, scale matrix (positive definite)
531
    """
532

533
class LKJCorr:
534
    """
535
    LKJ correlation matrix distribution.
536
    
537
    Parameters:
538
    - eta: float, shape parameter (> 0)
539
    - n: int, dimension of correlation matrix
540
    """
541

542
class LKJCholeskyCov:
543
    """
544
    LKJ Cholesky covariance matrix distribution.
545
    
546
    Parameters:
547
    - eta: float, LKJ shape parameter (> 0)
548
    - n: int, dimension of covariance matrix
549
    - sd_dist: distribution for standard deviations
550
    """
551

552
class MatrixNormal:
553
    """
554
    Matrix normal distribution.
555
    
556
    Parameters:
557
    - mu: array, mean matrix
558
    - rowcov: array, row covariance matrix
559
    - colcov: array, column covariance matrix
560
    """
561

562
class KroneckerNormal:
563
    """
564
    Kronecker-structured normal distribution.
565
    
566
    Parameters:
567
    - mu: array, mean vector
568
    - covs: list of arrays, Kronecker factor covariance matrices
569
    """
570
```
571

572
### Time Series Distributions
573

574
Distributions for temporal dependence and sequential data.
575

576
```python { .api }
577
class GaussianRandomWalk:
578
    """
579
    Gaussian random walk process.
580
    
581
    Parameters:
582
    - mu: float or array, innovation mean
583
    - sigma: float or array, innovation standard deviation (> 0)
584
    - init: distribution for initial value
585
    """
586

587
class AR1:
588
    """
589
    First-order autoregressive process AR(1).
590
    
591
    Parameters:
592
    - k: float or array, constant term
593
    - tau_e: float or array, innovation precision (> 0)
594
    - phi: float or array, autoregressive coefficient (|phi| < 1 for stationarity)
595
    """
596

597
class AR:
598
    """
599
    Autoregressive process AR(p).
600
    
601
    Parameters:
602
    - rho: array, autoregressive coefficients
603
    - sigma: float or array, innovation standard deviation (> 0)
604
    - constant: bool, whether to include constant term
605
    - init: distribution for initial values
606
    """
607

608
class GARCH11:
609
    """
610
    GARCH(1,1) process for volatility modeling.
611
    
612
    Parameters:
613
    - omega: float, constant term (> 0)
614
    - alpha_1: float, ARCH coefficient (≥ 0)
615
    - beta_1: float, GARCH coefficient (≥ 0)
616
    - initial_vol: float, initial volatility (> 0)
617
    """
618

619
class MvGaussianRandomWalk:
620
    """
621
    Multivariate Gaussian random walk.
622
    
623
    Parameters:
624
    - mu: array, innovation mean vector
625
    - cov: array, innovation covariance matrix
626
    - init: distribution for initial values
627
    """
628

629
class MvStudentTRandomWalk:
630
    """
631
    Multivariate Student's t random walk.
632
    
633
    Parameters:
634
    - nu: float, degrees of freedom (> 0)
635
    - mu: array, innovation location vector
636
    - cov: array, innovation scale matrix
637
    - init: distribution for initial values
638
    """
639
```
640

641
### Mixture Distributions
642

643
Finite mixture models for modeling heterogeneous populations.
644

645
```python { .api }
646
class Mixture:
647
    """
648
    General finite mixture distribution.
649
    
650
    Parameters:
651
    - w: array, mixture weights (sums to 1)
652
    - comp_dists: list of distributions, mixture components
653
    """
654

655
class NormalMixture:
656
    """
657
    Mixture of normal distributions.
658
    
659
    Parameters:
660
    - w: array, mixture weights (sums to 1)  
661
    - mu: array, component means
662
    - sigma: array, component standard deviations (> 0)
663
    """
664

665
class MixtureSameFamily:
666
    """
667
    Mixture of distributions from same parametric family.
668
    
669
    Parameters:
670
    - w: array, mixture weights (sums to 1)
671
    - comp_dists: distribution, component distribution template
672
    """
673
```
674

675
### Special Distributions
676

677
Advanced and specialized distributions for specific modeling needs.
678

679
```python { .api }
680
class DensityDist:
681
    """
682
    Custom distribution defined by log-density function.
683
    
684
    Parameters:
685
    - logp: function, log-density function
686
    - shape: tuple, shape of distribution
687
    - dtype: data type
688
    """
689

690
class Bound:
691
    """
692
    Wrapper to add bounds to any distribution.
693
    
694
    Parameters:
695
    - dist: distribution to bound
696
    - lower: float or array, lower bound
697
    - upper: float or array, upper bound
698
    """
699

700
class Interpolated:
701
    """
702
    Interpolated univariate distribution from data.
703
    
704
    Parameters:
705
    - x_points: array, interpolation points
706
    - pdf_points: array, probability density values
707
    """
708

709
class Simulator:
710
    """
711
    Distribution for simulation-based inference.
712
    
713
    Parameters:
714
    - function: callable, simulator function
715
    - **params: parameters to pass to simulator
716
    """
717

718
class BART:
719
    """
720
    Bayesian Additive Regression Trees distribution.
721
    
722
    Parameters:
723
    - X: array, predictor matrix
724
    - Y: array, response vector  
725
    - m: int, number of trees
726
    - alpha: float, tree structure prior parameter
727
    - beta: float, tree structure prior parameter
728
    """
729
```
730

731
### Distribution Base Classes and Utilities
732

733
Foundation classes and helper functions for distribution implementation.
734

735
```python { .api }
736
class Distribution:
737
    """Base class for all PyMC3 distributions."""
738

739
class Continuous:
740
    """Base class for continuous distributions."""
741

742
class Discrete:
743
    """Base class for discrete distributions."""
744

745
class NoDistribution:
746
    """Placeholder for missing distributions."""
747

748
def draw_values(*params, point=None, size=None):
749
    """
750
    Draw values from distributions and constants.
751
    
752
    Parameters:
753
    - params: distributions or constants to draw from
754
    - point: dict, point in parameter space
755
    - size: int or tuple, shape of samples to draw
756
    
757
    Returns:
758
    - tuple: drawn values
759
    """
760

761
def generate_samples(generator, *args, **kwargs):
762
    """
763
    Generate samples from a distribution using custom generator.
764
    
765
    Parameters:
766
    - generator: function, sample generator
767
    - args, kwargs: arguments to pass to generator
768
    
769
    Returns:
770
    - array: generated samples
771
    """
772

773
def fast_sample_posterior_predictive(trace, samples=None, model=None, **kwargs):
774
    """
775
    Fast posterior predictive sampling for specific distribution types.
776
    
777
    Parameters:
778
    - trace: MultiTrace, posterior samples
779
    - samples: int, number of posterior predictive samples
780
    - model: Model, model context
781
    
782
    Returns:
783
    - dict: posterior predictive samples
784
    """
785
```
786

787
## Usage Examples
788

789
### Basic Distribution Usage
790

791
```python
792
import pymc3 as pm
793
import numpy as np
794

795
# Sample from distributions
796
samples_normal = pm.Normal.dist(mu=0, sigma=1).random(size=1000)
797
samples_beta = pm.Beta.dist(alpha=2, beta=5).random(size=1000)
798

799
# Evaluate log-probability
800
x = np.array([0.0, 1.0, 2.0])
801
logp = pm.Normal.dist(mu=0, sigma=1).logp(x)
802
```
803

804
### Model with Multiple Distribution Types
805

806
```python
807
with pm.Model() as model:
808
    # Continuous priors
809
    alpha = pm.Normal('alpha', mu=0, sigma=10)
810
    beta = pm.Beta('beta', alpha=1, beta=1)
811
    sigma = pm.HalfNormal('sigma', sigma=5)
812
    
813
    # Discrete parameter
814
    k = pm.Poisson('k', mu=3)
815
    
816
    # Multivariate parameter
817
    theta = pm.Dirichlet('theta', a=np.ones(4))
818
    
819
    # Time series component
820
    walks = pm.GaussianRandomWalk('walks', mu=0, sigma=0.1, shape=100)
821
    
822
    # Mixture distribution
823
    mixture = pm.Mixture('mixture', 
824
                        w=theta, 
825
                        comp_dists=pm.Normal.dist(mu=[-2, 0, 2], sigma=1))
826
```
827

828
### Custom Distributions
829

830
```python
831
import theano.tensor as tt
832

833
# Custom distribution using DensityDist
834
def logp_custom(value, mu, sigma):
835
    return -0.5 * tt.sum(((value - mu) / sigma) ** 2)
836

837
with pm.Model() as model:
838
    mu = pm.Normal('mu', 0, 1)
839
    sigma = pm.HalfNormal('sigma', 1)
840
    
841
    custom = pm.DensityDist('custom', 
842
                           logp_custom,
843
                           observed=data,
844
                           mu=mu, 
845
                           sigma=sigma)
846
```
847

848
### Zero-Inflated Models
849

850
```python
851
with pm.Model() as zip_model:
852
    # Zero-inflation probability
853
    theta = pm.Beta('theta', alpha=1, beta=1)
854
    
855
    # Poisson rate parameter
856
    mu = pm.Exponential('mu', lam=1)
857
    
858
    # Zero-inflated Poisson likelihood
859
    y_obs = pm.ZeroInflatedPoisson('y_obs', 
860
                                   theta=theta, 
861
                                   mu=mu, 
862
                                   observed=count_data)
863
```