dct-toolkit 0.4.0__tar.gz → 0.6.0__tar.gz

{dct_toolkit-0.4.0 → dct_toolkit-0.6.0}/.gitignore

@@ -40,6 +40,7 @@ Thumbs.db
 # Jupyter
 .ipynb_checkpoints/
 *.ipynb
+!notebooks/*.ipynb
 
 # Environment
 .env
@@ -56,3 +57,8 @@ site/
 .mypy_cache/
 .dmypy.json
 dmypy.json
+
+# Local scratch / reference scripts
+.opencode/
+get_radar_smoothing.py
+radar_smoothing_ref.py

{dct_toolkit-0.4.0 → dct_toolkit-0.6.0}/AGENTS.md

@@ -1,9 +1,9 @@
 # AGENTS.md - DCT Toolkit Agent Guidelines
 
 **Project**: dct-toolkit  
-**Version**: 0.4.0  
-**Status**: Private Repository in Publication Preparation  
-**Last Updated**: 2026-04-10
+**Version**: 0.6.0  
+**Status**: Preparing v0.6.0 release (PyPI & conda-forge)  
+**Last Updated**: 2026-09-21
 
 ---
 
@@ -34,6 +34,19 @@ conda activate myenv
 python --version  # Should be 3.8+
 ```
 
+### dct-publish Environment (Publication & Development)
+Pre-configured environment for publication, testing, and notebook development:
+```bash
+conda activate dct-publish
+```
+
+**Packages installed:**
+- Python 3.11, numpy, scipy, pytest
+- xarray, matplotlib, cmweather (radar colormaps)
+- open-radar-data (sample radar datasets)
+- build, twine (for PyPI publishing)
+- dct-toolkit v0.5.0 (editable install)
+
 ### PYTHONPATH
 When running tests or examples from project root:
 ```bash
@@ -65,6 +78,8 @@ conda deactivate
 
 **Why isolated?** Building tools (`build`, `twine`) and their dependencies can conflict with other packages in your base environment (e.g., Sphinx, Streamlit). Always use an isolated environment for package operations.
 
+**Note:** The `dct-publish` environment is pre-configured for development, testing, and notebook work. Use it for day-to-day development. Create a fresh isolated environment only when you need to build/publish to PyPI.
+
 ---
 
 ## Code Style - Scientific Repository Standards
@@ -159,6 +174,9 @@ dct_toolkit/                    # PROJECT ROOT
 │   ├── basic_polar.py
 │   └── comprehensive_demo.py
 │
+├── notebooks/                 # JUPYTER NOTEBOOKS
+│   └── 01_getting_started.ipynb
+│
 ├── exp_v3/                    # EXPERIMENTS (reports + code)
 │   ├── figures/               # Generated figures (PNG/PDF)
 │   ├── test_width_impact.py
@@ -186,13 +204,12 @@ dct_toolkit/                    # PROJECT ROOT
 
 1. **Activate Environment**
    ```bash
-   conda activate myenv
+   conda activate dct-publish
    ```
 
 2. **Verify Baseline**
    ```bash
-   export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
-   python -m pytest tests/ -v
+   python -m pytest /path/to/dct_toolkit/tests/ -v
    ```
    All tests in `tests/` must pass before you start.
 
@@ -222,8 +239,8 @@ dct_toolkit/                    # PROJECT ROOT
 
 **Run Tests**:
 ```bash
-export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
-python -m pytest tests/ -v
+conda activate dct-publish
+python -m pytest /path/to/dct_toolkit/tests/ -v
 ```
 
 **Expected Output**: all tests passing
@@ -269,25 +286,27 @@ Before declaring task complete:
 - [x] Test suite (`tests/`) passing
 - [x] Documentation suite
 
-### 🚧 In Progress: Publication Readiness (stats-first)
-- [x] Fix immediate correctness issues in core statistics path
-- [x] Create a dedicated publication-prep branch
-- [ ] Update `AGENTS.md` / docs to reflect publication plan and current state
-- [ ] Build clean public-facing scope focused on convolution/statistics
-
-### 📋 Before Public Release
+### ✅ Completed (Publication Readiness)
+- [x] Fix immediate correctness issues in core statistics path (integer dtype bug)
+- [x] Create dedicated publication-prep branches
+- [x] Update `AGENTS.md` / docs to reflect publication plan
+- [x] Build clean public-facing scope focused on convolution/statistics
 - [x] Add packaging metadata (`pyproject.toml`)
-- [x] Add `LICENSE` and align README badges/claims
-- [ ] Define public API surface (exclude gap filling for initial public release)
-- [ ] Remove or relocate experimental assets from public-facing surface
-- [x] Add CI for tests and minimum quality checks
-
-### 🔭 Future (post-public v1)
+- [x] Add `LICENSE` (MIT) and align README badges/claims
+- [x] Define public API surface (exclude gap filling for initial public release)
+- [x] Remove experimental assets from public-facing surface
+- [x] Add CI for tests (`.github/workflows/tests.yml`)
+- [x] Publish to PyPI (v0.4.0 live at https://pypi.org/project/dct-toolkit/)
+- [x] Submit conda-forge recipe (PR #32930 in review)
+- [x] Merge publication work to `main` branch
+- [x] Tag `v0.4.0` release
+- [x] Create `research/gap-filling` branch for long-term research
+
+### 🔭 Future (v0.5.0 and beyond)
 - [ ] 3D support (volumetric data)
 - [ ] Additional kernels (Savitzky-Golay, Hanning)
 - [ ] Performance optimizations (numba?)
 - [ ] Jupyter notebook examples
-- [ ] conda-forge distribution
 - [ ] Advanced gap filling (constrained optimization)
 - [ ] GPU acceleration (CuPy)
 
@@ -326,7 +345,7 @@ Formula for robust mean with gaps:
 **Problem**: `ModuleNotFoundError: No module named 'dct_toolkit'`
 **Solution**: 
 ```bash
-export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
+conda activate dct-publish
 ```
 
 ### 2. Path Confusion
@@ -349,24 +368,69 @@ export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
 
 ## Repository Management
 
-### Private Repository (Current)
-- Hosted on: GitHub (private)
-- Access: Core team only
-- Branching: feature branches → main
-- Manual testing required until CI is added
-
-### Planned Public Release Scope
-- Initial public release is **convolution/statistics focused**
-- Keep DCT + periodic FFT boundary support in smoothing/statistical APIs
-- Defer gap-filling methods from initial public API surface
-- Add packaging metadata + license before publication
-
-### Publication Assets (Current Branch)
-- `pyproject.toml` for pip builds and installation
-- `LICENSE` (MIT)
-- `.github/workflows/tests.yml` (pytest on push/PR)
-- `docs/PUBLICATION_GUIDE.md` with pip + conda-forge steps
-- `conda.recipe/meta.yaml` starter recipe for staged-recipes submission
+### Branch Strategy
+
+We use a **trunk-based workflow** with dedicated branches for different purposes:
+
+| Branch | Purpose | Stability |
+|--------|---------|-----------|
+| `main` | Public releases, stable code | **Production-ready** |
+| `research/gap-filling` | Long-term gap-filling research | Experimental |
+| `feature/*` | Short-lived feature development | In-progress |
+
+#### `main` Branch (The Public Package)
+- Always matches the latest PyPI release
+- Contains only public API: core, cartesian, polar, stats
+- Gap-filling code exists in `gap_filling.py` but is **not exported** in `__init__.py`
+- All tests must pass before merging
+
+#### `research/gap-filling` Branch
+- Dedicated branch for long-term gap-filling research
+- Safe to experiment with `dct_inpaint`, `iterative_gap_fill`
+- Regularly merge `main` into this branch to get bug fixes and new features
+- Not merged back to `main` until research matures
+
+**To sync research branch with latest main:**
+```bash
+git checkout research/gap-filling
+git merge main
+```
+
+#### Feature Branches
+For new development (Hanning window, 3D support, notebooks):
+```bash
+# Create feature branch from main
+git checkout main
+git checkout -b feature/hanning-window
+
+# Work, commit, push
+git push origin feature/hanning-window
+
+# When done, merge to main via PR
+git checkout main
+git merge feature/hanning-window
+```
+
+### Repository Status
+- GitHub: Private (core team access only)
+- PyPI: **Public** — `pip install dct-toolkit` works
+- conda-forge: **Submitted** — PR #32930 in review at `conda-forge/staged-recipes`
+
+**Check conda-forge PR Status**:
+```bash
+gh pr view 32930 --repo conda-forge/staged-recipes
+# Or visit: https://github.com/conda-forge/staged-recipes/pull/32930
+```
+
+### Current Version
+- `v0.6.0` — Support for anisotropic smoothing widths, per-axis Cartesian kernels,
+  mixed polar kernels, periodic polar prefill, and effective density gating.
+- Tag: `git checkout v0.6.0`
+
+### Gap-Filling Status
+- Code exists in `dct_toolkit/gap_filling.py` (available for import directly)
+- **Not exported** in public API (`__init__.py`) — research-internal
+- Full gap-filling to be released in future v1.x after research matures
 
 ---
 
@@ -374,15 +438,13 @@ export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
 
 ### Documentation
 - **Math Theory**: `docs/MATHEMATICAL_BASIS.md`
-- **Gap Filling Basis**: `docs/GAP_FILLING_BASIS.md`
 - **API Details**: `docs/API_REFERENCE.md`
-- **Core Test Report**: `exp_v3/TEST_REPORT_CORE.md`
-- **Gap Filling Report**: `exp_v3/TEST_REPORT_GAP_FILLING.md`
+- **Getting Started**: `notebooks/01_getting_started.ipynb`
 
 ### Code Examples
+- **Getting Started Notebook**: `notebooks/01_getting_started.ipynb`
 - **Polar Smoothing**: `examples/basic_polar.py`
 - **Full Demo**: `examples/comprehensive_demo.py`
-- **Gap Filling**: `exp_v3/test_width_impact.py`
 
 ### Key Papers & References
 - Garcia (2010): DCT-PLS (contrast/background)
@@ -395,18 +457,28 @@ export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
 ## Quick Reference Card
 
 ```bash
-# Setup
-conda activate myenv
-export PYTHONPATH=$PYTHONPATH:$(pwd)/dct_toolkit
+# Install (pip)
+pip install dct-toolkit
+
+# Install (conda - once feed stock is merged)
+conda install -c conda-forge dct-toolkit
+
+# Development install from source
+git clone https://github.com/JValdivia23/dct-toolkit.git
+cd dct-toolkit
+pip install -e .
+
+# Activate dct-publish environment (for testing/notebooks)
+conda activate dct-publish
 
-# Test
-python -m pytest tests/ -v
+# Run tests (from project root)
+python -m pytest tests -v
 
 # Run example
 python examples/basic_polar.py
 
-# Benchmark
-python exp_v3/test_width_impact.py
+# Open Jupyter notebook
+jupyter notebook notebooks/01_getting_started.ipynb
 
 # Check imports (should be empty)
 grep -r "^from \.\./" dct_toolkit/dct_toolkit/

{dct_toolkit-0.4.0 → dct_toolkit-0.6.0}/CHANGELOG.md

@@ -5,27 +5,110 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.0] - 2026-09-21
+
+### Changed
+- Added anisotropic width support while keeping scalar width as the default path:
+  - Cartesian smoothing/stats now accept `width` as scalar or length-`ndim` sequence.
+  - Polar smoothing/stats now accept `width` as scalar or
+    `(width_azimuth, width_range)`.
+  - `dct_count` now uses anisotropic window area (`prod(widths)` in Cartesian,
+    `width_range * width_azimuth/(r*dtheta)` in polar).
+- `dct_prefill` now gates per-iteration mean estimates by the local valid-sample
+  density (`smooth(mask)`) with `min_effective_density=0.35` by default. This
+  stabilizes iterative gap-filling in low-support regions and uses the same
+  density signal that `dct_count / area` represents internally. The gate is
+  applied uniformly across Cartesian and polar coordinates and can be disabled
+  by passing `min_effective_density=None`.
+
+### Added
+- Added mixed polar kernels in `(azimuth, range)` order for `smooth_polar`,
+  both polar transfer-function entry points, and high-level smoothing,
+  statistics, and prefill. A single string still applies to both dimensions.
+  Both azimuth boundary modes retain range-adaptive widths and apply azimuth
+  smoothing before reflective range smoothing.
+- Added independent polar reference tests covering all mixed kernel pairs,
+  circular discrete averaging, odd/even azimuth lengths, singleton axes,
+  input validation, normalized statistics, prefill, and NaN handling.
+- Added per-axis Cartesian kernel types: `kernel_type` accepts a string or a
+  length-`ndim` sequence of `'boxcar'`, `'boxcar_discrete'`, and `'gaussian'`.
+  Mixed kernels work with scalar/per-axis widths in `smooth_cartesian`,
+  `dct_smooth`, and Cartesian statistics/prefill. Existing single-string calls
+  retain their behavior; the backend still uses one forward/inverse N-D DCT pair.
+- Added mixed-kernel reference, validation, and NaN-handling tests, plus a 3D
+  usage example and documentation of array axis order and Gaussian width units.
+- Added parity and artifact-regression tests for scalar-vs-vector isotropic widths,
+  plus anisotropic Cartesian/polar smoke coverage.
+- Added `min_effective_density` keyword argument to `dct_prefill` (default
+  `0.35`) and `dct_mean` (default `None`, opt-in) for count-based stability
+  gating. When set, `dct_mean` returns NaN wherever the local valid-sample
+  density is below the threshold. New tests in `tests/test_stats.py` cover
+  the default, the disabled, the custom threshold, and the polar-coordinates
+  paths.
+
+### Fixed
+- Polar nearest-neighbor prefill now respects periodic azimuth in both axis-wise
+  propagation and the global fallback, correcting seam-dependent results on
+  sparse sweeps. Range propagation remains nonperiodic. Added sparse-sweep
+  rotation, targeted global fallback, and singleton-axis regression tests.
+- Polar smoothing, statistics, and prefill now require a finite, positive real
+  scalar `az_res_deg`, including calls that return early without smoothing.
+  Shared spacing validation prevents negative counts and invalid width arithmetic;
+  tests cover invalid inputs and valid fractional/NumPy scalar spacings.
+- Periodic azimuth with `'boxcar_discrete'` now uses an actual centered discrete
+  boxcar with an odd integer window, matching the reflective width convention.
+  It previously substituted a Gaussian, so results for this option intentionally
+  change for both single-string and mixed-kernel calls.
+
+## [0.5.0] - 2026-04-14
+
+### Changed
+- `smooth_cartesian` now uses a single N-D spectral pass (`dctn/idctn`) with
+  broadcasted separable transfer functions, preserving output equivalence while
+  reducing transform overhead for higher-dimensional Cartesian arrays.
+- Default smoothing kernel is now `'gaussian'` for Cartesian and polar smoothing paths
+  (`smooth_cartesian`, `smooth_polar`, and all wrapper/statistics calls that inherit
+  those defaults).
+- `dct_smooth` now enforces a NaN-safe smoothing pipeline: if NaNs are present, it
+  automatically pre-fills missing values before spectral smoothing and restores the
+  original NaN mask afterward.
+- `dct_prefill` now applies mandatory nearest-neighbor residual fill for unresolved
+  targets, guaranteeing finite arrays for downstream spectral smoothing when support
+  exists.
+- Default prefill iteration count is now `max_iter=3` for predictable runtime. You can
+  still set `max_iter=None` to iterate until convergence (safety cap: 20).
+- `dct_mean`, `dct_variance`, and `dct_std` now include stable fallback handling for
+  poorly conditioned normalized-convolution regions (heavy-gap volumes), preventing
+  NaN/overflow behavior in low-support areas when valid support exists.
+- `dct_count` now clips smoothed density to `[0, 1]` before area scaling to keep
+  effective sample counts physically valid.
+- `dct_count`, `dct_mean`, `dct_variance`, and `dct_std` now default to
+  `restore_input_nan=True`, masking outputs at original invalid locations while
+  keeping valid locations stable and finite.
+
+### Added
+- Added NaN-policy regression tests for `dct_smooth` and new `dct_prefill` iteration/
+  residual behavior (`tests/test_api.py`, updates in `tests/test_stats.py`).
+- Added Cartesian N-D equivalence tests to verify artifact-free 3D/4D outputs and
+  new N-D statistics smoke tests (`tests/test_cartesian.py`, `tests/test_stats_nd.py`).
+
+## [0.4.1] - 2026-04-12
 
 ### Added
-- **Packaging + distribution groundwork**:
-    - Added `pyproject.toml` (PEP 517/518 via hatchling) for pip/wheel builds.
-    - Added `LICENSE` (MIT).
-    - Added GitHub Actions CI workflow `.github/workflows/tests.yml`.
-    - Added `docs/PUBLICATION_GUIDE.md` with PyPI + conda-forge release steps.
-    - Added `conda.recipe/meta.yaml` starter recipe for conda-forge submission prep.
-- **Statistics API**:
-    - Added `dct_prefill` (iterative normalized-convolution prefill) and exported it
-      in the top-level API.
-    - Added regression tests for `dct_prefill` behavior and parameter validation.
+- **Jupyter Notebook**: Added `notebooks/01_getting_started.ipynb` with interactive
+  tutorial for DCT smoothing and statistics.
+- Updated `.gitignore` to allow notebooks in `notebooks/` folder.
 
 ### Changed
-- `stats.py`: improved dtype handling for integer inputs in `dct_mean`/`dct_variance`
-  with floating-point outputs and explicit mask-shape validation.
-- `README.md` and `docs/API_REFERENCE.md`: refocused public surface on
-  convolution/statistics and documented `dct_prefill`.
-- `examples/comprehensive_demo.py`: removed stale experimental imports and aligned
-  with stats-first public API.
+- **Repository Cleanup**: Moved experimental content to `research/gap-filling` branch:
+    - Removed `exp_v3/` and `exp_v4/` experimental folders from main branch.
+    - Removed `docs/GAP_FILLING_BASIS.md` and `docs/PUBLICATION_GUIDE.md` from main branch.
+    - `gap_filling.py` remains in codebase but is **not exported** in public API.
+- `__init__.py`: Version bumped to `0.4.1`.
+
+### Notes
+- Main branch now contains only core package functionality for stable PyPI releases.
+- All experimental work (gap filling, inpainting) preserved in `research/gap-filling` branch.
 
 ## [0.4.0] - 2026-02-28
 

dct_toolkit-0.6.0/PKG-INFO

@@ -0,0 +1,199 @@
+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`.