0
# Kernel Functions
1
2
Built-in kernel functions with finite and infinite support for probability density estimation. Kernels define the shape of the probability density around each data point in kernel density estimation.
3
4
## Capabilities
5
6
### Available Kernels
7
8
Pre-defined kernel functions optimized for different smoothness and computational requirements.
9
10
```python { .api }
11
# Available kernel names for KDE constructors
12
AVAILABLE_KERNELS = [
13
"gaussian", # Gaussian/normal kernel (infinite support)
14
"exponential", # Exponential kernel (infinite support)
15
"box", # Box/uniform kernel (finite support)
16
"tri", # Triangular kernel (finite support)
17
"epa", # Epanechnikov kernel (finite support)
18
"biweight", # Biweight kernel (finite support)
19
"triweight", # Triweight kernel (finite support)
20
"tricube", # Tricube kernel (finite support)
21
"cosine" # Cosine kernel (finite support)
22
]
23
24
# Access kernel objects
25
from KDEpy.kernel_funcs import _kernel_functions
26
gaussian_kernel = _kernel_functions["gaussian"]
27
```
28
29
**Usage Example:**
30
31
```python
32
from KDEpy import FFTKDE
33
34
# Use different kernels by name
35
kde_gauss = FFTKDE(kernel='gaussian')
36
kde_epa = FFTKDE(kernel='epa')
37
kde_tri = FFTKDE(kernel='triweight')
38
39
# All kernels work with any KDE estimator
40
from KDEpy import TreeKDE, NaiveKDE
41
tree_box = TreeKDE(kernel='box')
42
naive_cosine = NaiveKDE(kernel='cosine')
43
```
44
45
### Kernel Class
46
47
Wrapper class for kernel functions providing evaluation and metadata.
48
49
```python { .api }
50
class Kernel:
51
def __init__(self, function, var=1, support=3):
52
"""
53
Initialize kernel function wrapper.
54
55
Parameters:
56
- function: callable, the kernel function to wrap
57
- var: float, variance of the kernel (default: 1)
58
- support: float, support radius of kernel (default: 3)
59
"""
60
61
def evaluate(self, x, bw=1, norm=2):
62
"""
63
Evaluate kernel function at given points.
64
65
Parameters:
66
- x: array-like, points to evaluate kernel at
67
- bw: float or array-like, bandwidth parameter
68
- norm: float, p-norm for distance computation (default: 2)
69
70
Returns:
71
- np.ndarray: Kernel values at input points
72
"""
73
74
# Properties
75
@property
76
def support(self):
77
"""float: Support radius of the kernel"""
78
79
@property
80
def var(self):
81
"""float: Variance of the kernel"""
82
83
@property
84
def function(self):
85
"""callable: The underlying kernel function"""
86
```
87
88
**Usage Example:**
89
90
```python
91
from KDEpy.kernel_funcs import Kernel, gaussian
92
import numpy as np
93
94
# Create custom kernel
95
def my_kernel(x, dims=1):
96
# Custom kernel implementation
97
return np.exp(-0.5 * x**2) / np.sqrt(2 * np.pi)
98
99
custom_kernel = Kernel(my_kernel, var=1.0, support=4.0)
100
101
# Evaluate kernel
102
x = np.linspace(-3, 3, 100)
103
values = custom_kernel.evaluate(x, bw=1.5)
104
105
# Use with KDE estimators
106
from KDEpy import NaiveKDE
107
kde = NaiveKDE(kernel=custom_kernel)
108
```
109
110
### Individual Kernel Functions
111
112
Raw kernel function implementations that can be used directly or wrapped in Kernel class.
113
114
```python { .api }
115
def gaussian(x, dims=1):
116
"""
117
Gaussian/normal kernel function.
118
119
Parameters:
120
- x: array-like, input distances
121
- dims: int, number of dimensions (default: 1)
122
123
Returns:
124
- np.ndarray: Kernel values
125
"""
126
127
def epanechnikov(x, dims=1):
128
"""
129
Epanechnikov kernel function (optimal in MSE sense).
130
131
Parameters:
132
- x: array-like, input distances
133
- dims: int, number of dimensions (default: 1)
134
135
Returns:
136
- np.ndarray: Kernel values
137
"""
138
139
def box(x, dims=1):
140
"""
141
Box/uniform kernel function.
142
143
Parameters:
144
- x: array-like, input distances
145
- dims: int, number of dimensions (default: 1)
146
147
Returns:
148
- np.ndarray: Kernel values
149
"""
150
151
def tri(x, dims=1):
152
"""
153
Triangular kernel function.
154
155
Parameters:
156
- x: array-like, input distances
157
- dims: int, number of dimensions (default: 1)
158
159
Returns:
160
- np.ndarray: Kernel values
161
"""
162
163
def biweight(x, dims=1):
164
"""
165
Biweight kernel function.
166
167
Parameters:
168
- x: array-like, input distances
169
- dims: int, number of dimensions (default: 1)
170
171
Returns:
172
- np.ndarray: Kernel values
173
"""
174
175
def triweight(x, dims=1):
176
"""
177
Triweight kernel function.
178
179
Parameters:
180
- x: array-like, input distances
181
- dims: int, number of dimensions (default: 1)
182
183
Returns:
184
- np.ndarray: Kernel values
185
"""
186
187
def tricube(x, dims=1):
188
"""
189
Tricube kernel function.
190
191
Parameters:
192
- x: array-like, input distances
193
- dims: int, number of dimensions (default: 1)
194
195
Returns:
196
- np.ndarray: Kernel values
197
"""
198
199
def cosine(x, dims=1):
200
"""
201
Cosine kernel function.
202
203
Parameters:
204
- x: array-like, input distances
205
- dims: int, number of dimensions (default: 1)
206
207
Returns:
208
- np.ndarray: Kernel values
209
"""
210
211
def exponential(x, dims=1):
212
"""
213
Exponential kernel function.
214
215
Parameters:
216
- x: array-like, input distances
217
- dims: int, number of dimensions (default: 1)
218
219
Returns:
220
- np.ndarray: Kernel values
221
"""
222
```
223
224
### Utility Functions
225
226
Helper functions for kernel computation and mathematical operations.
227
228
```python { .api }
229
def p_norm(x, p):
230
"""
231
Compute p-norm of input arrays.
232
233
Parameters:
234
- x: array-like, input array
235
- p: float, norm parameter (1=taxicab, 2=euclidean, inf=max)
236
237
Returns:
238
- np.ndarray: p-norm values
239
"""
240
241
def euclidean_norm(x):
242
"""
243
Compute Euclidean (L2) norm.
244
245
Parameters:
246
- x: array-like, input array
247
248
Returns:
249
- np.ndarray: Euclidean norm values
250
"""
251
252
def volume_unit_ball(d, p=2):
253
"""
254
Volume of unit ball in d dimensions with p-norm.
255
256
Parameters:
257
- d: int, number of dimensions
258
- p: float, norm parameter (default: 2)
259
260
Returns:
261
- float: Volume of unit ball
262
"""
263
264
def gauss_integral(n):
265
"""
266
Compute Gaussian integral for given dimension.
267
268
Parameters:
269
- n: int, dimension
270
271
Returns:
272
- float: Gaussian integral value
273
"""
274
```
275
276
## Kernel Properties and Selection
277
278
### Kernel Characteristics
279
280
Each kernel has different properties affecting smoothness and computational efficiency:
281
282
```python
283
from KDEpy.kernel_funcs import _kernel_functions
284
285
# Inspect kernel properties
286
for name, kernel in _kernel_functions.items():
287
print(f"{name}:")
288
print(f" Support: {kernel.support}")
289
print(f" Variance: {kernel.var}")
290
print(f" Finite support: {kernel.support < float('inf')}")
291
```
292
293
**Finite Support Kernels** (computationally efficient):
294
- `box` - Uniform distribution, discontinuous
295
- `tri` - Triangular, continuous but not smooth
296
- `epa` - Epanechnikov, optimal MSE properties
297
- `biweight` - Smooth, good compromise
298
- `triweight` - Very smooth
299
- `tricube` - Smooth with compact support
300
- `cosine` - Smooth, oscillation-free
301
302
**Infinite Support Kernels** (smooth but slower):
303
- `gaussian` - Most common, very smooth
304
- `exponential` - Heavy tails, robust to outliers
305
306
### Choosing Kernels
307
308
**For speed (finite support preferred)**:
309
```python
310
fast_kde = FFTKDE(kernel='epa') # Optimal finite support
311
fast_kde2 = TreeKDE(kernel='box') # Fastest computation
312
```
313
314
**For smoothness (infinite support)**:
315
```python
316
smooth_kde = NaiveKDE(kernel='gaussian') # Maximum smoothness
317
robust_kde = TreeKDE(kernel='exponential') # Heavy tails
318
```
319
320
**For balance**:
321
```python
322
balanced_kde = FFTKDE(kernel='biweight') # Good smoothness + finite support
323
```
324
325
### Custom Kernels
326
327
Define and use custom kernel functions:
328
329
```python
330
import numpy as np
331
from KDEpy import NaiveKDE
332
from KDEpy.kernel_funcs import Kernel
333
334
# Define custom kernel function
335
def custom_quartic(x, dims=1):
336
"""Custom quartic kernel"""
337
mask = np.abs(x) <= 1
338
result = np.zeros_like(x)
339
result[mask] = (15/16) * (1 - x[mask]**2)**2
340
return result
341
342
# Wrap in Kernel class
343
custom_kernel = Kernel(custom_quartic, var=1/5, support=1)
344
345
# Use with KDE
346
kde = NaiveKDE(kernel=custom_kernel)
347
kde.fit(data)
348
x, y = kde.evaluate()
349
350
# Or use function directly (for NaiveKDE only)
351
kde_direct = NaiveKDE(kernel=custom_quartic)
352
```
353
354
## Types
355
356
```python { .api }
357
from typing import Union, Callable
358
import numpy as np
359
360
# Kernel specification types
361
KernelName = str # One of AVAILABLE_KERNELS
362
KernelFunction = Callable[[np.ndarray, int], np.ndarray]
363
KernelSpec = Union[KernelName, KernelFunction, Kernel]
364
365
# Kernel function signature
366
KernelFunc = Callable[[np.ndarray, int], np.ndarray]
367
368
# Utility function types
369
NormFunction = Callable[[np.ndarray, float], np.ndarray]
370
VolumeFunction = Callable[[int, float], float]
371
```