0
# ML Friends Regions
1

2
Machine learning-based region definitions and parameter transformations for constraining nested sampling. These components provide efficient methods for defining likelihood regions and applying transformations to improve sampling efficiency in high-dimensional parameter spaces.
3

4
## Capabilities
5

6
### Core Region Classes
7

8
Base region implementations for constraining parameter space exploration.
9

10
```python { .api }
11
class MLFriends:
12
    """
13
    Machine learning friends region using nearest neighbor analysis.
14
    
15
    Automatically determines constrained regions based on the distribution
16
    of live points, enabling efficient sampling in complex parameter spaces.
17
    """
18

19
class RobustEllipsoidRegion(MLFriends):
20
    """
21
    Robust ellipsoidal region with outlier handling.
22
    
23
    Combines ellipsoidal approximation with robust statistics to handle
24
    outliers and irregular likelihood contours effectively.
25
    """
26

27
class SimpleRegion(RobustEllipsoidRegion):
28
    """
29
    Simplified region implementation for basic constraints.
30
    
31
    Provides essential region functionality with minimal computational
32
    overhead for standard nested sampling applications.
33
    """
34

35
class WrappingEllipsoid:
36
    """
37
    Ellipsoid with support for wrapped/periodic parameters.
38
    
39
    Handles circular parameters (angles, phases) by wrapping the
40
    ellipsoidal region across parameter boundaries.
41
    """
42
```
43

44
### Transform Layers
45

46
Hierarchical transformations for parameter space conditioning and dimensionality reduction.
47

48
```python { .api }
49
class ScalingLayer:
50
    """
51
    Basic parameter scaling transformations.
52
    
53
    Applies scaling transformations to normalize parameter ranges
54
    and improve sampling efficiency across different scales.
55
    """
56

57
class AffineLayer(ScalingLayer):
58
    """
59
    Affine transformations including rotation and translation.
60
    
61
    Extends scaling with rotation and translation capabilities
62
    for handling correlated parameters and coordinate system changes.
63
    """
64

65
class LocalAffineLayer(AffineLayer):
66
    """
67
    Locally adaptive affine transformations.
68
    
69
    Applies different affine transformations in different regions
70
    of parameter space for optimal local conditioning.
71
    """
72

73
class MaxPrincipleGapAffineLayer(AffineLayer):
74
    """
75
    Affine layer based on maximum principle gap analysis.
76
    
77
    Uses gap statistics to determine optimal transformation
78
    parameters for maximum sampling efficiency.
79
    """
80
```
81

82
### Region Analysis Functions
83

84
Utility functions for analyzing and manipulating regions and point distributions.
85

86
```python { .api }
87
def find_nearby(points, query_point, region, **kwargs):
88
    """
89
    Find points near a query location within region constraints.
90
    
91
    Parameters:
92
    - points (array): Set of points to search
93
    - query_point (array): Location to search around
94
    - region: Constraining region
95
    
96
    Returns:
97
    array: Indices of nearby points
98
    """
99

100
def subtract_nearby(points, query_point, region, **kwargs):
101
    """
102
    Remove nearby points from a point set.
103
    
104
    Parameters:
105
    - points (array): Set of points to filter
106
    - query_point (array): Reference location
107
    - region: Constraining region
108
    
109
    Returns:
110
    array: Filtered point set with nearby points removed
111
    """
112

113
def compute_mean_pair_distance(points, **kwargs):
114
    """
115
    Compute mean pairwise distance in point set.
116
    
117
    Parameters:
118
    - points (array): Set of points for analysis
119
    
120
    Returns:
121
    float: Mean pairwise distance
122
    """
123

124
def bounding_ellipsoid(points, **kwargs):
125
    """
126
    Compute bounding ellipsoid for point set.
127
    
128
    Parameters:
129
    - points (array): Points to bound
130
    
131
    Returns:
132
    Ellipsoid parameters and transformation matrix
133
    """
134
```
135

136
## Usage Examples
137

138
### Basic Region Usage
139

