Metadata-Version: 2.4
Name: qabba
Version: 0.2.0
Summary: Quantized ABBA for symbolic time-series representation and compression
Author: QABBA contributors
License: MIT License
        
        Copyright (c) 2026 QABBA contributors
        
        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.
        
        
Project-URL: Homepage, https://github.com/chenxinye/qabba_code
Project-URL: Documentation, https://qabba.readthedocs.io/
Project-URL: Repository, https://github.com/chenxinye/qabba_code
Project-URL: Issues, https://github.com/chenxinye/qabba_code/issues
Keywords: time series,compression,symbolic representation,quantization,ABBA
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.1
Requires-Dist: numpy>=1.22
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.8
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.6; extra == "plot"
Provides-Extra: zstd
Requires-Dist: zstandard>=0.22; extra == "zstd"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: qabba[docs,plot,zstd]; extra == "dev"
Dynamic: license-file

# QABBA

[![PyPI](https://img.shields.io/pypi/v/qabba.svg)](https://pypi.org/project/qabba/)
[![CI](https://github.com/chenxinye/qabba_code/actions/workflows/ci.yml/badge.svg)](https://github.com/chenxinye/qabba_code/actions/workflows/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/qabba/badge/?version=latest)](https://qabba.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

QABBA is a production-oriented Python package for **Quantized ABBA**, a symbolic time-series representation that combines adaptive piecewise-linear approximation, symbolic digitization, low-bitwidth center quantization, and optional lossless symbol-layer coding.

The package turns long numerical time series into compact symbolic sequences with quantized reconstruction parameters. This is useful when storage, transmission, and downstream symbolic analysis matter: edge sensing, long time-series archives, approximate reconstruction, motif-oriented mining, and LLM-facing time-series tokenization.

## Features

- **Compact symbolic representations**: convert dense float time series into adaptive symbol sequences and a small table of quantized centers.
- **Storage-aware by design**: inspect total bits, storage ratio, compression factor, and symbol-layer storage with a unified API.
- **Optional lossless symbol codecs**: choose `none`, `fixed`, `huffman`, `lzw`, `zlib`, `gzip`, `bz2`, `lzma`, or optional `zstd` for second-stage symbol coding.
- **Scikit-learn style API**: use familiar `fit`, `transform`, `fit_transform`, `inverse_transform`, `get_params`, and `set_params`.
- **Cython acceleration with fallback**: build fast kernels when Cython and a compiler are available; otherwise use pure Python implementations.
- **Research-to-software bridge**: package APIs follow the paper methodology while keeping experimental scripts separate under `exps`.

## Installation

Install the released package:

```bash
pip install qabba
```

Install optional extras:

```bash
pip install "qabba[plot,zstd]"
```

Install from source for development:

```bash
git clone https://github.com/chenxinye/qabba_code.git
cd qabba_code
pip install -e ".[dev]"
```

To force the pure Python kernels:

```bash
QABBA_DISABLE_CYTHON=1 pip install -e .
```

## Quick Start

```python
import numpy as np
from qabba import QABBA, mean_squared_error

x = np.sin(np.linspace(0, 8 * np.pi, 512))

model = QABBA(
    tol=0.05,
    alpha=0.4,
    bits_for_len=8,
    bits_for_inc=12,
    symbol_codec="fixed",
)

symbols = model.fit_transform(x)
x_hat = model.inverse_transform(symbols)

print("first symbols:", "".join(symbols[:20]))
print("storage ratio:", model.storage_.storage_ratio)
print("compression factor:", model.storage_.compression_factor)
print("MSE:", mean_squared_error(x, x_hat))
```

## Common Workflows

### 1. Fit, Encode, and Reconstruct

```python
model = QABBA(tol=0.05, alpha=0.5)
symbols = model.fit_transform(x)
x_hat = model.inverse_transform(symbols)
```

### 2. Compare Symbol Codecs

```python
model = QABBA(tol=0.05, alpha=0.5).fit(x)

for codec in ["none", "fixed", "lzw", "huffman"]:
    stats = model.encode_symbols(codec=codec)
    print(codec, stats.total_bits, stats.bits_per_symbol)
```

The symbol codec is lossless with respect to the symbolic sequence; it changes storage accounting, not reconstruction error.

### 3. Batch Multiple Time Series

```python
X = np.vstack([
    np.sin(np.linspace(0, 6 * np.pi, 256)),
    np.cos(np.linspace(0, 6 * np.pi, 256)),
])

model = QABBA(tol=0.05, alpha=0.5, n_jobs=2)
symbols = model.fit_transform(X)
reconstructions = model.inverse_transform(symbols)
```

Rows of a two-dimensional array are treated as independent univariate time series that share one learned symbolic codebook.

### 4. Inspect Storage

```python
storage = model.storage_

print(storage.total_bits)
print(storage.symbol_bits)
print(storage.center_bits)
print(storage.storage_ratio)
print(storage.compression_factor)
```

## Applications

QABBA is designed for workflows where a time series should be both compact and semantically usable after compression.

- **Edge and IoT sensing**: transmit symbolic sequences and quantized centers instead of dense float streams.
- **Scientific monitoring**: archive long signals while preserving trend and shape information for approximate reconstruction.
- **Symbolic time-series mining**: feed downstream algorithms for motifs, anomaly screening, clustering, and pattern matching.
- **LLM-oriented time-series processing**: expose adaptive symbolic sequences as text-like inputs for language-model pipelines.
- **Compression research**: compare rate-distortion behavior against classical dimensionality reduction and lossy scientific compressors.

QABBA is not intended to replace strict error-bounded floating-point compressors when every value must be recovered under a prescribed absolute or relative error bound. It is strongest when very compact symbolic structure is valuable.

## Documentation

The ReadTheDocs source lives in `docs/source`. Build it locally with:

```bash
cd docs
make html
```

The documentation includes installation, quick start, examples, applications, mathematical formulation, API reference, and license pages.

## Development

Run the test suite:

```bash
pytest
```

Build a wheel without dependencies:

```bash
python -m pip wheel . -w dist --no-deps
```

Build the documentation:

```bash
cd docs
make clean
make html
```

## Continuous Integration

The GitHub Actions workflow in `.github/workflows/ci.yml` runs on pull requests and pushes to `master`. It checks:

- package import and API tests on Python 3.9, 3.10, 3.11, and 3.12;
- source distribution and wheel builds;
- Sphinx documentation builds with `make html`.

### Cite

```bibtex
@misc{carson2025quantizedsymbolictimeseries,
      title={Quantized symbolic time series approximation}, 
      author={Erin Carson and Xinye Chen and Fei He and Cheng Kang},
      year={2026},
      eprint={2411.15209},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2411.15209}, 
}
```

## License

QABBA is released under the MIT License. See [LICENSE](LICENSE).
