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

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

@@ -1,9 +1,11 @@
 # AGENTS.md - DCT Toolkit Agent Guidelines
 
 **Project**: dct-toolkit  
-**Version**: 0.6.0  
-**Status**: Preparing v0.6.0 release (PyPI & conda-forge)  
-**Last Updated**: 2026-09-21
+**Version**: 2.0.0
+
+**Status**: Full sampled Gaussian statistics release track
+
+**Last Updated**: 2026-11-11
 
 ---
 
@@ -45,7 +47,16 @@ conda activate dct-publish
 - xarray, matplotlib, cmweather (radar colormaps)
 - open-radar-data (sample radar datasets)
 - build, twine (for PyPI publishing)
-- dct-toolkit v0.5.0 (editable install)
+- dct-toolkit editable install (verify the runtime and installed-distribution versions)
+
+After changing the package version, refresh editable installation metadata:
+
+```bash
+conda run -n dct-publish python -m pip install --no-deps -e .
+conda run -n dct-publish python -c 'from importlib.metadata import version; import dct_toolkit as dct; assert dct.__version__ == version("dct-toolkit")'
+```
+
+An editable source import alone does not update installed distribution metadata.
 
 ### PYTHONPATH
 When running tests or examples from project root:
@@ -158,8 +169,9 @@ dct_toolkit/                    # PROJECT ROOT
 ├── dct_toolkit/               # INSTALLABLE PACKAGE ⚠️ CODE GOES HERE
 │   ├── __init__.py           # Public API exports
 │   ├── core.py               # Transfer functions & 1D primitives
-│   ├── cartesian.py          # 2D Cartesian separable smoothing
-│   ├── polar.py              # 2D Polar smoothing (adaptive kernels)
+│   ├── cartesian.py          # N-D Cartesian separable smoothing
+│   ├── polar.py              # Legacy 2D and explicit geometry-aware N-D smoothing
+│   ├── _geometry.py          # Shared axis/coordinate/width validation and support
 │   ├── stats.py              # Statistical ops (Normalized Convolution)
 │   └── gap_filling.py         # Gap-filling methods (deferred for public stats-first release)
 │
@@ -189,7 +201,7 @@ dct_toolkit/                    # PROJECT ROOT
 ├── docs/                      # DOCUMENTATION
 │   ├── API_REFERENCE.md
 │   ├── MATHEMATICAL_BASIS.md
-│   └── GAP_FILLING_BASIS.md
+│   └── RELEASING.md          # Local build, artifact checks, and publication handoff
 │
 ├── README.md                  # Main documentation
 ├── CHANGELOG.md               # Version history
@@ -215,7 +227,8 @@ dct_toolkit/                    # PROJECT ROOT
 
 3. **Review Documentation**
    - Check `docs/MATHEMATICAL_BASIS.md` for theory
-   - Check `docs/GAP_FILLING_BASIS.md` for gap filling theory
+   - Gap filling outside the exported statistics API remains research-internal;
+     inspect `dct_toolkit/gap_filling.py` only when that scope is requested
    - Check `docs/API_REFERENCE.md` for existing API
 
 ### Making Changes
@@ -245,6 +258,10 @@ python -m pytest /path/to/dct_toolkit/tests/ -v
 
 **Expected Output**: all tests passing
 
+CI additionally runs the installed package outside the checkout, checks runtime
+and distribution versions agree, and exercises the N-D example. Its minimum
+dependency job uses Python 3.8, NumPy 1.20.0, and SciPy 1.8.0.
+
 **If Tests Fail**:
 - Fix the code, not the tests
 - Tests represent ground truth requirements
@@ -302,8 +319,19 @@ Before declaring task complete:
 - [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)
+### v1.0.0 Development Scope
+
+- Geometry-aware N-D polar arrays with selectable azimuth, elevation, range,
+  time, linear, and batch roles in arbitrary array order.
+- Per-axis kernels, boundaries, grid/physical width units, and filtering selection.
+- Complete propagation through normalized moments, support, prefill, and fallback.
+- Unfiltered axes remain isolated domains, including all-missing batches.
+- Keep existing 2D calls compatible; explicit physical-coordinate mode is opt-in.
+- New public APIs need independent numerical tests and an independent code/docs review.
+- Do not modify manuscripts or review trackers as part of this software task.
+
+### Future Beyond v2.0.0
+
 - [ ] Additional kernels (Savitzky-Golay, Hanning)
 - [ ] Performance optimizations (numba?)
 - [ ] Jupyter notebook examples
@@ -317,17 +345,31 @@ Before declaring task complete:
 ### Transfer Functions
 - **Boxcar (Analytical)**: `H[k] = sin(W·θ)/(W·sin(θ))`, θ = πk/(2n)
 - **Boxcar (Discrete)**: Sum of cosines for discrete kernels
