DCT-Toolkit: Convolutional Statistics

dct_toolkit provides DCT-based smoothing and normalized-convolution statistics for data with gaps. The current publication-prep track is intentionally focused on the convolution/statistics surface.

Current Scope (Stats-First)

• DCT-based smoothing for 1D/N-D Cartesian data.
• Per-axis Cartesian widths and kernel types, including mixed boxcar/Gaussian smoothing.
• Polar smoothing with adaptive azimuth widths and independent azimuth/range kernel types.
• Reflective boundaries via DCT and periodic azimuth boundaries via real FFT.
• Robust local statistics (dct_mean, dct_variance, dct_std, dct_count) with NaN support.

Installation

pip

pip install dct-toolkit

conda (pending conda-forge approval)

Conda-forge packaging has been submitted (PR under review). This option would be available soon:

conda install dct-toolkit

Quick Start

1) Robust Mean with Missing Data

import numpy as np
import dct_toolkit as dct

data = np.sin(np.linspace(0, 10, 200))
data[70:110] = np.nan

mu = dct.dct_mean(data, width=10.0)

1b) Prefill Before Full-Field Smoothing

smoothed = dct.dct_smooth(prefilled, width=10.0)

This function will call dct.dct_prefill() internally. We need to fill NaNs as requirement for DCT or FFT operations by default.

2) Polar Smoothing with Periodic Azimuth

For data in (azimuth, range) order, combine a boxcar along azimuth with a Gaussian along range:

smoothed = dct.dct_smooth(
    radar_data,
    width=(5.0, 3.0),
    coordinates="polar",
    kernel_type=("boxcar", "gaussian"),
    az_boundary="periodic",
    az_res_deg=1.0,
)

Both sequences follow (azimuth, range) order. Azimuth width adapts with range: width_azimuth / (r * dtheta) beams, where r starts at 1 and dtheta is the azimuth spacing in radians. Range width is in range gates. Gaussian sigma = effective_width / sqrt(12) on the selected axis. Filtering applies azimuth first, then range; both periodic and reflective azimuth support all three kernel types, including 'boxcar_discrete'. az_res_deg must be a finite, positive scalar in degrees. For gapped data, periodic azimuth also wraps the nearest-neighbor prefill fallback across the sweep seam; range distances remain nonperiodic.

3) Local Variability Estimates

var = dct.dct_variance(data, width=10.0)
std = dct.dct_std(data, width=10.0)

4) Mixed Kernels for a 3D Volume

For a volume stored in (z, y, x) order, apply Gaussian smoothing vertically and boxcar smoothing horizontally:

rng = np.random.default_rng(42)
volume = rng.standard_normal((16, 32, 32))  # (z, y, x)

smoothed = dct.dct_smooth(
    volume,
    width=(3.0, 5.0, 5.0),
    kernel_type=("gaussian", "boxcar", "boxcar"),
)

# The same kernels work with normalized statistics on data containing NaNs.
volume[5:7, 12:15, 12:15] = np.nan
mean = dct.dct_mean(
    volume,
    width=(3.0, 5.0, 5.0),
    kernel_type=("gaussian", "boxcar", "boxcar"),
)

Kernel and width sequences follow NumPy axis order and must have one entry per dimension. Widths are in grid cells along each axis; Gaussian sigma = width / sqrt(12). Convert physical widths using the corresponding grid spacing before calling. A scalar width applies equal widths, and a single kernel string applies that kernel to every axis. Equal widths with different kernel types can still produce anisotropic smoothing. Polar smoothing also accepts a kernel pair, using the (azimuth, range) convention shown above.

Quick Cheat Sheet

Pre-filling (dct_prefill)

dct_prefill provides an iterative normalized-convolution gap fill based on dct_mean:

• Fills gaps (NaNs or a specified mask) using iterative local averaging.
• Preserves non-target values exactly.
• Intended as a pre-processing step before full-field smoothing.
• max_iter=3 by default for predictable runtime; use max_iter=None to iterate until convergence (all NaNs filled). By default, any remaining NaNs are filled with the nearest valid data.

See the Quick Start section above for usage examples.

Documentation

• docs/MATHEMATICAL_BASIS.md — Mathematical foundations and theory
• docs/API_REFERENCE.md — Complete API documentation

License

MIT. See LICENSE.