tessera-ml 0.2.0__tar.gz

tessera-ml-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, João F. R. Tonini
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tessera-ml-0.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include tessera *.py
+recursive-include tests *.py
+recursive-exclude data *
+recursive-exclude results *
+recursive-exclude paper *

tessera-ml-0.2.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.1
+Name: tessera-ml
+Version: 0.2.0
+Summary: Topological Entity Similarity Structure for Emergent Response Analysis
+Author-email: "João F. R. Tonini" <jtonini@richmond.edu>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/jtonini/tessera
+Project-URL: Repository, https://github.com/jtonini/tessera
+Project-URL: Documentation, https://github.com/jtonini/tessera#readme
+Project-URL: Issues, https://github.com/jtonini/tessera/issues
+Keywords: machine-learning,graph-neural-networks,similarity-networks,community-detection,binary-classification,regime-divergence,network-topology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+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 :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: pandas>=1.3
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: matplotlib>=3.5
+Provides-Extra: ml
+Requires-Dist: torch>=2.0; extra == "ml"
+Requires-Dist: torch-geometric>=2.3; extra == "ml"
+Requires-Dist: leidenalg>=0.9; extra == "ml"
+Requires-Dist: igraph>=0.10; extra == "ml"
+Provides-Extra: full
+Requires-Dist: torch>=2.0; extra == "full"
+Requires-Dist: torch-geometric>=2.3; extra == "full"
+Requires-Dist: leidenalg>=0.9; extra == "full"
+Requires-Dist: igraph>=0.10; extra == "full"
+Requires-Dist: xgboost>=1.7; extra == "full"
+Requires-Dist: ripser>=0.6; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+
+# TESSERA
+
+**Topological Entity Similarity Structure for Emergent Response Analysis**
+
+A domain-general framework for detecting and exploiting geometric structure
+in multi-dimensional feature spaces for predictive classification.
+
+*Targeting: Nature Computational Science*
+
+## Core Hypothesis
+
+When entities are characterized by multi-dimensional features and outcomes
+depend on relational position in feature space, similarity network topology
+carries predictive information that direct feature-based classifiers miss.
+
+## Three Failure Geometries
+
+TESSERA detects geometrically distinct response regions in entity similarity
+space:
+
+1. **Ecotone** — responses cluster at boundaries between stable operational
+   domains (analogous to ecological transition zones)
+2. **Isolated cluster** — responses occupy a distinct region, separate from
+   main domains
+3. **Diffuse** — responses scattered within domains, driven by individual
+   feature thresholds
+
+## Three Demonstration Domains
+
+| | Ecology | Manufacturing | HPC |
+|---|---|---|---|
+| **Entity** | Reef survey | Production run | Job |
+| **Features** | Environmental conditions | Sensor measurements | Resource usage |
+| **Outcome** | Bleaching | Defect | Failure |
+| **Dataset** | Global Coral Bleaching DB | UCI SECOM | Synthetic / NØMAD |
+| **N** | ~35,000 | 1,567 | 5,000+ |
+
+## Validation Protocol
+
+1. **Phase 1 — Ablation**: GNN vs. MLP, RF, XGBoost, LogReg (justify network)
+2. **Phase 2 — Similarity**: 7 measures compared (Simpson, Cosine, Bray-Curtis,
+   Jaccard, Pearson, Euclidean, Mahalanobis)
+3. **Phase 3 — Bin sensitivity**: n_bins = 2, 3, 4, 5 (Simpson only)
+4. **Phase 4 — Temporal**: 5-fold temporal cross-validation
+
+## Project Structure
+
+```
+tessera/
+├── __init__.py                    # Package init (v0.1.0)
+├── core/
+│   ├── __init__.py
+│   ├── similarity.py              # 7 similarity measures
+│   └── network.py                 # Graph construction (threshold, kNN, weighted)
+├── synthetic/
+│   ├── __init__.py
+│   ├── landscape.py               # Feature space topology builder
+│   ├── outcomes.py                # Failure pattern assignment (3 types + mixed)
+│   └── visualize.py               # Diagnostic plots
+├── data_acquisition.py            # Real dataset download & preprocessing
+├── test_generator.py              # Synthetic data validation
+└── test_pipeline.py               # End-to-end pipeline test
+```
+
+## Current Status
+
+- [x] Synthetic data generator (3 patterns + mixed, with entity injection)
+- [x] Similarity engine (7 measures, vectorized)
+- [x] Network construction (threshold, kNN, weighted)
+- [x] Pipeline validation (data → similarity → graph)
+- [ ] GNN model
+- [ ] Real dataset acquisition (coral bleaching, SECOM)
+- [ ] Validation pipeline (4 phases)
+- [ ] Methods section
+- [ ] Results
+- [ ] Introduction, Discussion, Conclusions
+
+## Paper Writing Order
+
+1. Methods
+2. Results
+3. Introduction
+4. Discussion
+5. Conclusions
+6. Abstract (last)
+
+## References
+
+- van Woesik, R. & Kratochwill, C. (2022). A global coral-bleaching database,
+  1980–2020. *Scientific Data*, 9(20).
+- McCann, M. & Johnston, A. (2008). SECOM Dataset. UCI ML Repository.
+- Tonini, J. (2025). NØMAD-HPC. *Journal of Open Research Software*.

