Code for A Categorical Framework for Khipu Analysis

Categorical Framework for Khipu Analysis - Code Repository Description This repository contains the complete Python implementation of the computational methods described in: "A Categorical Framework for Khipu Analysis: Computational Methods for Reconstruction and Exploratory Diagnostics"J. J. Segura, Universidad Andrés Bello (2026) What This Code Does This package provides reproducible tools for analyzing khipu (Andean knotted-cord recording devices) using category-theoretic principles. The implementation bridges abstract mathematical frameworks with practical archaeological corpus analysis. Core Capabilities: Categorical Signature Extraction: Computes an 8-dimensional structural fingerprint for each khipu based on empirical densities of limit-like and colimit-like patterns (equalizers, pullbacks, products, coproducts, pushouts, terminal objects) Administrative Backbone Validation: Operationalizes the widespread archaeological hypothesis of summary-detail organization through context-free grammar with numeric side conditions Exploratory Corpus Diagnostics: Unsupervised clustering, PCA visualization, and weak-label association analysis for identifying structural regimes across large khipu databases Reconstruction Under Damage: Constraint-propagation algorithms for completing partial khipu descriptions while quantifying uncertainty, motivated by sheaf-theoretic "gluing" principles Multi-Surrogate Sensitivity Analysis: Evaluates grouping uncertainty by computing signatures under multiple pendant-group surrogates (database clusters, color schemes, spatial contiguity) Validated on Public Corpora All methods have been empirically validated on two major public khipu databases: Open Khipu Repository (OKR): 619 khipu, 54,403 cords Harvard Khipu Database (HKDB) export via Khipu Field Guide (v2.1.0): 685 khipu, 62,515 cords Key Features Reproducible by design: Pinned dependencies, deterministic outputs, complete environment specifications Fast execution: Full corpus analysis (600+ khipu) completes in ~25 seconds Database-agnostic: Works with OKR SQLite format and HKDB KFG exports Extensible: Modular architecture allows custom signature components and constraint families Well-documented: Inline docstrings, example workflows, case studies Archaeological best practices: Respects uncertainty, avoids over-interpretation, provides diagnostic warnings Installation Requirements Python 3.11+ (tested on 3.11.2) Core dependencies: numpy, pandas, scipy, scikit-learn, matplotlib, networkx Database support: sqlite3 (built-in) Quick Start # Clone repository git clone [REPOSITORY_URL] cd khipu-categorical-framework # Create virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # OR for pinned reproducible environment: pip install -r requirements_pinned.txt # Run basic workflow python examples/basic_workflow.py Using the Pinned Environment For exact reproducibility of manuscript results: # Option 1: pip with pinned requirements pip install -r requirements_pinned.txt # Option 2: conda environment (if you use conda) conda env create -f environment.yml conda activate khipu-categorical Usage Examples Example 1: Compute Signatures for a Single Khipu from khipu_categorical import KhipuLoader, SignatureExtractor # Load khipu from OKR database loader = KhipuLoader("path/to/khipu.db") khipu = loader.load_khipu(khipu_id="UR004") # Extract 8-dimensional signature extractor = SignatureExtractor() signature = extractor.compute_signature(khipu) print(f"Equalizer proxy (σ3): {signature['sigma3_equalizer']:.3f}") print(f"Product proxy (σ2): {signature['sigma2_product']:.3f}") print(f"Grouping quality (σ9): {signature['sigma9_grouping_quality']:.3f}") Example 2: Run Full Corpus Analysis from khipu_categorical import CorpusAnalyzer # Analyze entire OKR corpus analyzer = CorpusAnalyzer("path/to/khipu.db") results = analyzer.run_full_analysis( grouping_surrogates=["cluster", "color", "contiguity"], output_dir="results/" ) # Results include: # - Signature statistics with bootstrap 95% CIs # - PCA visualizations # - Cross-surrogate correlation tables # - Case study reports Example 3: Reconstruct Damaged Khipu from khipu_categorical import ReconstructionEngine # Load partial khipu with missing values partial_khipu = loader.load_khipu("UR123", allow_missing=True) # Attempt reconstruction engine = ReconstructionEngine(tolerance=0.05) completions = engine.reconstruct( partial_khipu, max_solutions=10, constraint_types=["summation", "hierarchy", "scheme_repetition"] ) # Examine uncertainty print(f"Found {len(completions)} consistent completions") print(f"Variable uncertainty ranges: {engine.get_uncertainty_summary()}") Repository Structure khipu-categorical-framework/ ├── README.md # Main documentation ├── LICENSE # MIT or CC-BY-4.0 ├── requirements.txt # Minimal dependencies ├── requirements_pinned.txt # Exact versions for reproducibility ├── environment.yml # Conda environment specification ├── setup.py # Package installation ├── khipu_categorical/ # Main package │ ├── __init__.py │ ├── category.py # Category Khipu definition │ ├── signatures.py # Signature extraction │ ├── backbone.py # Administrative backbone grammar │ ├── reconstruction.py # Constraint propagation │ ├── diagnostics.py # Clustering and weak-label analysis │ ├── database.py # OKR and HKDB loaders │ └── utils.py # Helper functions ├── examples/ # Worked examples │ ├── basic_workflow.py │ ├── corpus_analysis.py │ ├── reconstruction_demo.py │ └── case_studies.py ├── tests/ # Unit and integration tests │ ├── test_signatures.py │ ├── test_reconstruction.py │ └── test_database_loaders.py ├── data/ # Sample data (small test cases) │ └── sample_khipu.json ├── docs/ # Additional documentation │ ├── mathematical_background.md │ ├── signature_components.md │ └── reconstruction_algorithms.md └── manuscript_reproduction/ # Scripts to reproduce all manuscript results ├── run_okr_analysis.py ├── run_hkdb_analysis.py ├── generate_all_figures.py └── generate_all_tables.py Reproducing Manuscript Results All tables and figures in the manuscript can be reproduced exactly: # Generate all OKR results (Tables 4-6, Figures 5-6, 11-12) python manuscript_reproduction/run_okr_analysis.py # Generate all HKDB results (Tables 7-9, Figures 7-8) python manuscript_reproduction/run_hkdb_analysis.py # Generate all figures python manuscript_reproduction/generate_all_figures.py # Generate all tables (LaTeX format) python manuscript_reproduction/generate_all_tables.py Expected runtime: ~25 seconds per corpus on modern hardware (tested on [specify your system]). Data Sources This code works with two public khipu databases: Open Khipu Repository (OKR) Format: SQLite database (khipu.db) Citation: OKR Team (2025). The Open Khipu Repository, v2.1.0. Zenodo. https://doi.org/10.5281/zenodo.18025748 Download: https://zenodo.org/records/18025748 Harvard Khipu Database (HKDB) Export Format: Processed via Khipu Field Guide tooling Citation: Medrano & Khosla (2024). How Can Data Science Contribute to Understanding the Khipu Code? (Companion Data), v2.1.0. Zenodo. https://doi.org/10.5281/zenodo.10472429 Download: https://zenodo.org/records/10472429 Processing: See Khipu Field Guide documentation at khipufieldguide.com Note: Khipu are cultural heritage objects. Users should interpret analyses in collaboration with source communities and domain experts. Validation and Testing The package includes comprehensive tests: # Run all tests pytest tests/ # Run with coverage report pytest --cov=khipu_categorical tests/ # Run specific test suite pytest tests/test_signatures.py -v All tests pass on the reference environment (Python 3.11.2, see requirements_pinned.txt). Performance Benchmarks Typical performance on reference hardware (specify your specs): Single khipu signature extraction: