maya-encoding 0.1.0__tar.gz

maya_encoding-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+
+      - name: Run tests
+        run: |
+          pytest tests/ -v --cov=maya_encoding --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml

maya_encoding-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

maya_encoding-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+coverage.xml
+.coverage
+*.so
+.env
+.venv/
+venv/
+*.ipynb_checkpoints/
+benchmarks/results/*.json

maya_encoding-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+- `VFDEncoder`: Vigesimal Feature Decomposition for numeric features
+  - Full, lite, and bars_dots component modes
+  - Automatic level detection and scale factor inference
+  - Negative and float handling strategies
+  - sklearn pipeline compatible (fit/transform/inverse_transform)
+- `MayaCalendarEncoder`: Maya Calendar Encoding for temporal features
+  - Tzolk'in (260-day), Haab' (365-day), and Long Count components
+  - Hierarchical and flat encoding modes
+  - Optional sine/cosine cyclical encoding
+  - GMT and custom epoch support
+  - Wayeb' period detection
+- Core mathematical functions
+  - Vigesimal number system (encode/decode/decompose)
+  - Maya calendar conversions (Gregorian to Tzolk'in, Haab', Long Count)
+  - Vectorized operations with numpy
+- Visualization
+  - `plot_maya_number()`: Render numbers as Maya glyphs
+  - `render_maya_text()`: Text-based Maya numeral representation
+- Benchmark suite comparing VFD and MCE against baseline encodings
+- Full test suite with >90% coverage

maya_encoding-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to maya-encoding
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/danielregalado/maya-encoding.git
+cd maya-encoding
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+We use `ruff` for linting:
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Reporting Issues
+
+Please use GitHub Issues and include:
+- Python version
+- maya-encoding version
+- Minimal reproducible example

maya_encoding-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Regalado
+
+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.

maya_encoding-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: maya-encoding
+Version: 0.1.0
+Summary: Maya-inspired numerical encodings for machine learning: Vigesimal Feature Decomposition (VFD) and Maya Calendar Encoding (MCE)
+Project-URL: Homepage, https://github.com/danielregalado/maya-encoding
+Project-URL: Documentation, https://danielregalado.github.io/maya-encoding
+Project-URL: Repository, https://github.com/danielregalado/maya-encoding
+Project-URL: Issues, https://github.com/danielregalado/maya-encoding/issues
+Author-email: Daniel Regalado <dxr1491@miami.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,encoding,feature-engineering,machine-learning,maya,scikit-learn,time-series,vigesimal
+Classifier: Development Status :: 3 - Alpha
+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 :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.5; extra == 'all'
+Requires-Dist: mkdocs; extra == 'all'
+Requires-Dist: mkdocs-material; extra == 'all'
+Requires-Dist: mkdocstrings[python]; extra == 'all'
+Requires-Dist: mypy; extra == 'all'
+Requires-Dist: pandas>=1.3; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: scipy>=1.7; extra == 'all'
+Requires-Dist: seaborn>=0.12; extra == 'all'
+Requires-Dist: xgboost>=1.5; extra == 'all'
+Provides-Extra: benchmarks
+Requires-Dist: pandas>=1.3; extra == 'benchmarks'
+Requires-Dist: scipy>=1.7; extra == 'benchmarks'
+Requires-Dist: seaborn>=0.12; extra == 'benchmarks'
+Requires-Dist: xgboost>=1.5; extra == 'benchmarks'
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.5; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pandas>=1.3; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# maya-encoding
+
+[![CI](https://github.com/danielregalado/maya-encoding/actions/workflows/ci.yml/badge.svg)](https://github.com/danielregalado/maya-encoding/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/maya-encoding.svg)](https://badge.fury.io/py/maya-encoding)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Maya-inspired numerical encodings for machine learning.**
+
+Two sklearn-compatible transformers that use the mathematical structure of the ancient Maya number system and calendar to create richer feature representations:
+
+- **VFDEncoder** (Vigesimal Feature Decomposition) — Decomposes numbers into the Maya base-20 system with bars (÷5) and dots (%5), giving models multi-scale numerical structure for free.
+- **MayaCalendarEncoder** (Maya Calendar Encoding) — Converts dates into features from the Tzolk'in (260-day), Haab' (365-day), and Long Count calendars, providing interlocking cyclical patterns at multiple time scales.
+
+## Installation
+
+```bash
+pip install maya-encoding
+```
+
+With visualization support:
+```bash
+pip install maya-encoding[viz]
+```
+
+## Quick Start
+
+### VFD: Numeric Feature Encoding
+
+```python
+from maya_encoding import VFDEncoder
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestRegressor
+
+# VFD decomposes numbers into vigesimal digits, bars, and dots
+encoder = VFDEncoder(components='full')
+
+# Works seamlessly in sklearn pipelines
+pipe = Pipeline([
+    ('encode', VFDEncoder()),
+    ('model', RandomForestRegressor())
+])
+pipe.fit(X_train, y_train)
+```
+
+How it works: the number **347** becomes:
+```
+347 = 17×20 + 7
+
+Level 0 (ones):   digit=7,  bars=1, dots=2
+Level 1 (twenties): digit=17, bars=3, dots=2
+
+Feature vector: [7, 1, 2, 17, 3, 2] (or normalized to [0,1])
+```
+
+This gives the model three "zoom levels" per number — coarse magnitude (digits), medium grouping (bars), and fine residual (dots).
+
+### MCE: Temporal Feature Encoding
+
+```python
+from maya_encoding import MayaCalendarEncoder
+
+# Encode dates using Maya calendar cycles
+encoder = MayaCalendarEncoder(
+    components=['tzolkin', 'haab', 'long_count'],
+    cyclical=True,  # Add sine/cosine for smooth cycle boundaries
+)
+
+X_temporal = encoder.fit_transform(df['date'])
+```
+
+The Maya calendar provides interlocking cycles of coprime periods (13, 20, 260, 365, 360), capturing multi-scale temporal patterns that standard sine/cosine encoding requires manual period selection to achieve.
+
+## Why Maya Encoding?
+
+**The problem:** When you feed a number like "347" to a model, it knows nothing about its structure. It has to learn from scratch that 347 is close to 350, "large" compared to 5, and divisible in certain ways.
+
+**The solution:** The Maya vigesimal system naturally decomposes numbers into a hierarchy:
+- **Vigesimal digits** (×20): coarse magnitude
+- **Bars** (×5): medium grouping
+- **Dots** (×1): fine residual
+
+This is a strict information superset — the model can ignore the extra features via regularization if they're not useful, but gets multi-scale structure for free if they are.
+
+For temporal data, the Maya calendar's three interlocking cycles (Tzolk'in 260-day, Haab' 365-day, Long Count) provide coprime-period features that capture patterns standard time encodings miss.
+
+## API Reference
+
+### VFDEncoder
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `n_levels` | `'auto'` | Vigesimal levels (auto-detected from data) |
+| `components` | `'full'` | `'full'`, `'lite'` (digits only), `'bars_dots'` |
+| `normalize` | `True` | Normalize to [0,1] |
+| `handle_negative` | `'abs_sign'` | `'abs_sign'`, `'shift'`, `'error'` |
+| `handle_float` | `'scale'` | `'scale'`, `'round'`, `'integer_part'` |
+| `scale_factor` | `'auto'` | Auto-detected from decimal precision |
+
+### MayaCalendarEncoder
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `components` | `['tzolkin', 'haab', 'long_count']` | Calendar systems to use |
+| `tzolkin_encoding` | `'separate'` | `'separate'` (2 features) or `'combined'` (1 feature) |
+| `haab_encoding` | `'hierarchical'` | `'hierarchical'` (with bars/dots) or `'flat'` |
+| `long_count_levels` | `3` | 1-5: kin, uinal, tun, katun, baktun |
+| `cyclical` | `True` | Add sine/cosine pairs |
+| `epoch` | `'gmt'` | `'gmt'` (standard), `'spinden'`, or custom JDN |
+| `wayeb_flag` | `True` | Binary feature for the 5-day Wayeb' period |
+
+## Visualization
+
+```python
+from maya_encoding.visualization.glyphs import plot_maya_number, render_maya_text
+
+# Text rendering
+print(render_maya_text(347))
+
+# Matplotlib rendering
+plot_maya_number(347)
+```
+
+## Development
+
+```bash
+git clone https://github.com/danielregalado/maya-encoding.git
+cd maya-encoding
+pip install -e ".[dev]"
+pytest
+```
+
+Run benchmarks:
+```bash
+python benchmarks/run_vfd_benchmarks.py
+python benchmarks/run_mce_benchmarks.py
+```
+
+## Citation
+
+If you use maya-encoding in your research, please cite:
+
+```bibtex
+@software{regalado2026maya,
+  author = {Regalado, Daniel},
+  title = {maya-encoding: Maya-Inspired Numerical Encodings for Machine Learning},
+  year = {2026},
+  url = {https://github.com/danielregalado/maya-encoding}
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

maya_encoding-0.1.0/README.md

@@ -0,0 +1,154 @@
+# maya-encoding
+
+[![CI](https://github.com/danielregalado/maya-encoding/actions/workflows/ci.yml/badge.svg)](https://github.com/danielregalado/maya-encoding/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/maya-encoding.svg)](https://badge.fury.io/py/maya-encoding)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Maya-inspired numerical encodings for machine learning.**
+
+Two sklearn-compatible transformers that use the mathematical structure of the ancient Maya number system and calendar to create richer feature representations:
+
+- **VFDEncoder** (Vigesimal Feature Decomposition) — Decomposes numbers into the Maya base-20 system with bars (÷5) and dots (%5), giving models multi-scale numerical structure for free.
+- **MayaCalendarEncoder** (Maya Calendar Encoding) — Converts dates into features from the Tzolk'in (260-day), Haab' (365-day), and Long Count calendars, providing interlocking cyclical patterns at multiple time scales.
+
+## Installation
+
+```bash
+pip install maya-encoding
+```
+
+With visualization support:
+```bash
+pip install maya-encoding[viz]
+```
+
+## Quick Start
+
+### VFD: Numeric Feature Encoding
+
+```python
+from maya_encoding import VFDEncoder
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestRegressor
+
+# VFD decomposes numbers into vigesimal digits, bars, and dots
+encoder = VFDEncoder(components='full')
+
+# Works seamlessly in sklearn pipelines
+pipe = Pipeline([
+    ('encode', VFDEncoder()),
+    ('model', RandomForestRegressor())
+])
+pipe.fit(X_train, y_train)
+```
+
+How it works: the number **347** becomes:
+```
+347 = 17×20 + 7
+
+Level 0 (ones):   digit=7,  bars=1, dots=2
+Level 1 (twenties): digit=17, bars=3, dots=2
+
+Feature vector: [7, 1, 2, 17, 3, 2] (or normalized to [0,1])
+```
+
+This gives the model three "zoom levels" per number — coarse magnitude (digits), medium grouping (bars), and fine residual (dots).
+
+### MCE: Temporal Feature Encoding
+
+```python
+from maya_encoding import MayaCalendarEncoder
+
+# Encode dates using Maya calendar cycles
+encoder = MayaCalendarEncoder(
+    components=['tzolkin', 'haab', 'long_count'],
+    cyclical=True,  # Add sine/cosine for smooth cycle boundaries
+)
+
+X_temporal = encoder.fit_transform(df['date'])
+```
+
+The Maya calendar provides interlocking cycles of coprime periods (13, 20, 260, 365, 360), capturing multi-scale temporal patterns that standard sine/cosine encoding requires manual period selection to achieve.
+
+## Why Maya Encoding?
+
+**The problem:** When you feed a number like "347" to a model, it knows nothing about its structure. It has to learn from scratch that 347 is close to 350, "large" compared to 5, and divisible in certain ways.
+
+**The solution:** The Maya vigesimal system naturally decomposes numbers into a hierarchy:
+- **Vigesimal digits** (×20): coarse magnitude
+- **Bars** (×5): medium grouping
+- **Dots** (×1): fine residual
+
+This is a strict information superset — the model can ignore the extra features via regularization if they're not useful, but gets multi-scale structure for free if they are.
+
+For temporal data, the Maya calendar's three interlocking cycles (Tzolk'in 260-day, Haab' 365-day, Long Count) provide coprime-period features that capture patterns standard time encodings miss.
+
+## API Reference
+
+### VFDEncoder
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `n_levels` | `'auto'` | Vigesimal levels (auto-detected from data) |
+| `components` | `'full'` | `'full'`, `'lite'` (digits only), `'bars_dots'` |
+| `normalize` | `True` | Normalize to [0,1] |
+| `handle_negative` | `'abs_sign'` | `'abs_sign'`, `'shift'`, `'error'` |
+| `handle_float` | `'scale'` | `'scale'`, `'round'`, `'integer_part'` |
+| `scale_factor` | `'auto'` | Auto-detected from decimal precision |
+
+### MayaCalendarEncoder
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `components` | `['tzolkin', 'haab', 'long_count']` | Calendar systems to use |
+| `tzolkin_encoding` | `'separate'` | `'separate'` (2 features) or `'combined'` (1 feature) |
+| `haab_encoding` | `'hierarchical'` | `'hierarchical'` (with bars/dots) or `'flat'` |
+| `long_count_levels` | `3` | 1-5: kin, uinal, tun, katun, baktun |
+| `cyclical` | `True` | Add sine/cosine pairs |
+| `epoch` | `'gmt'` | `'gmt'` (standard), `'spinden'`, or custom JDN |
+| `wayeb_flag` | `True` | Binary feature for the 5-day Wayeb' period |
+
+## Visualization
+
+```python
+from maya_encoding.visualization.glyphs import plot_maya_number, render_maya_text
+
+# Text rendering
+print(render_maya_text(347))
+
+# Matplotlib rendering
+plot_maya_number(347)
+```
+
+## Development
+
+```bash
+git clone https://github.com/danielregalado/maya-encoding.git
+cd maya-encoding
+pip install -e ".[dev]"
+pytest
+```
+
+Run benchmarks:
+```bash
+python benchmarks/run_vfd_benchmarks.py
+python benchmarks/run_mce_benchmarks.py
+```
+
+## Citation
+
+If you use maya-encoding in your research, please cite:
+
+```bibtex
+@software{regalado2026maya,
+  author = {Regalado, Daniel},
+  title = {maya-encoding: Maya-Inspired Numerical Encodings for Machine Learning},
+  year = {2026},
+  url = {https://github.com/danielregalado/maya-encoding}
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.