0
# Utilities
1

2
Core utilities for spatial operations, matrix computations, GMM optimization, and data generation for simulation studies.
3

4
## Capabilities
5

6
### Spatial Operations
7

8
```python { .api }
9
def get_lags(w, x, w_lags):
10
    """
11
    Generate spatial lags of variables.
12
    
13
    Parameters:
14
    - w: Spatial weights object
15
    - x: Variable to lag
16
    - w_lags: Number of lags to generate
17
    
18
    Returns:
19
    - array: Spatially lagged variables
20
    """
21

22
def get_spFilter(w, lamb, sf):
23
    """
24
    Apply spatial filtering transformation: (I - λW)x.
25
    
26
    Parameters:
27
    - w: Spatial weights object
28
    - lamb: Spatial parameter (scalar)
29
    - sf: Variable to filter
30
    
31
    Returns:
32
    - array: Spatially filtered variable
33
    """
34

35
def get_lags_split(w, x, max_lags, split_at):
36
    """Generate spatial lags with split functionality."""
37
```
38

39
### GMM Utilities
40

41
```python { .api }
42
def optim_moments(moments_in, vcX=np.array([0]), all_par=False, start=None, hard_bound=False):
43
    """
44
    Optimize GMM moments estimation.
45
    
46
    Parameters:
47
    - moments_in: Moment conditions function
48
    - vcX: Variance-covariance matrix
49
    - all_par: Boolean, return all parameters if True
50
    - start: Starting values for optimization
51
    - hard_bound: Boolean, enforce parameter bounds
52
    
53
    Returns:
54
    - array: Optimized parameters
55
    """
56

57
def get_A1_het(S):
58
    """Build A1 matrix for heteroskedastic GMM estimation."""
59

60
def get_A1_hom(s, scalarKP=False):
61
    """Build A1 matrix for homoskedastic GMM estimation."""
62

63
def get_A2_hom(s):
64
    """Build A2 matrix for homoskedastic GMM estimation."""
65

66
def inverse_prod(w, data, scalar, post_multiply=False, inv_method='power_exp', threshold=0.99999999, max_iter=100):
67
    """Compute inverse matrix product for spatial filtering."""
68

69
def power_expansion(w, data, scalar, post_multiply=False, threshold=0.99999999, max_iter=100):
70
    """Power expansion approximation for matrix inverse."""
71
```
72

73
### Regression Helper Classes
74

75
```python { .api }
76
class RegressionPropsY:
77
    """
78
    Helper class providing regression properties for dependent variable.
79
    
80
    Properties:
81
    - mean_y: float, mean of dependent variable
82
    - std_y: float, standard deviation of dependent variable
83
    - sig2n: float, sigma-squared (n denominator)
84
    - sig2n_k: float, sigma-squared (n-k denominator)
85
    """
86

87
class RegressionPropsVM:
88
    """
89
    Helper class providing variance-covariance matrix properties.
90
    
91
    Properties:
92
    - vm: array, variance-covariance matrix
93
    - std_err: array, standard errors
94
    - z_stat: array, z-statistics
95
    - p_values: array, p-values
96
    """
97
```
98

99

100
## Usage Examples
101

102
### Spatial Operations
103

104
```python
105
import numpy as np
106
import spreg
107
from libpysal import weights
108

109
# Create spatial weights
110
n = 100
111
coords = np.random.randn(n, 2)
112
w = weights.KNN.from_array(coords, k=5)
113

114
# Variable to lag
115
x = np.random.randn(n, 1)
116

117
# Multiple lags (note: lag_spatial is from libpysal, not spreg)
118
from libpysal.weights.spatial_lag import lag_spatial
119
wx = lag_spatial(w, x)
120
print(f"Original variable shape: {x.shape}")
121
print(f"Spatial lag shape: {wx.shape}")
122

123
# Generate lags using spreg utilities
124
x_multi = np.random.randn(n, 3)
125
lags = spreg.get_lags(w, x_multi, w_lags=2)
126
print(f"Multiple spatial lags shape: {lags.shape}")
127
```
128

129
### GMM Optimization
130

131
```python
132
import numpy as np
133
import spreg
134
from libpysal import weights
135

136
# Example: Set up endogenous variables for spatial model
137
n = 100
138
y = np.random.randn(n, 1)
139
x = np.random.randn(n, 2)
140
yend = np.random.randn(n, 1)  # endogenous variable
141
q = np.random.randn(n, 1)     # instrument
142
w = weights.lat2W(10, 10)
143

144
# Set up for spatial estimation
145
y_setup, x_setup, yend_setup, q_setup = spreg.set_endog(
146
    y, x, w, yend, q, w_lags=1, lag_q=True
147
)
148

149
print("Data setup for spatial GMM estimation completed")
150
print(f"Processed shapes: y={y_setup.shape}, x={x_setup.shape}")
151
```