tessera-ml-0.2.0/README.md

@@ -0,0 +1,92 @@
+# TESSERA
+
+**Topological Entity Similarity Structure for Emergent Response Analysis**
+
+A domain-general framework for detecting and exploiting geometric structure
+in multi-dimensional feature spaces for predictive classification.
+
+*Targeting: Nature Computational Science*
+
+## Core Hypothesis
+
+When entities are characterized by multi-dimensional features and outcomes
+depend on relational position in feature space, similarity network topology
+carries predictive information that direct feature-based classifiers miss.
+
+## Three Failure Geometries
+
+TESSERA detects geometrically distinct response regions in entity similarity
+space:
+
+1. **Ecotone** — responses cluster at boundaries between stable operational
+   domains (analogous to ecological transition zones)
+2. **Isolated cluster** — responses occupy a distinct region, separate from
+   main domains
+3. **Diffuse** — responses scattered within domains, driven by individual
+   feature thresholds
+
+## Three Demonstration Domains
+
+| | Ecology | Manufacturing | HPC |
+|---|---|---|---|
+| **Entity** | Reef survey | Production run | Job |
+| **Features** | Environmental conditions | Sensor measurements | Resource usage |
+| **Outcome** | Bleaching | Defect | Failure |
+| **Dataset** | Global Coral Bleaching DB | UCI SECOM | Synthetic / NØMAD |
+| **N** | ~35,000 | 1,567 | 5,000+ |
+
+## Validation Protocol
+
+1. **Phase 1 — Ablation**: GNN vs. MLP, RF, XGBoost, LogReg (justify network)
+2. **Phase 2 — Similarity**: 7 measures compared (Simpson, Cosine, Bray-Curtis,
+   Jaccard, Pearson, Euclidean, Mahalanobis)
+3. **Phase 3 — Bin sensitivity**: n_bins = 2, 3, 4, 5 (Simpson only)
+4. **Phase 4 — Temporal**: 5-fold temporal cross-validation
+
+## Project Structure
+
+```
+tessera/
+├── __init__.py                    # Package init (v0.1.0)
+├── core/
+│   ├── __init__.py
+│   ├── similarity.py              # 7 similarity measures
+│   └── network.py                 # Graph construction (threshold, kNN, weighted)
+├── synthetic/
+│   ├── __init__.py
+│   ├── landscape.py               # Feature space topology builder
+│   ├── outcomes.py                # Failure pattern assignment (3 types + mixed)
+│   └── visualize.py               # Diagnostic plots
+├── data_acquisition.py            # Real dataset download & preprocessing
+├── test_generator.py              # Synthetic data validation
+└── test_pipeline.py               # End-to-end pipeline test
+```
+
+## Current Status
+
+- [x] Synthetic data generator (3 patterns + mixed, with entity injection)
+- [x] Similarity engine (7 measures, vectorized)
+- [x] Network construction (threshold, kNN, weighted)
+- [x] Pipeline validation (data → similarity → graph)
+- [ ] GNN model
+- [ ] Real dataset acquisition (coral bleaching, SECOM)
+- [ ] Validation pipeline (4 phases)
+- [ ] Methods section
+- [ ] Results
+- [ ] Introduction, Discussion, Conclusions
+
+## Paper Writing Order
+
+1. Methods
+2. Results
+3. Introduction
+4. Discussion
+5. Conclusions
+6. Abstract (last)
+
+## References
+
+- van Woesik, R. & Kratochwill, C. (2022). A global coral-bleaching database,
+  1980–2020. *Scientific Data*, 9(20).
+- McCann, M. & Johnston, A. (2008). SECOM Dataset. UCI ML Repository.
+- Tonini, J. (2025). NØMAD-HPC. *Journal of Open Research Software*.

