0
# Uncertainty Propagation
1

2
Framework for propagating uncertainties through calculations with support for correlated and uncorrelated errors.
3

4
## Core Imports
5

6
```python
7
from astropy.uncertainty import Distribution
8
from astropy.uncertainty import normal, uniform, poisson
9
```
10

11
## Capabilities
12

13
### Distribution Classes
14

15
Classes for representing probability distributions and performing Monte Carlo uncertainty propagation.
16

17
```python { .api }
18
class Distribution:
19
    """
20
    Base class for probability distributions.
21
    
22
    Parameters:
23
    - samples: array of samples from the distribution
24
    """
25
    def __init__(self, samples): ...
26
    
27
    @property
28
    def samples(self):
29
        """Array of samples from the distribution."""
30
    
31
    @property
32
    def n_samples(self):
33
        """Number of samples."""
34
    
35
    def pdf_mean(self):
36
        """Mean of the probability distribution."""
37
    
38
    def pdf_std(self):
39
        """Standard deviation of the distribution."""
40
    
41
    def pdf_var(self):
42
        """Variance of the distribution."""
43
    
44
    def pdf_median(self):
45
        """Median of the distribution."""
46
    
47
    def pdf_mad(self):
48
        """Median absolute deviation."""
49
    
50
    def pdf_percentiles(self, percentile):
51
        """Compute percentiles of the distribution."""
52
    
53
    def __add__(self, other): ...
54
    def __sub__(self, other): ...
55
    def __mul__(self, other): ...
56
    def __truediv__(self, other): ...
57
    def __pow__(self, power): ...
58
```
59

60
### Distribution Creation Functions
61

62
Functions for creating common probability distributions with specified parameters.
63

64
```python { .api }
65
def normal(center, std=None, n_samples=None):
66
    """
67
    Create normal (Gaussian) distribution.
68
    
69
    Parameters:
70
    - center: mean of the distribution
71
    - std: standard deviation
72
    - n_samples: number of samples to generate
73
    
74
    Returns:
75
    Distribution: normal distribution
76
    """
77

78
def uniform(lower=None, upper=None, center=None, width=None, n_samples=None):
79
    """
80
    Create uniform distribution.
81
    
82
    Parameters:
83
    - lower: lower bound (alternative to center/width)
84
    - upper: upper bound (alternative to center/width) 
85
    - center: center value (alternative to lower/upper)
86
    - width: width of distribution (alternative to lower/upper)
87
    - n_samples: number of samples to generate
88
    
89
    Returns:
90
    Distribution: uniform distribution
91
    """
92

93
def poisson(center, n_samples=None):
94
    """
95
    Create Poisson distribution.
96
    
97
    Parameters:
98
    - center: mean/rate parameter of Poisson distribution
99
    - n_samples: number of samples to generate
100
    
101
    Returns:
102
    Distribution: Poisson distribution
103
    """
104
```
105

106
## Usage Examples
107

108
### Basic Uncertainty Propagation
109

110
```python
111
import numpy as np
112
from astropy.uncertainty import normal
113

114
# Create distributions for input variables
115
a = normal(center=5.0, std=0.2, n_samples=10000)
116
b = normal(center=3.0, std=0.1, n_samples=10000)
117

118
# Propagate uncertainties through calculations
119
result = a + b
120
product = a * b
121
ratio = a / b
122

123
print(f"Sum: {result.pdf_mean():.3f} ± {result.pdf_std():.3f}")
124
print(f"Product: {product.pdf_mean():.3f} ± {product.pdf_std():.3f}")  
125
print(f"Ratio: {ratio.pdf_mean():.3f} ± {ratio.pdf_std():.3f}")
126
```
127

128
### Complex Function Propagation
129

130
```python
131
from astropy.uncertainty import uniform
132
import astropy.units as u
133

134
# Physical measurement with uniform uncertainty
135
length = uniform(center=10.0, width=0.5, n_samples=10000) * u.m
136
width = normal(center=2.0, std=0.1, n_samples=10000) * u.m
137

138
# Calculate area with uncertainty
139
area = length * width
140

141
print(f"Area: {area.pdf_mean():.2f} ± {area.pdf_std():.2f}")
142

143
# Non-linear function
144
volume = length * width * normal(1.5, 0.05, 10000) * u.m
145
print(f"Volume: {volume.pdf_mean():.2f} ± {volume.pdf_std():.2f}")
146
```
147

148
### Percentile Analysis
149

150
```python
151
# Get confidence intervals
152
lower_5 = result.pdf_percentiles(5)
153
upper_95 = result.pdf_percentiles(95) 
154

155
print(f"90% confidence interval: [{lower_5:.3f}, {upper_95:.3f}]")
156

157
# Multiple percentiles
158
percentiles = result.pdf_percentiles([16, 50, 84])
159
print(f"16th, 50th, 84th percentiles: {percentiles}")
160
```
161

162
## Types
163

164
```python { .api }
165
# Distribution types
166
Distribution = astropy.uncertainty.Distribution
167
```