-- **Gaussian**: `H[k] = exp(-0.5·(ω·σ)²)`, σ = width/√12
+- **Gaussian (default)**: full normalized sampled Gaussian, σ = width/√12;
+  evaluate its cosine sum or equivalent frequency-alias sum to float64 precision.
+  No fixed spatial cutoff; nonnegative spatial weights support statistical moments.
+- **Gaussian (spectral compatibility)**: `gaussian_spectral` retains
+  `H[k] = exp(-0.5·(ω·σ)²)`, σ = width/√12; spatial weights can be signed.
 
 ### Normalized Convolution
 Formula for robust mean with gaps:
 ```
-μ = smooth(data * mask) / (smooth(mask) + ε)
+μ = smooth(zero_filled_valid_data) / smooth(valid_mask)
 ```
+Apply the complete smoothing operator to each input before normalizing once.
+The denominator must be strictly greater than the floor (default `1e-3`);
+unsupported locations use the documented selective prefill fallback. This is
+not additive-epsilon regularization. `dct_count` reports nominal weighted
+support, not statistical effective sample size.
 
 ### Polar Coordinates
-- **Data Layout**: (n_azimuth, n_range)
-- **Adaptive Width**: w_az(r) = width / (r · dθ)
+- **Legacy Data Layout**: (n_azimuth, n_range), retaining index-based width units.
+- **Explicit N-D Mode**: axis roles, coordinates, and units define the geometry.
+- **Physical Angular Widths**: azimuth scales with `1 / (r * cos(elevation) * dθ)`;
+  elevation scales with `1 / (r * dφ)`. Use actual coordinates, not gate indices.
+- **Filter Order**: azimuth, elevation, range, then independent time/linear axes;
+  this is an ordered nonstationary operator, not one global separable transform.
+- **Fallback Domains**: never borrow support across unfiltered/batch axes.
 - **Boundary Conditions**:
   - Reflective: DCT-II (even symmetry)
   - Periodic: Real FFT (circular convolution)
@@ -412,25 +454,23 @@ 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
-```
+- GitHub: **Public** — `JValdivia23/dct-toolkit`
+- PyPI: **Public** distribution channel; local version changes do not publish a release
+- conda-forge: **Approved & Merged** — Feedstock live at `conda-forge/dct-toolkit-feedstock`
 
 ### 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`
+
+- Version: `2.0.0`, using the full sampled Gaussian by default across smoothing
+  and statistics. Use `gaussian_spectral` to reproduce pre-2.0 Gaussian results.
+- Preserve the historical `v1.0.0`, `v0.6.0`, and older release records.
+- Do not tag, push, upload to PyPI/conda-forge, or create a public archival record
+  without approval.
+- See `docs/RELEASING.md` for local artifact verification and release handoff.
 
 ### 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
+- Full gap-filling to be released in a future version after research matures
 
 ---
 

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

