dct-toolkit 0.4.0__py3-none-any.whl

dct_toolkit/__init__.py

@@ -0,0 +1,63 @@
+"""Public API for DCT-based convolution and statistical operations.
+
+The public top-level surface is intentionally scoped to smoothing and
+normalized-convolution statistics for the publication-focused release track.
+"""
+
+from typing import Any
+
+import numpy as np
+
+from .core import dct_convolve_1d, get_dct_transfer_function
+from .cartesian import smooth_cartesian
+from .polar import smooth_polar
+from .stats import dct_count, dct_mean, dct_prefill, dct_std, dct_variance
+
+__version__ = "0.4.0"
+
+
+__all__ = [
+    "__version__",
+    "get_dct_transfer_function",
+    "dct_convolve_1d",
+    "smooth_cartesian",
+    "smooth_polar",
+    "dct_smooth",
+    "dct_count",
+    "dct_mean",
+    "dct_prefill",
+    "dct_variance",
+    "dct_std",
+]
+
+
+def dct_smooth(
+    data: np.ndarray,
+    width: float,
+    coordinates: str = "cartesian",
+    **kwargs: Any,
+) -> np.ndarray:
+    """
+    Apply DCT-based smoothing.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data.
+    width : float
+        Smoothing width.
+    coordinates : str, default='cartesian'
+        'cartesian' or 'polar'.
+    **kwargs
+        Additional arguments (kernel_type, az_res_deg, etc.)
+
+    Returns
+    -------
+    smoothed : np.ndarray
+        Smoothed data.
+    """
+    if coordinates == "cartesian":
+        return smooth_cartesian(data, width, **kwargs)
+    if coordinates == "polar":
+        return smooth_polar(data, width_pixels=width, **kwargs)
+    raise ValueError(f"Unknown coordinates: {coordinates}")

dct_toolkit/cartesian.py

@@ -0,0 +1,41 @@
+"""
+2D Cartesian Smoothing.
+
+This module provides separable smoothing for N-D Cartesian data.
+It applies 1D smoothing sequentially along each dimension.
+"""
+
+import numpy as np
+from .core import get_dct_transfer_function, dct_convolve_1d
+
+def smooth_cartesian(data: np.ndarray, width: float, kernel_type: str = 'boxcar') -> np.ndarray:
+    """
+    Apply separable DCT smoothing to N-D Cartesian data.
+    
+    The smoothing is applied sequentially along each axis using the same
+    kernel type and width (isotropic smoothing).
+    
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data array (any dimension).
+    width : float
+        Smoothing width.
+    kernel_type : str, default='boxcar'
+        Kernel type ('boxcar', 'boxcar_discrete', 'gaussian').
+        
+    Returns
+    -------
+    smoothed : np.ndarray
+        Smoothed data with same shape as input.
+    """
+    result = data.copy()
+    ndim = data.ndim
+    
+    # Apply 1D smoothing along each axis
+    for axis in range(ndim):
+        n = data.shape[axis]
+        H = get_dct_transfer_function(n, kernel_type, width)
+        result = dct_convolve_1d(result, H, axis=axis)
+        
+    return result

dct_toolkit/core.py

@@ -0,0 +1,123 @@
+"""
+Core DCT Primitives and Transfer Functions.
+
+This module provides the low-level building blocks for DCT-based smoothing:
+1. Analytical and discrete transfer functions (H[k])
+2. 1D convolution primitive using DCT-II/Ortho
+"""
+
+import numpy as np
+import scipy.fft
+
+def get_dct_transfer_function(n: int, kernel_type: str, width: float) -> np.ndarray:
+    """
+    Generate the 1D DCT Transfer Function H[k].
+
+    Parameters
+    ----------
+    n : int
+        Number of points.
+    kernel_type : str
+        'boxcar', 'boxcar_discrete', or 'gaussian'.
+    width : float
+        Kernel width.
+        - boxcar: full width
+        - gaussian: equivalent boxcar width (sigma = width / sqrt(12))
+
+    Returns
+    -------
+    H : np.ndarray
+        Transfer function of shape (n,).
+    """
+    k = np.arange(n)
+    
+    if kernel_type == 'boxcar':
+        # Analytical Boxcar: H = sin(W * theta) / (W * sin(theta))
+        # where theta = pi * k / (2*n)
+        theta_half = (np.pi * k) / (2 * n)
+        
+        H = np.zeros(n)
+        H[0] = 1.0
+        
+        mask = k > 0
+        if np.any(mask):
+            numerator = np.sin(width * theta_half[mask])
+            denominator = np.sin(theta_half[mask])
+            
+            # Avoid division by zero
+            valid = np.abs(denominator) > 1e-15
+            safe_mask = np.zeros_like(mask)
+            safe_mask[mask] = valid
+            
+            if np.any(safe_mask):
+                H[safe_mask] = numerator[safe_mask[mask]] / (denominator[safe_mask[mask]] * width)
+                
+        return H
+        
+    elif kernel_type == 'boxcar_discrete':
+        # Discrete Boxcar Sum
+        # H[k] = (1 + 2*sum_{j=1}^{m} cos(j*w_k)) / w_int
+        w_int = int(np.round(width))
+        if w_int < 1: w_int = 1
+        if w_int % 2 == 0: w_int += 1
+        
+        w_k = (np.pi * k) / n
+        H = np.ones(n)
+        half_width = (w_int - 1) // 2
+        
+        for j in range(1, half_width + 1):
+            H += 2 * np.cos(j * w_k)
+            
+        H /= w_int
+        return H
+        
+    elif kernel_type == 'gaussian':
+        # Gaussian: sigma = width / sqrt(12)
+        sigma = width / np.sqrt(12)
+        if sigma < 1e-9:
+            return np.ones(n)
+            
+        # omega_k = pi * k / n
+        omega_k = (np.pi * k) / n
+        return np.exp(-0.5 * (omega_k * sigma)**2)
+    
+    else:
+        raise ValueError(f"Unknown kernel type: {kernel_type}")
+
+def dct_convolve_1d(data: np.ndarray, H: np.ndarray, axis: int = -1) -> np.ndarray:
+    """
+    Apply 1D DCT-based convolution.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data.
+    H : np.ndarray
+        Transfer function (must match data.shape[axis]).
+    axis : int
+        Axis to smooth along.
+
+    Returns
+    -------
+    smoothed : np.ndarray
+        Smoothed data.
+    """
+    # Validate shapes
+    if data.shape[axis] != len(H):
+        raise ValueError(f"Transfer function length {len(H)} does not match data dimension {data.shape[axis]}")
+
+    # Broadcast H to data shape
+    shape = [1] * data.ndim
+    shape[axis] = len(H)
+    H_reshaped = H.reshape(shape)
+    
+    # Forward DCT (Type-II, Ortho)
+    X = scipy.fft.dct(data, axis=axis, type=2, norm='ortho')
+    
+    # Apply transfer function
+    Y = X * H_reshaped
+    
+    # Inverse DCT (Type-II, Ortho)
+    y = scipy.fft.idct(Y, axis=axis, type=2, norm='ortho')
+    
+    return y