Metadata-Version: 2.4
Name: dct-toolkit
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
        
        Copyright (c) 2026 Jairo M. Valdivia
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: convolution,dct,fft,polar,radar,smoothing,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.8
Description-Content-Type: text/markdown

# DCT-Toolkit: Convolutional Statistics

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`dct_toolkit` provides DCT-based smoothing and normalized-convolution statistics for
data with gaps. The current publication-prep track is intentionally focused on the
convolution/statistics surface.

## Current Scope (Stats-First)

- DCT-based smoothing for 1D/N-D Cartesian data.
- Polar smoothing with adaptive azimuth kernels.
- Reflective boundaries via DCT and periodic azimuth boundaries via real FFT.
- Robust local statistics (`dct_mean`, `dct_variance`, `dct_std`, `dct_count`) with NaN support.

## Installation

### pip

```bash
pip install .
```

When the package is published on PyPI, installation will be:

```bash
pip install dct-toolkit
```

### from source

```bash
git clone <your-repo-url>
cd dct_toolkit
pip install .
```

### conda (planned)

Conda-forge packaging is in preparation. Until the feedstock is published, you can install with
pip inside a conda environment.

```bash
conda create -n dct-toolkit python=3.11 -y
conda activate dct-toolkit
pip install dct-toolkit
```

## Quick Start

### 1) Robust Mean with Missing Data

```python
import numpy as np
import dct_toolkit as dct

data = np.sin(np.linspace(0, 10, 200))
data[70:110] = np.nan

mu = dct.dct_mean(data, width=10.0)
```

### 1b) Prefill Before Full-Field Smoothing

```python
prefilled = dct.dct_prefill(data, width=10.0, max_iter=3)
smoothed = dct.dct_smooth(prefilled, width=10.0)
```

### 2) Polar Smoothing with Periodic Azimuth

```python
smoothed = dct.dct_smooth(
    radar_data,
    width=5.0,
    coordinates="polar",
    az_boundary="periodic",
    az_res_deg=1.0,
)
```

### 3) Local Variability Estimates

```python
var = dct.dct_variance(data, width=10.0)
std = dct.dct_std(data, width=10.0)
```

## Public API (Top Level)

- `dct_smooth`
- `dct_count`
- `dct_mean`
- `dct_prefill`
- `dct_variance`
- `dct_std`
- `smooth_cartesian`
- `smooth_polar`
- `get_dct_transfer_function`
- `dct_convolve_1d`

## Notes on Gap Filling

Gap-filling methods remain in the repository for internal research, but they are
de-scoped from the top-level public API for the initial convolution/statistics release.

## Documentation

- `docs/MATHEMATICAL_BASIS.md`
- `docs/API_REFERENCE.md`

## License

MIT. See `LICENSE`.
