Metadata-Version: 2.4
Name: dct-toolkit
Version: 0.6.0
Summary: DCT/FFT-based convolutional statistics for Cartesian and polar data
Author-email: "Jairo M. Valdivia" <Jairo.ValdiviaPrado@colorado.edu>
License: MIT License
        
        Copyright (c) 2026 Jairo M. Valdivia
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: convolution,dct,fft,polar,radar,smoothing,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.8
Description-Content-Type: text/markdown

# DCT-Toolkit: Convolutional Statistics

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`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

```bash
pip install dct-toolkit
```

### conda (pending conda-forge approval)

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

```bash
conda install dct-toolkit
```

## Quick Start

### 1) Robust Mean with Missing Data

```python
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

```python
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:

```python
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

```python
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:

```python
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

| Function | Description |
|----------|-------------|
| `get_dct_transfer_function` | Build 1D spectral kernel `H[k]` from width and kernel type. |
| `dct_convolve_1d` | Apply one 1D DCT convolution along one axis using a precomputed `H`. |
| `smooth_cartesian` | Low-level separable smoothing for N-D Cartesian arrays. |
| `smooth_polar` | Low-level smoothing for 2D polar arrays with adaptive azimuth width. |
| `dct_smooth` | Top-level "just smooth this" wrapper (auto-pre-fills NaNs, then restores NaN mask). |
| `dct_mean` | NaN-robust local mean via normalized convolution. |
| `dct_count` | Effective local sample count from a validity mask. |
| `dct_prefill` | Iterative normalized-convolution gap fill (often used before full-field smoothing). |
| `dct_variance` | NaN-robust local variance from normalized-convolution moments. |
| `dct_std` | NaN-robust local standard deviation (`sqrt(dct_variance)`). |

## 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`.
