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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/.gitignore +5 -0
  2. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/AGENTS.md +7 -7
  3. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/CHANGELOG.md +42 -1
  4. dct_toolkit-0.6.0/PKG-INFO +199 -0
  5. dct_toolkit-0.6.0/README.md +153 -0
  6. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/__init__.py +14 -5
  7. dct_toolkit-0.6.0/dct_toolkit/_kernels.py +31 -0
  8. dct_toolkit-0.6.0/dct_toolkit/cartesian.py +87 -0
  9. dct_toolkit-0.6.0/dct_toolkit/polar.py +295 -0
  10. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/stats.py +181 -41
  11. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/docs/API_REFERENCE.md +139 -13
  12. dct_toolkit-0.6.0/docs/MATHEMATICAL_BASIS.md +178 -0
  13. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/pyproject.toml +2 -2
  14. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_api.py +28 -0
  15. dct_toolkit-0.6.0/tests/test_cartesian.py +195 -0
  16. dct_toolkit-0.6.0/tests/test_polar_kernels.py +244 -0
  17. dct_toolkit-0.6.0/tests/test_polar_robustness.py +157 -0
  18. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_stats.py +214 -0
  19. dct_toolkit-0.6.0/tests/test_stats_nd.py +116 -0
  20. dct_toolkit-0.5.0/PKG-INFO +0 -161
  21. dct_toolkit-0.5.0/README.md +0 -115
  22. dct_toolkit-0.5.0/dct_toolkit/cartesian.py +0 -56
  23. dct_toolkit-0.5.0/dct_toolkit/polar.py +0 -275
  24. dct_toolkit-0.5.0/docs/MATHEMATICAL_BASIS.md +0 -77
  25. dct_toolkit-0.5.0/tests/test_cartesian.py +0 -104
  26. dct_toolkit-0.5.0/tests/test_stats_nd.py +0 -37
  27. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/LICENSE +0 -0
  28. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/_widths.py +0 -0
  29. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/core.py +0 -0
  30. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/gap_filling.py +0 -0
  31. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/examples/basic_polar.py +0 -0
  32. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/examples/comprehensive_demo.py +0 -0
  33. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_core.py +0 -0
  34. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_gap_filling.py +0 -0
  35. {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_polar.py +0 -0
@@ -57,3 +57,8 @@ site/
57
57
  .mypy_cache/
58
58
  .dmypy.json
59
59
  dmypy.json
60
+
61
+ # Local scratch / reference scripts
62
+ .opencode/
63
+ get_radar_smoothing.py
64
+ radar_smoothing_ref.py
@@ -1,9 +1,9 @@
1
1
  # AGENTS.md - DCT Toolkit Agent Guidelines
2
2
 
3
3
  **Project**: dct-toolkit
4
- **Version**: 0.5.0
5
- **Status**: Published — PyPI live, conda-forge PR under review
6
- **Last Updated**: 2026-04-14
4
+ **Version**: 0.6.0
5
+ **Status**: Preparing v0.6.0 release (PyPI & conda-forge)
6
+ **Last Updated**: 2026-09-21
7
7
 
8
8
  ---
9
9
 
@@ -45,7 +45,7 @@ conda activate dct-publish
45
45
  - xarray, matplotlib, cmweather (radar colormaps)
46
46
  - open-radar-data (sample radar datasets)
47
47
  - build, twine (for PyPI publishing)
48
- - dct-toolkit v0.4.0 (editable install)
48
+ - dct-toolkit v0.5.0 (editable install)
49
49
 
50
50
  ### PYTHONPATH
51
51
  When running tests or examples from project root:
@@ -423,9 +423,9 @@ gh pr view 32930 --repo conda-forge/staged-recipes
423
423
  ```
424
424
 
425
425
  ### Current Version
426
- - `v0.5.0` — N-D Cartesian smoothing backend upgrade (`dctn/idctn`) with
427
- validated 3D/4D parity and stats compatibility.
428
- - Tag: `git checkout v0.5.0`
426
+ - `v0.6.0` — Support for anisotropic smoothing widths, per-axis Cartesian kernels,
427
+ mixed polar kernels, periodic polar prefill, and effective density gating.
428
+ - Tag: `git checkout v0.6.0`
429
429
 
430
430
  ### Gap-Filling Status
431
431
  - Code exists in `dct_toolkit/gap_filling.py` (available for import directly)
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [Unreleased]
8
+ ## [0.6.0] - 2026-09-21
9
9
 
10
10
  ### Changed
11
11
  - Added anisotropic width support while keeping scalar width as the default path:
@@ -14,10 +14,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
14
14
  `(width_azimuth, width_range)`.
15
15
  - `dct_count` now uses anisotropic window area (`prod(widths)` in Cartesian,
16
16
  `width_range * width_azimuth/(r*dtheta)` in polar).
17
+ - `dct_prefill` now gates per-iteration mean estimates by the local valid-sample
18
+ density (`smooth(mask)`) with `min_effective_density=0.35` by default. This
19
+ stabilizes iterative gap-filling in low-support regions and uses the same
20
+ density signal that `dct_count / area` represents internally. The gate is
21
+ applied uniformly across Cartesian and polar coordinates and can be disabled
22
+ by passing `min_effective_density=None`.
17
23
 
18
24
  ### Added
25
+ - Added mixed polar kernels in `(azimuth, range)` order for `smooth_polar`,
26
+ both polar transfer-function entry points, and high-level smoothing,
27
+ statistics, and prefill. A single string still applies to both dimensions.
28
+ Both azimuth boundary modes retain range-adaptive widths and apply azimuth
29
+ smoothing before reflective range smoothing.
30
+ - Added independent polar reference tests covering all mixed kernel pairs,
31
+ circular discrete averaging, odd/even azimuth lengths, singleton axes,
32
+ input validation, normalized statistics, prefill, and NaN handling.
33
+ - Added per-axis Cartesian kernel types: `kernel_type` accepts a string or a
34
+ length-`ndim` sequence of `'boxcar'`, `'boxcar_discrete'`, and `'gaussian'`.
35
+ Mixed kernels work with scalar/per-axis widths in `smooth_cartesian`,
36
+ `dct_smooth`, and Cartesian statistics/prefill. Existing single-string calls
37
+ retain their behavior; the backend still uses one forward/inverse N-D DCT pair.
38
+ - Added mixed-kernel reference, validation, and NaN-handling tests, plus a 3D
39
+ usage example and documentation of array axis order and Gaussian width units.
19
40
  - Added parity and artifact-regression tests for scalar-vs-vector isotropic widths,
20
41
  plus anisotropic Cartesian/polar smoke coverage.
42
+ - Added `min_effective_density` keyword argument to `dct_prefill` (default
43
+ `0.35`) and `dct_mean` (default `None`, opt-in) for count-based stability
44
+ gating. When set, `dct_mean` returns NaN wherever the local valid-sample
45
+ density is below the threshold. New tests in `tests/test_stats.py` cover
46
+ the default, the disabled, the custom threshold, and the polar-coordinates
47
+ paths.
48
+
49
+ ### Fixed
50
+ - Polar nearest-neighbor prefill now respects periodic azimuth in both axis-wise
51
+ propagation and the global fallback, correcting seam-dependent results on
52
+ sparse sweeps. Range propagation remains nonperiodic. Added sparse-sweep
53
+ rotation, targeted global fallback, and singleton-axis regression tests.
54
+ - Polar smoothing, statistics, and prefill now require a finite, positive real
55
+ scalar `az_res_deg`, including calls that return early without smoothing.
56
+ Shared spacing validation prevents negative counts and invalid width arithmetic;
57
+ tests cover invalid inputs and valid fractional/NumPy scalar spacings.
58
+ - Periodic azimuth with `'boxcar_discrete'` now uses an actual centered discrete
59
+ boxcar with an odd integer window, matching the reflective width convention.
60
+ It previously substituted a Gaussian, so results for this option intentionally
61
+ change for both single-string and mixed-kernel calls.
21
62
 
22
63
  ## [0.5.0] - 2026-04-14
23
64
 
@@ -0,0 +1,199 @@
1
+ Metadata-Version: 2.4
2
+ Name: dct-toolkit
3
+ Version: 0.6.0
4
+ Summary: DCT/FFT-based convolutional statistics for Cartesian and polar data
5
+ Author-email: "Jairo M. Valdivia" <Jairo.ValdiviaPrado@colorado.edu>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Jairo M. Valdivia
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+ License-File: LICENSE
28
+ Keywords: convolution,dct,fft,polar,radar,smoothing,statistics
29
+ Classifier: Development Status :: 4 - Beta
30
+ Classifier: Intended Audience :: Developers
31
+ Classifier: Intended Audience :: Science/Research
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Programming Language :: Python :: 3 :: Only
35
+ Classifier: Programming Language :: Python :: 3.8
36
+ Classifier: Programming Language :: Python :: 3.9
37
+ Classifier: Programming Language :: Python :: 3.10
38
+ Classifier: Programming Language :: Python :: 3.11
39
+ Classifier: Programming Language :: Python :: 3.12
40
+ Classifier: Topic :: Scientific/Engineering
41
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
42
+ Requires-Python: >=3.8
43
+ Requires-Dist: numpy>=1.20
44
+ Requires-Dist: scipy>=1.8
45
+ Description-Content-Type: text/markdown
46
+
47
+ # DCT-Toolkit: Convolutional Statistics
48
+
49
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
50
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
51
+
52
+ `dct_toolkit` provides DCT-based smoothing and normalized-convolution statistics for
53
+ data with gaps. The current publication-prep track is intentionally focused on the
54
+ convolution/statistics surface.
55
+
56
+ ## Current Scope (Stats-First)
57
+
58
+ - DCT-based smoothing for 1D/N-D Cartesian data.
59
+ - Per-axis Cartesian widths and kernel types, including mixed boxcar/Gaussian smoothing.
60
+ - Polar smoothing with adaptive azimuth widths and independent azimuth/range kernel types.
61
+ - Reflective boundaries via DCT and periodic azimuth boundaries via real FFT.
62
+ - Robust local statistics (`dct_mean`, `dct_variance`, `dct_std`, `dct_count`) with NaN support.
63
+
64
+ ## Installation
65
+
66
+ ### pip
67
+
68
+ ```bash
69
+ pip install dct-toolkit
70
+ ```
71
+
72
+ ### conda (pending conda-forge approval)
73
+
74
+ Conda-forge packaging has been submitted (PR under review). This option would be available soon:
75
+
76
+ ```bash
77
+ conda install dct-toolkit
78
+ ```
79
+
80
+ ## Quick Start
81
+
82
+ ### 1) Robust Mean with Missing Data
83
+
84
+ ```python
85
+ import numpy as np
86
+ import dct_toolkit as dct
87
+
88
+ data = np.sin(np.linspace(0, 10, 200))
89
+ data[70:110] = np.nan
90
+
91
+ mu = dct.dct_mean(data, width=10.0)
92
+ ```
93
+
94
+ ### 1b) Prefill Before Full-Field Smoothing
95
+
96
+ ```python
97
+ smoothed = dct.dct_smooth(prefilled, width=10.0)
98
+ ```
99
+ This function will call `dct.dct_prefill()` internally. We need to fill NaNs as requirement for DCT or FFT operations by default.
100
+
101
+ ### 2) Polar Smoothing with Periodic Azimuth
102
+
103
+ For data in **(azimuth, range)** order, combine a boxcar along azimuth with a
104
+ Gaussian along range:
105
+
106
+ ```python
107
+ smoothed = dct.dct_smooth(
108
+ radar_data,
109
+ width=(5.0, 3.0),
110
+ coordinates="polar",
111
+ kernel_type=("boxcar", "gaussian"),
112
+ az_boundary="periodic",
113
+ az_res_deg=1.0,
114
+ )
115
+ ```
116
+
117
+ Both sequences follow `(azimuth, range)` order. Azimuth width adapts with range:
118
+ `width_azimuth / (r * dtheta)` beams, where `r` starts at 1 and `dtheta` is the
119
+ azimuth spacing in radians. Range width is in range gates. Gaussian
120
+ `sigma = effective_width / sqrt(12)` on the selected axis. Filtering applies
121
+ azimuth first, then range; both periodic and reflective azimuth support all
122
+ three kernel types, including `'boxcar_discrete'`.
123
+ `az_res_deg` must be a finite, positive scalar in degrees. For gapped data,
124
+ periodic azimuth also wraps the nearest-neighbor prefill fallback across the
125
+ sweep seam; range distances remain nonperiodic.
126
+
127
+ ### 3) Local Variability Estimates
128
+
129
+ ```python
130
+ var = dct.dct_variance(data, width=10.0)
131
+ std = dct.dct_std(data, width=10.0)
132
+ ```
133
+
134
+ ### 4) Mixed Kernels for a 3D Volume
135
+
136
+ For a volume stored in **(z, y, x)** order, apply Gaussian smoothing vertically
137
+ and boxcar smoothing horizontally:
138
+
139
+ ```python
140
+ rng = np.random.default_rng(42)
141
+ volume = rng.standard_normal((16, 32, 32)) # (z, y, x)
142
+
143
+ smoothed = dct.dct_smooth(
144
+ volume,
145
+ width=(3.0, 5.0, 5.0),
146
+ kernel_type=("gaussian", "boxcar", "boxcar"),
147
+ )
148
+
149
+ # The same kernels work with normalized statistics on data containing NaNs.
150
+ volume[5:7, 12:15, 12:15] = np.nan
151
+ mean = dct.dct_mean(
152
+ volume,
153
+ width=(3.0, 5.0, 5.0),
154
+ kernel_type=("gaussian", "boxcar", "boxcar"),
155
+ )
156
+ ```
157
+
158
+ Kernel and width sequences follow NumPy axis order and must have one entry per
159
+ dimension. Widths are in grid cells along each axis; Gaussian
160
+ `sigma = width / sqrt(12)`. Convert physical widths using the corresponding
161
+ grid spacing before calling. A scalar width applies equal widths, and a single
162
+ kernel string applies that kernel to every axis. Equal widths with different
163
+ kernel types can still produce anisotropic smoothing. Polar smoothing also
164
+ accepts a kernel pair, using the `(azimuth, range)` convention shown above.
165
+
166
+ ## Quick Cheat Sheet
167
+
168
+ | Function | Description |
169
+ |----------|-------------|
170
+ | `get_dct_transfer_function` | Build 1D spectral kernel `H[k]` from width and kernel type. |
171
+ | `dct_convolve_1d` | Apply one 1D DCT convolution along one axis using a precomputed `H`. |
172
+ | `smooth_cartesian` | Low-level separable smoothing for N-D Cartesian arrays. |
173
+ | `smooth_polar` | Low-level smoothing for 2D polar arrays with adaptive azimuth width. |
174
+ | `dct_smooth` | Top-level "just smooth this" wrapper (auto-pre-fills NaNs, then restores NaN mask). |
175
+ | `dct_mean` | NaN-robust local mean via normalized convolution. |
176
+ | `dct_count` | Effective local sample count from a validity mask. |
177
+ | `dct_prefill` | Iterative normalized-convolution gap fill (often used before full-field smoothing). |
178
+ | `dct_variance` | NaN-robust local variance from normalized-convolution moments. |
179
+ | `dct_std` | NaN-robust local standard deviation (`sqrt(dct_variance)`). |
180
+
181
+ ## Pre-filling (`dct_prefill`)
182
+
183
+ `dct_prefill` provides an **iterative normalized-convolution gap fill** based on `dct_mean`:
184
+
185
+ - Fills gaps (NaNs or a specified mask) using iterative local averaging.
186
+ - Preserves non-target values exactly.
187
+ - Intended as a **pre-processing step** before full-field smoothing.
188
+ - `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.
189
+
190
+ See the Quick Start section above for usage examples.
191
+
192
+ ## Documentation
193
+
194
+ - `docs/MATHEMATICAL_BASIS.md` — Mathematical foundations and theory
195
+ - `docs/API_REFERENCE.md` — Complete API documentation
196
+
197
+ ## License
198
+
199
+ MIT. See `LICENSE`.
@@ -0,0 +1,153 @@
1
+ # DCT-Toolkit: Convolutional Statistics
2
+
3
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ `dct_toolkit` provides DCT-based smoothing and normalized-convolution statistics for
7
+ data with gaps. The current publication-prep track is intentionally focused on the
8
+ convolution/statistics surface.
9
+
10
+ ## Current Scope (Stats-First)
11
+
12
+ - DCT-based smoothing for 1D/N-D Cartesian data.
13
+ - Per-axis Cartesian widths and kernel types, including mixed boxcar/Gaussian smoothing.
14
+ - Polar smoothing with adaptive azimuth widths and independent azimuth/range kernel types.
15
+ - Reflective boundaries via DCT and periodic azimuth boundaries via real FFT.
16
+ - Robust local statistics (`dct_mean`, `dct_variance`, `dct_std`, `dct_count`) with NaN support.
17
+
18
+ ## Installation
19
+
20
+ ### pip
21
+
22
+ ```bash
23
+ pip install dct-toolkit
24
+ ```
25
+
26
+ ### conda (pending conda-forge approval)
27
+
28
+ Conda-forge packaging has been submitted (PR under review). This option would be available soon:
29
+
30
+ ```bash
31
+ conda install dct-toolkit
32
+ ```
33
+
34
+ ## Quick Start
35
+
36
+ ### 1) Robust Mean with Missing Data
37
+
38
+ ```python
39
+ import numpy as np
40
+ import dct_toolkit as dct
41
+
42
+ data = np.sin(np.linspace(0, 10, 200))
43
+ data[70:110] = np.nan
44
+
45
+ mu = dct.dct_mean(data, width=10.0)
46
+ ```
47
+
48
+ ### 1b) Prefill Before Full-Field Smoothing
49
+
50
+ ```python
51
+ smoothed = dct.dct_smooth(prefilled, width=10.0)
52
+ ```
53
+ This function will call `dct.dct_prefill()` internally. We need to fill NaNs as requirement for DCT or FFT operations by default.
54
+
55
+ ### 2) Polar Smoothing with Periodic Azimuth
56
+
57
+ For data in **(azimuth, range)** order, combine a boxcar along azimuth with a
58
+ Gaussian along range:
59
+
60
+ ```python
61
+ smoothed = dct.dct_smooth(
62
+ radar_data,
63
+ width=(5.0, 3.0),
64
+ coordinates="polar",
65
+ kernel_type=("boxcar", "gaussian"),
66
+ az_boundary="periodic",
67
+ az_res_deg=1.0,
68
+ )
69
+ ```
70
+
71
+ Both sequences follow `(azimuth, range)` order. Azimuth width adapts with range:
72
+ `width_azimuth / (r * dtheta)` beams, where `r` starts at 1 and `dtheta` is the
73
+ azimuth spacing in radians. Range width is in range gates. Gaussian
74
+ `sigma = effective_width / sqrt(12)` on the selected axis. Filtering applies
75
+ azimuth first, then range; both periodic and reflective azimuth support all
76
+ three kernel types, including `'boxcar_discrete'`.
77
+ `az_res_deg` must be a finite, positive scalar in degrees. For gapped data,
78
+ periodic azimuth also wraps the nearest-neighbor prefill fallback across the
79
+ sweep seam; range distances remain nonperiodic.
80
+
81
+ ### 3) Local Variability Estimates
82
+
83
+ ```python
84
+ var = dct.dct_variance(data, width=10.0)
85
+ std = dct.dct_std(data, width=10.0)
86
+ ```
87
+
88
+ ### 4) Mixed Kernels for a 3D Volume
89
+
90
+ For a volume stored in **(z, y, x)** order, apply Gaussian smoothing vertically
91
+ and boxcar smoothing horizontally:
92
+
93
+ ```python
94
+ rng = np.random.default_rng(42)
95
+ volume = rng.standard_normal((16, 32, 32)) # (z, y, x)
96
+
97
+ smoothed = dct.dct_smooth(
98
+ volume,
99
+ width=(3.0, 5.0, 5.0),
100
+ kernel_type=("gaussian", "boxcar", "boxcar"),
101
+ )
102
+
103
+ # The same kernels work with normalized statistics on data containing NaNs.
104
+ volume[5:7, 12:15, 12:15] = np.nan
105
+ mean = dct.dct_mean(
106
+ volume,
107
+ width=(3.0, 5.0, 5.0),
108
+ kernel_type=("gaussian", "boxcar", "boxcar"),
109
+ )
110
+ ```
111
+
112
+ Kernel and width sequences follow NumPy axis order and must have one entry per
113
+ dimension. Widths are in grid cells along each axis; Gaussian
114
+ `sigma = width / sqrt(12)`. Convert physical widths using the corresponding
115
+ grid spacing before calling. A scalar width applies equal widths, and a single
116
+ kernel string applies that kernel to every axis. Equal widths with different
117
+ kernel types can still produce anisotropic smoothing. Polar smoothing also
118
+ accepts a kernel pair, using the `(azimuth, range)` convention shown above.
119
+
120
+ ## Quick Cheat Sheet
121
+
122
+ | Function | Description |
123
+ |----------|-------------|
124
+ | `get_dct_transfer_function` | Build 1D spectral kernel `H[k]` from width and kernel type. |
125
+ | `dct_convolve_1d` | Apply one 1D DCT convolution along one axis using a precomputed `H`. |
126
+ | `smooth_cartesian` | Low-level separable smoothing for N-D Cartesian arrays. |
127
+ | `smooth_polar` | Low-level smoothing for 2D polar arrays with adaptive azimuth width. |
128
+ | `dct_smooth` | Top-level "just smooth this" wrapper (auto-pre-fills NaNs, then restores NaN mask). |
129
+ | `dct_mean` | NaN-robust local mean via normalized convolution. |
130
+ | `dct_count` | Effective local sample count from a validity mask. |
131
+ | `dct_prefill` | Iterative normalized-convolution gap fill (often used before full-field smoothing). |
132
+ | `dct_variance` | NaN-robust local variance from normalized-convolution moments. |
133
+ | `dct_std` | NaN-robust local standard deviation (`sqrt(dct_variance)`). |
134
+
135
+ ## Pre-filling (`dct_prefill`)
136
+
137
+ `dct_prefill` provides an **iterative normalized-convolution gap fill** based on `dct_mean`:
138
+
139
+ - Fills gaps (NaNs or a specified mask) using iterative local averaging.
140
+ - Preserves non-target values exactly.
141
+ - Intended as a **pre-processing step** before full-field smoothing.
142
+ - `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.
143
+
144
+ See the Quick Start section above for usage examples.
145
+
146
+ ## Documentation
147
+
148
+ - `docs/MATHEMATICAL_BASIS.md` — Mathematical foundations and theory
149
+ - `docs/API_REFERENCE.md` — Complete API documentation
150
+
151
+ ## License
152
+
153
+ MIT. See `LICENSE`.
@@ -11,10 +11,10 @@ import numpy as np
11
11
  from .core import dct_convolve_1d, get_dct_transfer_function
12
12
  from ._widths import WidthLike
13
13
  from .cartesian import smooth_cartesian
14
- from .polar import smooth_polar
14
+ from .polar import _azimuth_spacing_radians, smooth_polar
15
15
  from .stats import dct_count, dct_mean, dct_prefill, dct_std, dct_variance
16
16
 
17
- __version__ = "0.5.0"
17
+ __version__ = "0.6.0"
18
18
 
19
19
 
20
20
  __all__ = [
@@ -47,8 +47,9 @@ def dct_smooth(
47
47
  data : np.ndarray
48
48
  Input data.
49
49
  width : float or sequence of float
50
- Smoothing width. Scalar input keeps isotropic behavior. Sequence
51
- input allows anisotropic widths.
50
+ Smoothing width. A scalar applies the same width to every axis.
51
+ A sequence allows per-axis widths. Cartesian widths are in grid cells
52
+ and follow array axis order; Gaussian ``sigma = width / sqrt(12)``.
52
53
  coordinates : str, default='cartesian'
53
54
  'cartesian' or 'polar'.
54
55
  prefill_max_iter : int or None, default=3
@@ -56,7 +57,13 @@ def dct_smooth(
56
57
  contains NaNs. If None, prefill iterates until convergence or a
57
58
  safety cap of 20 iterations.
58
59
  **kwargs
59
- Additional arguments (kernel_type, az_res_deg, etc.)
60
+ Additional arguments (kernel_type, az_res_deg, etc.). For Cartesian
61
+ data, ``kernel_type`` accepts a string or a sequence of supported
62
+ kernel names with length ``data.ndim``, in array axis order.
63
+ Polar data accepts a string or ``(kernel_azimuth, kernel_range)`` pair.
64
+ Polar ``az_res_deg`` must be a finite, positive real scalar.
65
+ The same kernels are used for prefill and final smoothing.
66
+ The default is 'gaussian'.
60
67
 
61
68
  Returns
62
69
  -------
@@ -65,6 +72,8 @@ def dct_smooth(
65
72
  """
66
73
  data_array = np.asarray(data)
67
74
  nan_mask = np.isnan(data_array)
75
+ if coordinates == "polar":
76
+ _azimuth_spacing_radians(kwargs.get("az_res_deg", 1.0))
68
77
 
69
78
  # Support legacy alias in wrapper calls.
70
79
  if "max_iter" in kwargs:
@@ -0,0 +1,31 @@
1
+ """Internal helpers for per-axis kernel selection."""
2
+
3
+ from typing import Sequence, Tuple, Union
4
+
5
+ import numpy as np
6
+
7
+
8
+ KernelLike = Union[str, Sequence[str], np.ndarray]
9
+
10
+
11
+ def normalize_kernel_types(kernel_type: KernelLike, ndim: int) -> Tuple[str, ...]:
12
+ """Validate kernel names and expand a single name to every axis."""
13
+ if isinstance(kernel_type, str):
14
+ kernels = (kernel_type,) * ndim
15
+ else:
16
+ values = np.asarray(kernel_type, dtype=object)
17
+ if values.ndim != 1:
18
+ raise ValueError("kernel_type must be a string or 1-D sequence of strings")
19
+ if values.size != ndim:
20
+ raise ValueError(
21
+ f"kernel_type must be a string or length-{ndim} sequence, "
22
+ f"got length {values.size}"
23
+ )
24
+ kernels = tuple(values.tolist())
25
+
26
+ for axis, kernel in enumerate(kernels):
27
+ if not isinstance(kernel, str):
28
+ raise ValueError(f"kernel_type entries must be strings, got {kernel!r} at axis {axis}")
29
+ if kernel not in ("boxcar", "boxcar_discrete", "gaussian"):
30
+ raise ValueError(f"Unknown kernel type: {kernel!r} at axis {axis}")
31
+ return kernels
@@ -0,0 +1,87 @@
1
+ """
2
+ N-D Cartesian Smoothing.
3
+
4
+ This module provides separable smoothing for N-D Cartesian data.
5
+ It applies a separable N-D transfer function in the DCT domain.
6
+ """
7
+
8
+ import numpy as np
9
+ import scipy.fft
10
+
11
+ from ._kernels import KernelLike, normalize_kernel_types
12
+ from ._widths import WidthLike, normalize_widths
13
+ from .core import get_dct_transfer_function
14
+
15
+
16
+ def smooth_cartesian(
17
+ data: np.ndarray,
18
+ width: WidthLike,
19
+ kernel_type: KernelLike = "gaussian",
20
+ ) -> np.ndarray:
21
+ """
22
+ Apply separable DCT smoothing to N-D Cartesian data.
23
+
24
+ The smoothing uses a single N-D forward DCT and inverse DCT. The
25
+ separable transfer function is applied by multiplying the spectrum by
26
+ one 1-D transfer function per axis using broadcasting.
27
+
28
+ Parameters
29
+ ----------
30
+ data : np.ndarray
31
+ Input data array (any dimension).
32
+ width : float or sequence of float
33
+ Smoothing width in grid cells along each axis. A scalar applies the
34
+ same width to every axis. A sequence must have length ``data.ndim``
35
+ and follows array axis order. For Gaussian kernels,
36
+ ``sigma = width / sqrt(12)`` along the corresponding axis.
37
+ kernel_type : str or sequence of str, default='gaussian'
38
+ Kernel type ('boxcar', 'boxcar_discrete', 'gaussian'). A string applies
39
+ to every axis. A sequence must have length ``data.ndim`` and selects
40
+ one kernel per axis in array order, independently of ``width``.
41
+
42
+ Returns
43
+ -------
44
+ smoothed : np.ndarray
45
+ Smoothed data with same shape as input.
46
+
47
+ Raises
48
+ ------
49
+ ValueError
50
+ If a kernel sequence is not one-dimensional, its length differs
51
+ from ``data.ndim``, or a kernel entry is not a supported string.
52
+
53
+ Notes
54
+ -----
55
+ Boundaries are reflective on every axis. Equal widths with different
56
+ kernel types can still produce anisotropic smoothing. Input should be
57
+ finite; use ``dct_mean`` or ``dct_smooth`` for data containing NaNs.
58
+
59
+ Examples
60
+ --------
61
+ Smooth a volume stored in (z, y, x) order with a Gaussian along z and
62
+ boxcars along y and x:
63
+
64
+ >>> volume = np.ones((8, 16, 16))
65
+ >>> smoothed = smooth_cartesian(
66
+ ... volume, width=(3.0, 5.0, 5.0),
67
+ ... kernel_type=("gaussian", "boxcar", "boxcar"),
68
+ ... )
69
+ >>> np.allclose(smoothed, volume)
70
+ True
71
+ """
72
+ data_array = np.asarray(data)
73
+ if data_array.ndim == 0:
74
+ return data_array.copy()
75
+
76
+ widths = normalize_widths(width, data_array.ndim, name="width")
77
+ kernels = normalize_kernel_types(kernel_type, data_array.ndim)
78
+
79
+ spectrum = scipy.fft.dctn(data_array, type=2, norm="ortho")
80
+
81
+ for axis, (n, width_axis, kernel_axis) in enumerate(zip(data_array.shape, widths, kernels)):
82
+ H = get_dct_transfer_function(n, kernel_axis, float(width_axis))
83
+ transfer_shape = [1] * data_array.ndim
84
+ transfer_shape[axis] = n
85
+ spectrum *= H.reshape(transfer_shape)
86
+
87
+ return scipy.fft.idctn(spectrum, type=2, norm="ortho")