tessera-ml-0.2.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["setuptools>=68.0,<69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tessera-ml"
+version = "0.2.0"
+description = "Topological Entity Similarity Structure for Emergent Response Analysis"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "BSD-3-Clause"}
+authors = [
+    {name = "João F. R. Tonini", email = "jtonini@richmond.edu"},
+]
+keywords = [
+    "machine-learning",
+    "graph-neural-networks",
+    "similarity-networks",
+    "community-detection",
+    "binary-classification",
+    "regime-divergence",
+    "network-topology",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=1.21",
+    "scipy>=1.7",
+    "pandas>=1.3",
+    "scikit-learn>=1.0",
+    "matplotlib>=3.5",
+]
+
+[project.optional-dependencies]
+ml = [
+    "torch>=2.0",
+    "torch-geometric>=2.3",
+    "leidenalg>=0.9",
+    "igraph>=0.10",
+]
+full = [
+    "torch>=2.0",
+    "torch-geometric>=2.3",
+    "leidenalg>=0.9",
+    "igraph>=0.10",
+    "xgboost>=1.7",
+    "ripser>=0.6",
+]
+dev = [
+    "pytest>=7.0",
+    "black>=23.0",
+    "ruff>=0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jtonini/tessera"
+Repository = "https://github.com/jtonini/tessera"
+Documentation = "https://github.com/jtonini/tessera#readme"
+Issues = "https://github.com/jtonini/tessera/issues"
+
+[tool.setuptools.packages.find]
+include = ["tessera*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tessera-ml-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tessera-ml-0.2.0/tessera/__init__.py

@@ -0,0 +1,13 @@
+"""
+TESSERA - Topological Entity Similarity Structure for Emergent Response Analysis
+
+A domain-general framework for detecting and exploiting geometric structure
+in multi-dimensional feature spaces for predictive classification.
+
+Modules:
+- tessera.core: Similarity, network, community detection, regime divergence
+- tessera.synthetic: Synthetic data generation
+- tessera.models: GNN, LSTM, Autoencoder, Ensemble
+"""
+
+__version__ = "0.2.0"

tessera-ml-0.2.0/tessera/core/__init__.py

@@ -0,0 +1,88 @@
+"""
+TESSERA Core Module
+
+Similarity computation, network construction, community detection,
+regime divergence analysis, temporal persistence, and response
+landscape spatial methods.
+"""
+
+from .similarity import SimilarityEngine, compute_similarity_batch
+from .network import NetworkBuilder, TesseraGraph
+from .community import (
+    CommunityDetector,
+    CommunityStructure,
+    NJTree,
+    PersistenceResult,
+    CommunityPersistenceAnalyzer,
+    StochasticEventDiagnostics,
+    StochasticEventReport,
+    EntityDisplacement,
+)
+from .regime_divergence import RegimeDivergenceComputer, RegimeDivergenceMap
+from .response_landscape import (
+    ReferenceLandscapeBuilder,
+    ResponseSurface,
+    GradientFieldAnalyzer,
+    GradientAnalysis,
+    PersistentHomologyAnalyzer,
+    TopologicalFeatures,
+    SpatialScanStatistic,
+    ScanResult,
+)
+from .fusion import SimilarityFusion, FusionResult
+from .parallel import TesseraParallel, parallel_config, ParallelConfig
+from .safety import safe_array, safe_similarity_matrix, safe_probabilities
+from .checkpoint import CheckpointManager, get_or_create_checkpoint
+from .sparse_similarity import SparseSimilarity, SparseKNNResult, compute_sparse_knn_batch
+from .validation import (
+    AblationRunner,
+    AblationResult,
+    SimilarityComparisonRunner,
+    SimilarityComparisonResult,
+    BinSensitivityRunner,
+    BinSensitivityResult,
+    TemporalCVRunner,
+    TemporalCVResult,
+    compute_metrics,
+    EvalMetrics,
+)
+
+__all__ = [
+    "SimilarityEngine",
+    "compute_similarity_batch",
+    "NetworkBuilder",
+    "TesseraGraph",
+    "CommunityDetector",
+    "CommunityStructure",
+    "NJTree",
+    "PersistenceResult",
+    "CommunityPersistenceAnalyzer",
+    "StochasticEventDiagnostics",
+    "StochasticEventReport",
+    "EntityDisplacement",
+    "RegimeDivergenceComputer",
+    "RegimeDivergenceMap",
+    "ReferenceLandscapeBuilder",
+    "ResponseSurface",
+    "GradientFieldAnalyzer",
+    "GradientAnalysis",
+    "PersistentHomologyAnalyzer",
+    "TopologicalFeatures",
+    "SpatialScanStatistic",
+    "ScanResult",
+    "SimilarityFusion",
+    "FusionResult",
+    "TesseraParallel",
+    "parallel_config",
+    "ParallelConfig",
+    "AblationRunner",
+    "AblationResult",
+    "SimilarityComparisonRunner",
+    "SimilarityComparisonResult",
+    "BinSensitivityRunner",
+    "BinSensitivityResult",
+    "TemporalCVRunner",
+    "TemporalCVResult",
+    "compute_metrics",
+    "EvalMetrics",
+]