0
# Parametric AR Methods
1

2
Auto-regressive (AR) parameter estimation and power spectral density computation using various algorithms. These methods model the data as the output of an all-pole filter driven by white noise, providing high-resolution spectral estimates particularly effective for short data records.
3

4
## Capabilities
5

6
### Yule-Walker Method
7

8
Estimates AR parameters using the Yule-Walker equations based on the autocorrelation function. Provides a stable solution but may have lower resolution compared to other methods.
9

10
```python { .api }
11
def aryule(X, order, norm='biased', allow_singularity=True):
12
    """
13
    AR parameter estimation using Yule-Walker equations.
14
    
15
    Parameters:
16
    - X: array-like, input time series data
17
    - order: int, AR model order
18
    - norm: str, normalization type ('biased', 'unbiased')
19
    - allow_singularity: bool, allow singular autocorrelation matrix
20
    
21
    Returns:
22
    tuple: (AR coefficients array, noise variance float, reflection coefficients array)
23
    """
24

25
class pyule(data, order, NFFT=None, sampling=1., scale_by_freq=False):
26
    """
27
    PSD estimation using Yule-Walker method.
28
    
29
    Parameters:
30
    - data: array-like, input time series
31
    - order: int, AR model order
32
    - NFFT: int, FFT length for PSD computation
33
    - sampling: float, sampling frequency
34
    - scale_by_freq: bool, scale PSD by frequency
35
    """
36
```
37

38
### Burg Method
39

40
Maximum entropy method that estimates AR parameters by minimizing forward and backward prediction errors. Provides excellent frequency resolution and stability.
41

42
```python { .api }
43
def arburg(X, order, criteria=None):
44
    """
45
    AR parameter estimation using Burg algorithm.
46
    
47
    Parameters:
48
    - X: array-like, input time series data
49
    - order: int, AR model order (or maximum order if criteria used)
50
    - criteria: str, automatic order selection criterion
51
    
52
    Returns:
53
    tuple: (AR coefficients array, prediction error variance float, reflection coefficients array)
54
    """
55

56
class pburg(data, order, criteria=None, NFFT=None, sampling=1., scale_by_freq=False):
57
    """
58
    PSD estimation using Burg method.
59
    
60
    Parameters:
61
    - data: array-like, input time series
62
    - order: int, AR model order
63
    - criteria: str, order selection criteria ('AIC', 'MDL', etc.)
64
    - NFFT: int, FFT length for PSD computation
65
    - sampling: float, sampling frequency
66
    - scale_by_freq: bool, scale PSD by frequency
67
    """
68
```
69

70
### Covariance Method
71

72
Estimates AR parameters using the covariance method, which minimizes the forward prediction error. Provides unbiased estimates but may be less stable than other methods.
73

74
```python { .api }
75
def arcovar(x, order):
76
    """
77
    AR parameter estimation using covariance method.
78
    
79
    Parameters:
80
    - x: array-like, input time series data
81
    - order: int, AR model order
82
    
83
    Returns:
84
    tuple: (AR coefficients array, noise variance float, reflection coefficients array)
85
    """
86

87
def arcovar_marple(x, order):
88
    """
89
    Marple's implementation of covariance method.
90
    
91
    Parameters:
92
    - x: array-like, input time series data
93
    - order: int, AR model order (works for order <= 4)
94
    
95
    Returns:
96
    tuple: (AR coefficients array, noise variance float, reflection coefficients array)
97
    """
98

99
class pcovar(data, order, NFFT=None, sampling=1., scale_by_freq=False):
100
    """
101
    PSD estimation using covariance method.
102
    
103
    Parameters:
104
    - data: array-like, input time series
105
    - order: int, AR model order
106
    - NFFT: int, FFT length for PSD computation
107
    - sampling: float, sampling frequency
108
    - scale_by_freq: bool, scale PSD by frequency
109
    """
110
```
111

112
### Modified Covariance Method
113

114
Combines forward and backward prediction errors to provide improved parameter estimates. Generally more stable than the standard covariance method.
115

116
```python { .api }
117
def modcovar(x, order):
118
    """
119
    AR parameter estimation using modified covariance method.
120
    
121
    Parameters:
122
    - x: array-like, input time series data
123
    - order: int, AR model order
124
    
125
    Returns:
126
    tuple: (AR coefficients array, noise variance float, reflection coefficients array)
127
    """
128

129
def modcovar_marple(X, IP):
130
    """
131
    Marple's implementation of modified covariance method.
132
    
133
    Parameters:
134
    - X: array-like, input time series data
135
    - IP: int, AR model order
136
    
137
    Returns:
138
    tuple: (AR coefficients array, noise variance float, reflection coefficients array)
139
    """
140

141
class pmodcovar(data, order, NFFT=None, sampling=1., scale_by_freq=False):
142
    """
143
    PSD estimation using modified covariance method.
144
    
145
    Parameters:
146
    - data: array-like, input time series
147
    - order: int, AR model order
148
    - NFFT: int, FFT length for PSD computation
149
    - sampling: float, sampling frequency
150
    - scale_by_freq: bool, scale PSD by frequency
151
    """
152
```
153

154
## Usage Examples
155

156
### Basic AR Parameter Estimation
157

158
```python
159
import spectrum
160
import numpy as np
161

162
# Generate AR(2) test signal
163
N = 256
164
noise = 0.1 * np.random.randn(N)
165
# AR coefficients for two-pole system
166
ar_true = [1.0, -1.6180, 0.8607]  
167
signal = spectrum.lfilter([1], ar_true, noise)
168

169
# Estimate AR parameters using different methods
170
ar_yule, var_yule, rc_yule = spectrum.aryule(signal, order=2)
171
ar_burg, var_burg, rc_burg = spectrum.arburg(signal, order=2)
172
ar_cov, var_cov, rc_cov = spectrum.arcovar(signal, order=2)
173

174
print(f"True AR coefficients: {ar_true[1:]}")
175
print(f"Yule-Walker: {ar_yule}")
176
print(f"Burg: {ar_burg}")
177
print(f"Covariance: {ar_cov}")
178
```
179

180
### PSD Estimation with Automatic Order Selection
181

182
```python
183
import spectrum
184
import numpy as np
185

186
# Generate noisy sinusoidal signal
187
t = np.arange(256)
188
signal = np.sin(0.2*t) + np.sin(0.3*t) + 0.2*np.random.randn(256)
189

190
# PSD estimation with automatic order selection using AIC
191
p = spectrum.pburg(signal, order=20, criteria='AIC')
192
p.plot()
193

194
# Compare different methods
195
p_yule = spectrum.pyule(signal, order=15)
196
p_cov = spectrum.pcovar(signal, order=15)
197
p_mod = spectrum.pmodcovar(signal, order=15)
198

199
# Plot all methods for comparison
200
import matplotlib.pyplot as plt
201
f = np.linspace(0, 0.5, len(p.psd))
202
plt.figure(figsize=(10, 6))
203
plt.semilogy(f, p.psd, label='Burg')
204
plt.semilogy(f, p_yule.psd, label='Yule-Walker')
205
plt.semilogy(f, p_cov.psd, label='Covariance')
206
plt.semilogy(f, p_mod.psd, label='Modified Covariance')
207
plt.xlabel('Normalized Frequency')
208
plt.ylabel('PSD')
209
plt.legend()
210
plt.grid(True)
211
plt.show()
212
```