140
```python
141
from ultranest import ReactiveNestedSampler
142
from ultranest.mlfriends import RobustEllipsoidRegion
143

144
# Region selection is typically automatic within ReactiveNestedSampler
145
sampler = ReactiveNestedSampler(
146
    param_names=['x', 'y', 'z'],
147
    loglike=loglike,
148
    transform=prior_transform
149
)
150

151
# Manual region configuration (advanced usage)
152
# region = RobustEllipsoidRegion()
153
# sampler.region = region
154
```
155

156
### Transform Layer Application
157

158
```python
159
from ultranest.mlfriends import AffineLayer
160

161
# Transform layers are automatically configured based on
162
# parameter correlations and problem structure
163
```
164

165
### Custom Region Analysis
166

167
```python
168
import numpy as np
169
from ultranest.mlfriends import find_nearby, compute_mean_pair_distance
170

171
# Analyze point distribution
172
points = np.random.randn(1000, 3)  # Example points
173
query = np.array([0, 0, 0])
174

175
# Find nearby points
176
nearby_indices = find_nearby(points, query, region=None)
177

178
# Compute characteristic distance scale
179
mean_distance = compute_mean_pair_distance(points)
180
```
181

182
## Advanced Region Configuration
183

184
### Wrapped Parameters
185

186
For problems with circular parameters (angles, phases):
187

188
```python
189
from ultranest.mlfriends import WrappingEllipsoid
190

191
# Configure wrapped parameters during sampler creation
192
sampler = ReactiveNestedSampler(
193
    param_names=['amplitude', 'phase', 'frequency'],
194
    loglike=loglike,
195
    transform=prior_transform,
196
    wrapped_params=[1]  # Phase parameter is circular
197
)
198

199
# Wrapping ellipsoid is automatically used for wrapped parameters
200
```
201

202
### Multi-Scale Problems
203

204
For problems with parameters spanning different scales:
205

206
```python
207
# Scaling layers are automatically applied based on parameter ranges
208
def prior_transform(cube):
209
    params = cube.copy()
210
    params[0] = cube[0] * 1e-6        # Small scale parameter
211
    params[1] = cube[1] * 1e6         # Large scale parameter  
212
    params[2] = cube[2] * 1.0         # Normal scale parameter
213
    return params
214

215
# ReactiveNestedSampler automatically handles scale differences
216
sampler = ReactiveNestedSampler(
217
    param_names=['small', 'large', 'normal'],
218
    loglike=loglike,
219
    transform=prior_transform
220
)
221
```
222

223
### High-Dimensional Spaces
224

225
For problems with many parameters and complex correlations:
226

227
```python
228
# LocalAffineLayer and advanced transformations are automatically
229
# selected for high-dimensional problems with complex structure
230

231
param_names = [f'param_{i}' for i in range(50)]  # 50 parameters
232

233
sampler = ReactiveNestedSampler(
234
    param_names=param_names,
235
    loglike=high_dim_loglike,
236
    transform=high_dim_prior_transform
237
)
238

239
# Advanced region analysis and transformations applied automatically
240
```
241

242
## Region Selection Guidelines
243

244
### Automatic Selection
245

246
The ReactiveNestedSampler automatically selects appropriate region types based on:
247

248
- **Parameter dimensionality**: Higher dimensions use more sophisticated regions
249
- **Correlation structure**: Correlated parameters trigger affine transformations
250
- **Wrapped parameters**: Circular parameters activate wrapping ellipsoids
251
- **Likelihood complexity**: Complex likelihoods use robust region methods
252

253
### Manual Configuration
254

255
For specialized applications requiring manual control:
256

257
```python
258
# Access region configuration after initialization
259
sampler = ReactiveNestedSampler(...)
260
current_region = sampler.region
261

262
# Modify region parameters (advanced usage)
263
# current_region.update_parameters(...)
264
```
265

266
### Performance Tuning
267

268
- **Simple problems**: SimpleRegion provides minimal overhead
269
- **Robust analysis**: RobustEllipsoidRegion handles outliers and irregular contours
270
- **Correlated parameters**: Affine layers improve efficiency for parameter correlations
271
- **Wrapped parameters**: WrappingEllipsoid essential for circular parameter spaces
272

273
The ML Friends region system provides automatic adaptation to problem structure while allowing manual control for specialized applications. The reactive sampler selects optimal region configurations based on problem analysis during the sampling process.