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.
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/.gitignore +5 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/AGENTS.md +7 -7
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/CHANGELOG.md +42 -1
- dct_toolkit-0.6.0/PKG-INFO +199 -0
- dct_toolkit-0.6.0/README.md +153 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/__init__.py +14 -5
- dct_toolkit-0.6.0/dct_toolkit/_kernels.py +31 -0
- dct_toolkit-0.6.0/dct_toolkit/cartesian.py +87 -0
- dct_toolkit-0.6.0/dct_toolkit/polar.py +295 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/stats.py +181 -41
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/docs/API_REFERENCE.md +139 -13
- dct_toolkit-0.6.0/docs/MATHEMATICAL_BASIS.md +178 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/pyproject.toml +2 -2
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_api.py +28 -0
- dct_toolkit-0.6.0/tests/test_cartesian.py +195 -0
- dct_toolkit-0.6.0/tests/test_polar_kernels.py +244 -0
- dct_toolkit-0.6.0/tests/test_polar_robustness.py +157 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_stats.py +214 -0
- dct_toolkit-0.6.0/tests/test_stats_nd.py +116 -0
- dct_toolkit-0.5.0/PKG-INFO +0 -161
- dct_toolkit-0.5.0/README.md +0 -115
- dct_toolkit-0.5.0/dct_toolkit/cartesian.py +0 -56
- dct_toolkit-0.5.0/dct_toolkit/polar.py +0 -275
- dct_toolkit-0.5.0/docs/MATHEMATICAL_BASIS.md +0 -77
- dct_toolkit-0.5.0/tests/test_cartesian.py +0 -104
- dct_toolkit-0.5.0/tests/test_stats_nd.py +0 -37
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/LICENSE +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/_widths.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/core.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/dct_toolkit/gap_filling.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/examples/basic_polar.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/examples/comprehensive_demo.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_core.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_gap_filling.py +0 -0
- {dct_toolkit-0.5.0 → dct_toolkit-0.6.0}/tests/test_polar.py +0 -0
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# AGENTS.md - DCT Toolkit Agent Guidelines
|
|
2
2
|
|
|
3
3
|
**Project**: dct-toolkit
|
|
4
|
-
**Version**: 0.
|
|
5
|
-
**Status**:
|
|
6
|
-
**Last Updated**: 2026-
|
|
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.
|
|
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.
|
|
427
|
-
|
|
428
|
-
- Tag: `git checkout v0.
|
|
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
|
-
## [
|
|
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
|
+
[](https://www.python.org/downloads/)
|
|
50
|
+
[](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
|
+
[](https://www.python.org/downloads/)
|
|
4
|
+
[](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.
|
|
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.
|
|
51
|
-
|
|
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")
|