tessl/pypi-kdepy

Kernel Density Estimation in Python with three high-performance algorithms through a unified API.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Kernel Functions

Name: tessl/pypi-kdepy
Author: tessl

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.

Capabilities

Available Kernels

Pre-defined kernel functions optimized for different smoothness and computational requirements.

# Available kernel names for KDE constructors
AVAILABLE_KERNELS = [
    "gaussian",     # Gaussian/normal kernel (infinite support)
    "exponential",  # Exponential kernel (infinite support)  
    "box",         # Box/uniform kernel (finite support)
    "tri",         # Triangular kernel (finite support)
    "epa",         # Epanechnikov kernel (finite support)
    "biweight",    # Biweight kernel (finite support)
    "triweight",   # Triweight kernel (finite support) 
    "tricube",     # Tricube kernel (finite support)
    "cosine"       # Cosine kernel (finite support)
]

# Access kernel objects
from KDEpy.kernel_funcs import _kernel_functions
gaussian_kernel = _kernel_functions["gaussian"]

Usage Example:

from KDEpy import FFTKDE

# Use different kernels by name
kde_gauss = FFTKDE(kernel='gaussian')
kde_epa = FFTKDE(kernel='epa') 
kde_tri = FFTKDE(kernel='triweight')

# All kernels work with any KDE estimator
from KDEpy import TreeKDE, NaiveKDE
tree_box = TreeKDE(kernel='box')
naive_cosine = NaiveKDE(kernel='cosine')

Kernel Class

Wrapper class for kernel functions providing evaluation and metadata.

class Kernel:
    def __init__(self, function, var=1, support=3):
        """
        Initialize kernel function wrapper.
        
        Parameters:
        - function: callable, the kernel function to wrap
        - var: float, variance of the kernel (default: 1)
        - support: float, support radius of kernel (default: 3)
        """
    
    def evaluate(self, x, bw=1, norm=2):
        """
        Evaluate kernel function at given points.
        
        Parameters:
        - x: array-like, points to evaluate kernel at
        - bw: float or array-like, bandwidth parameter
        - norm: float, p-norm for distance computation (default: 2)
        
        Returns:
        - np.ndarray: Kernel values at input points
        """
    
    # Properties
    @property
    def support(self):
        """float: Support radius of the kernel"""
    
    @property  
    def var(self):
        """float: Variance of the kernel"""
        
    @property
    def function(self):
        """callable: The underlying kernel function"""

Usage Example:

from KDEpy.kernel_funcs import Kernel, gaussian
import numpy as np

# Create custom kernel
def my_kernel(x, dims=1):
    # Custom kernel implementation
    return np.exp(-0.5 * x**2) / np.sqrt(2 * np.pi)

custom_kernel = Kernel(my_kernel, var=1.0, support=4.0)

# Evaluate kernel
x = np.linspace(-3, 3, 100)
values = custom_kernel.evaluate(x, bw=1.5)

# Use with KDE estimators
from KDEpy import NaiveKDE
kde = NaiveKDE(kernel=custom_kernel)

Individual Kernel Functions

Raw kernel function implementations that can be used directly or wrapped in Kernel class.

def gaussian(x, dims=1):
    """
    Gaussian/normal kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def epanechnikov(x, dims=1):
    """
    Epanechnikov kernel function (optimal in MSE sense).
    
    Parameters:
    - x: array-like, input distances  
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def box(x, dims=1):
    """
    Box/uniform kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def tri(x, dims=1):
    """
    Triangular kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def biweight(x, dims=1):
    """
    Biweight kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def triweight(x, dims=1):
    """
    Triweight kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def tricube(x, dims=1):
    """
    Tricube kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def cosine(x, dims=1):
    """
    Cosine kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

def exponential(x, dims=1):
    """
    Exponential kernel function.
    
    Parameters:
    - x: array-like, input distances
    - dims: int, number of dimensions (default: 1)
    
    Returns:
    - np.ndarray: Kernel values
    """

Utility Functions

Helper functions for kernel computation and mathematical operations.

def p_norm(x, p):
    """
    Compute p-norm of input arrays.
    
    Parameters:
    - x: array-like, input array
    - p: float, norm parameter (1=taxicab, 2=euclidean, inf=max)
    
    Returns:
    - np.ndarray: p-norm values
    """

def euclidean_norm(x):
    """
    Compute Euclidean (L2) norm.
    
    Parameters:  
    - x: array-like, input array
    
    Returns:
    - np.ndarray: Euclidean norm values
    """

def volume_unit_ball(d, p=2):
    """
    Volume of unit ball in d dimensions with p-norm.
    
    Parameters:
    - d: int, number of dimensions
    - p: float, norm parameter (default: 2)
    
    Returns:
    - float: Volume of unit ball
    """

def gauss_integral(n):
    """
    Compute Gaussian integral for given dimension.
    
    Parameters:
    - n: int, dimension
    
    Returns:
    - float: Gaussian integral value
    """

Kernel Properties and Selection

Kernel Characteristics

Each kernel has different properties affecting smoothness and computational efficiency:

from KDEpy.kernel_funcs import _kernel_functions

# Inspect kernel properties
for name, kernel in _kernel_functions.items():
    print(f"{name}:")
    print(f"  Support: {kernel.support}")
    print(f"  Variance: {kernel.var}")
    print(f"  Finite support: {kernel.support < float('inf')}")

Finite Support Kernels (computationally efficient):

box - Uniform distribution, discontinuous
tri - Triangular, continuous but not smooth
epa - Epanechnikov, optimal MSE properties
biweight - Smooth, good compromise
triweight - Very smooth
tricube - Smooth with compact support
cosine - Smooth, oscillation-free

Infinite Support Kernels (smooth but slower):

gaussian - Most common, very smooth
exponential - Heavy tails, robust to outliers

Choosing Kernels

For speed (finite support preferred):

fast_kde = FFTKDE(kernel='epa')     # Optimal finite support
fast_kde2 = TreeKDE(kernel='box')   # Fastest computation

For smoothness (infinite support):

smooth_kde = NaiveKDE(kernel='gaussian')     # Maximum smoothness
robust_kde = TreeKDE(kernel='exponential')   # Heavy tails

For balance:

balanced_kde = FFTKDE(kernel='biweight')   # Good smoothness + finite support

Custom Kernels

Define and use custom kernel functions:

import numpy as np
from KDEpy import NaiveKDE
from KDEpy.kernel_funcs import Kernel

# Define custom kernel function
def custom_quartic(x, dims=1):
    """Custom quartic kernel"""
    mask = np.abs(x) <= 1
    result = np.zeros_like(x)
    result[mask] = (15/16) * (1 - x[mask]**2)**2
    return result

# Wrap in Kernel class
custom_kernel = Kernel(custom_quartic, var=1/5, support=1)

# Use with KDE
kde = NaiveKDE(kernel=custom_kernel)
kde.fit(data)
x, y = kde.evaluate()

# Or use function directly (for NaiveKDE only)
kde_direct = NaiveKDE(kernel=custom_quartic)

Types

from typing import Union, Callable
import numpy as np

# Kernel specification types
KernelName = str  # One of AVAILABLE_KERNELS
KernelFunction = Callable[[np.ndarray, int], np.ndarray]
KernelSpec = Union[KernelName, KernelFunction, Kernel]

# Kernel function signature
KernelFunc = Callable[[np.ndarray, int], np.ndarray]

# Utility function types
NormFunction = Callable[[np.ndarray, float], np.ndarray]
VolumeFunction = Callable[[int, float], float]

Install with Tessl CLI