@@ -5,6 +5,115 @@ 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]
+
+## [2.0.0] - 2026-11-11
+
+Major release changing the default Gaussian's numerical definition. Existing
+calls remain accepted, but Gaussian outputs change. For reproducible pre-2.0
+results, explicitly select `'gaussian_spectral'` wherever Gaussian filtering was
+previously used, including each Gaussian entry in hybrid kernel sequences.
+Widths, coordinate conventions, and the public function signatures are unchanged.
+
+### Breaking Changes
+- Redefine `'gaussian'`, the default kernel, as the full normalized sampled
+  Gaussian rather than the exponential spectral response used in v1.0.0.
+  This affects existing smoothing/statistics calls even when `kernel_type`
+  is omitted. Use `'gaussian_spectral'` to retain the previous response.
+
+### Changed
+- Make the default `'gaussian'` kernel the full normalized sampled Gaussian,
+  evaluated to floating-point precision without a fixed spatial truncation.
+  Cartesian, legacy polar, explicit N-D polar, both boundaries, normalized
+  moments, prefill, and fallback now share this nonnegative spatial kernel.
+  Numerical results change, particularly for widths near or below one grid cell.
+- Preserve the previous exponential response as `'gaussian_spectral'` for
+  reproducing v1.0.0 Gaussian results, including per-axis hybrid selections.
+  Its spatial weights can be signed; it is not the default for statistics.
+
+### Fixed
+- Remove substantive negative raw variances caused by Gaussian spatial ringing.
+  The final variance clamp remains for floating-point cancellation. Positivity
+  requires nonnegative kernels on every selected axis; fractional analytical
+  boxcars and `'gaussian_spectral'` do not provide that guarantee.
+- Evaluate broad sampled Gaussians with an equivalent frequency-alias sum,
+  avoiding allocations proportional to potentially enormous effective widths.
+
+### Documentation
+- Document sampled Gaussian normalization, numerical evaluation, narrow-width
+  behavior, statistical guarantees, and migration to `'gaussian_spectral'`.
+- Clarify required N-D polar metadata, the default physical width units, and
+  coordinate dependencies; add a runnable coordinate-free grid-width example.
+- Compare Cartesian and explicit polar N-D processing, including boundaries,
+  axis selection, and the conditions for equivalent finite-data smoothing.
+- Explain input-NaN restoration and the low-level polar width argument in the README.
+
+## [1.0.0] - 2026-10-26
+
+Geometry-aware N-D polar release, preserving the v0.6.0 legacy 2D interface.
+
+### Added
+- Explicit N-D polar geometry through keyword-only `axis_types`, `axis_coords`,
+  `boundary`, `width_units`, `angle_units`, and `filter_axes` in `smooth_polar`,
+  forwarded by the smoothing wrapper and statistics with `coordinates='polar'`.
+- Named azimuth/elevation/range axes in arbitrary array order, plus time, linear
+  (`cartesian` alias), and independent batch axes; per-axis widths, kernels,
+  boundaries, and physical/grid units follow array order.
+- Physical angular widths use actual range and elevation geometry:
+  `L_az / (R*cos(elevation)*delta_az)` and `L_el / (R*delta_el)` in grid cells.
+  Regular coordinate validation rejects singular origins/poles and incomplete
+  non-singleton physical periodic azimuth grids rather than capping widths.
+- Synthetic, plotting-free `examples/nd_polar.py` demonstrates a
+  `(time, elevation, azimuth, range)` field, missing data, mixed kernels/boundaries,
+  axis permutation, and isolation of unfiltered time slices.
+
+### Changed
+- Explicit geometry uses canonical azimuth/elevation/range/time/linear filter
+  order independently of array storage order. The generally nonseparable,
+  noncommuting operator is not an exact isotropic or cell-volume convolution.
+- Batch and unfiltered dimensions remain independent through smoothing,
+  normalized statistics, iterative filling, and every fallback. They do not
+  contribute nominal support area; wholly missing independent domains stay NaN.
+- Documented `dct_count` as nominal weighted support, distinct from literal
+  neighbor counts and squared-weight statistical ESS, including repeated samples
+  at reflective/periodic boundaries.
+
+### Documentation corrections
+- Removed the additive-epsilon description: the normal public mean ratio uses
+  the full operator once on data and mask and requires a denominator strictly
+  greater than `1e-3`. Variance estimates both moments independently, including
+  separate fallback prefills of `x` and `x**2`, then clamps negative results.
+- Qualified nonnegative-weight statistical guarantees: arbitrary fractional
+  spectral kernels need not have nonnegative spatial weights.
+- Replaced the broken mathematical-guide link to the removed gap-filling basis
+  with research-internal module documentation, without adding a public export.
+
+### Fixed
+- Validate integer coordinate spacing before floating-point conversion, including
+  large time origins and overflow-safe signed/unsigned integer differences.
+- Promote low-precision floating coordinates before spacing validation, avoiding
+  subtraction overflow and concealed irregular grids without downcasting wider types.
+- Compute nominal support lazily with exponent scaling. An unrepresentable count
+  factor no longer prevents valid smoothing or normalized-moment computations;
+  individual effective widths remain validated.
+- Remove array-layout bias from repeated time/linear-role fallback through joint
+  mixed-boundary nearest completion and symmetric averaging of exact global ties.
+  Legacy 2D axis-wise tie rules remain unchanged.
+- Preserve zero-dimensional array outputs during count, variance, and standard
+  deviation mask restoration, consistently with smoothing and mean operations.
+- Check installed runtime/distribution version alignment and run the suite against
+  the installed package in CI, including Python 3.8 with NumPy 1.20.0/SciPy 1.8.0.
+- Document editable metadata refresh and the coordinated PyPI/conda-forge release
+  process, including checksums of the exact published source archive.
+
+### Compatibility
+- Existing `smooth_polar` positional arguments, the `width_pixels` name, and
+  positional `width` in high-level functions are unchanged.
+- `axis_types=None` preserves the legacy 2D `(azimuth, range)` path, index-based
+  range convention, scalar/pair widths and kernels, and existing boundary rules.
+  Nondefault new geometry options require explicit `axis_types`; old widths are
+  not silently reinterpreted as physical distances.
+
 ## [0.6.0] - 2026-09-21
 
 ### Changed