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

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

@@ -40,6 +40,7 @@ Thumbs.db
 # Jupyter
 .ipynb_checkpoints/
 *.ipynb
+!notebooks/*.ipynb
 
 # Environment
 .env

{dct_toolkit-0.4.0 → dct_toolkit-0.5.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.5.0  
+**Status**: Published — PyPI live, conda-forge PR under review  
+**Last Updated**: 2026-04-14
 
 ---
 
@@ -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.4.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.5.0` — N-D Cartesian smoothing backend upgrade (`dctn/idctn`) with
+  validated 3D/4D parity and stats compatibility.
+- Tag: `git checkout v0.5.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.5.0}/CHANGELOG.md

@@ -7,25 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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).
+
+### Added
+- Added parity and artifact-regression tests for scalar-vs-vector isotropic widths,
+  plus anisotropic Cartesian/polar smoke coverage.
+
+## [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.4.0 → dct_toolkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dct-toolkit
-Version: 0.4.0
+Version: 0.5.0
 Summary: DCT/FFT-based convolutional statistics for Cartesian and polar data
 Author-email: "Jairo M. Valdivia" <Jairo.ValdiviaPrado@colorado.edu>
 License: MIT License

dct_toolkit-0.5.0/dct_toolkit/__init__.py

@@ -0,0 +1,100 @@
+"""Public API for DCT-based convolution and statistical operations.
+
+The public top-level surface is intentionally scoped to smoothing and
+normalized-convolution statistics for the publication-focused release track.
+"""
+
+from typing import Any, Optional
+
+import numpy as np
+
+from .core import dct_convolve_1d, get_dct_transfer_function
+from ._widths import WidthLike
+from .cartesian import smooth_cartesian
+from .polar import smooth_polar
+from .stats import dct_count, dct_mean, dct_prefill, dct_std, dct_variance
+
+__version__ = "0.5.0"
+
+
+__all__ = [
+    "__version__",
+    "get_dct_transfer_function",
+    "dct_convolve_1d",
+    "smooth_cartesian",
+    "smooth_polar",
+    "dct_smooth",
+    "dct_count",
+    "dct_mean",
+    "dct_prefill",
+    "dct_variance",
+    "dct_std",
+]
+
+
+def dct_smooth(
+    data: np.ndarray,
+    width: WidthLike,
+    coordinates: str = "cartesian",
+    prefill_max_iter: Optional[int] = 3,
+    **kwargs: Any,
+) -> np.ndarray:
+    """
+    Apply DCT-based smoothing.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data.
+    width : float or sequence of float
+        Smoothing width. Scalar input keeps isotropic behavior. Sequence
+        input allows anisotropic widths.
+    coordinates : str, default='cartesian'
+        'cartesian' or 'polar'.
+    prefill_max_iter : int or None, default=3
+        Number of normalized-convolution prefill iterations used when input
+        contains NaNs. If None, prefill iterates until convergence or a
+        safety cap of 20 iterations.
+    **kwargs
+        Additional arguments (kernel_type, az_res_deg, etc.)
+
+    Returns
+    -------
+    smoothed : np.ndarray
+        Smoothed data.
+    """
+    data_array = np.asarray(data)
+    nan_mask = np.isnan(data_array)
+
+    # Support legacy alias in wrapper calls.
+    if "max_iter" in kwargs:
+        prefill_max_iter = kwargs.pop("max_iter")
+
+    if not np.any(nan_mask):
+        if coordinates == "cartesian":
+            return smooth_cartesian(data_array, width, **kwargs)
+        if coordinates == "polar":
+            return smooth_polar(data_array, width_pixels=width, **kwargs)
+        raise ValueError(f"Unknown coordinates: {coordinates}")
+
+    # No support exists to estimate an all-NaN field; preserve mask semantics.
+    if np.all(nan_mask):
+        return np.full(data_array.shape, np.nan, dtype=np.float64)
+
+    filled = dct_prefill(
+        data_array,
+        width=width,
+        coordinates=coordinates,
+        max_iter=prefill_max_iter,
+        **kwargs,
+    )
+
+    if coordinates == "cartesian":
+        smoothed = smooth_cartesian(filled, width, **kwargs)
+    elif coordinates == "polar":
+        smoothed = smooth_polar(filled, width_pixels=width, **kwargs)
+    else:
+        raise ValueError(f"Unknown coordinates: {coordinates}")
+
+    smoothed[nan_mask] = np.nan
+    return smoothed

dct_toolkit-0.5.0/dct_toolkit/_widths.py

@@ -0,0 +1,34 @@
+"""Internal helpers for isotropic/anisotropic width handling."""
+
+from typing import Sequence, Union
+
+import numpy as np
+
+
+WidthLike = Union[float, Sequence[float], np.ndarray]
+
+
+def normalize_widths(width: WidthLike, ndim: int, name: str = "width") -> np.ndarray:
+    """Normalize scalar/sequence width input to a positive 1-D array."""
+    if ndim < 0:
+        raise ValueError(f"ndim must be >= 0, got {ndim}")
+
+    values = np.asarray(width, dtype=float)
+
+    if values.ndim == 0:
+        widths = np.full(ndim, float(values), dtype=float)
+    elif values.ndim == 1:
+        if values.size != ndim:
+            raise ValueError(
+                f"{name} must be a scalar or length-{ndim} sequence, got length {values.size}"
+            )
+        widths = values.astype(float, copy=False)
+    else:
+        raise ValueError(f"{name} must be a scalar or 1-D sequence")
+
+    if not np.all(np.isfinite(widths)):
+        raise ValueError(f"{name} must contain only finite values")
+    if np.any(widths <= 0):
+        raise ValueError(f"{name} must be > 0")
+
+    return widths

dct_toolkit-0.5.0/dct_toolkit/cartesian.py

@@ -0,0 +1,56 @@
+"""
+N-D Cartesian Smoothing.
+
+This module provides separable smoothing for N-D Cartesian data.
+It applies a separable N-D transfer function in the DCT domain.
+"""
+
+import numpy as np
+import scipy.fft
+
+from .core import get_dct_transfer_function
+from ._widths import WidthLike, normalize_widths
+
+
+def smooth_cartesian(
+    data: np.ndarray,
+    width: WidthLike,
+    kernel_type: str = "gaussian",
+) -> np.ndarray:
+    """
+    Apply separable DCT smoothing to N-D Cartesian data.
+
+    The smoothing uses a single N-D forward DCT and inverse DCT. The
+    separable transfer function is applied by multiplying the spectrum by
+    one 1-D transfer function per axis using broadcasting.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data array (any dimension).
+    width : float or sequence of float
+        Smoothing width. Scalar input applies isotropic smoothing. Sequence
+        input must have length ``data.ndim`` and applies per-axis widths.
+    kernel_type : str, default='gaussian'
+        Kernel type ('boxcar', 'boxcar_discrete', 'gaussian').
+
+    Returns
+    -------
+    smoothed : np.ndarray
+        Smoothed data with same shape as input.
+    """
+    data_array = np.asarray(data)
+    if data_array.ndim == 0:
+        return data_array.copy()
+
+    widths = normalize_widths(width, data_array.ndim, name="width")
+
+    spectrum = scipy.fft.dctn(data_array, type=2, norm="ortho")
+
+    for axis, (n, width_axis) in enumerate(zip(data_array.shape, widths)):
+        H = get_dct_transfer_function(n, kernel_type, float(width_axis))
+        transfer_shape = [1] * data_array.ndim
+        transfer_shape[axis] = n
+        spectrum *= H.reshape(transfer_shape)
+
+    return scipy.fft.idctn(spectrum, type=2, norm="ortho")