Metadata-Version: 2.4
Name: wjpy
Version: 0.1.0
Summary: Weighted Jaccard methodology for correlation network analysis. Bidirectional regime detection and pairing-family decomposition.
Home-page: https://github.com/nwharbert8-ui/wjpy
Author: Drake H. Harbert
Author-email: Drake@innerarchitecturellc.com
License: MIT
Project-URL: Documentation, https://github.com/nwharbert8-ui/wjpy
Project-URL: Bug Tracker, https://github.com/nwharbert8-ui/wjpy/issues
Project-URL: Source, https://github.com/nwharbert8-ui/wjpy
Project-URL: Methodology Paper, https://doi.org/10.5281/zenodo.19025536
Keywords: weighted-jaccard correlation-network regime-detection pairing-family genomics finance industrial-monitoring ecology brain-connectivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.6
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# wjpy — Weighted Jaccard Methodology for Correlation Network Analysis

[![PyPI version](https://badge.fury.io/py/wjpy.svg)](https://pypi.org/project/wjpy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19025536.svg)](https://doi.org/10.5281/zenodo.19025536)

A Python package implementing the Weighted Jaccard (WJ) methodology and pairing-family decomposition for correlation network analysis. Detects bidirectional structural regimes — both convergence and divergence — and separates magnitude-component reorganization from sign-component reorganization.

## Why WJ

Most correlation-network analysis collapses two structurally distinct reorganization modes into one number:
- **Magnitude reorganization:** correlations grow or shrink uniformly (financial crises).
- **Sign reorganization:** correlations flip polarity without changing magnitude (regime transitions, calm-era decorrelation).

`wjpy` implements the unsigned, signed, and binary Jaccard variants — and the gap between them — as separate, interpretable measurements. Validated empirically across genomics (GTEx v8 brain data), industrial sensors (NASA C-MAPSS, Scania, Tennessee Eastman), financial markets (S&P 500), and ecological systems.

## Installation

```bash
pip install wjpy
```

## Quick Start

```python
import numpy as np
from wjpy import (
    fast_spearman_matrix,
    weighted_jaccard,
    signed_weighted_jaccard,
    binary_jaccard,
    implementation_divergence,
)

# Compute Spearman correlation matrix from observation data
# data shape: (n_features, n_samples)
data_baseline = np.random.randn(50, 200)
data_regime = np.random.randn(50, 200)

corr_baseline = fast_spearman_matrix(data_baseline)
corr_regime = fast_spearman_matrix(data_regime)

# Compare networks
wj_uns = weighted_jaccard(corr_baseline, corr_regime)
wj_sgn = signed_weighted_jaccard(corr_baseline, corr_regime)
bj = binary_jaccard(corr_baseline, corr_regime, threshold=0.3)

print(f"Unsigned WJ: {wj_uns:.4f}")
print(f"Signed WJ:   {wj_sgn:.4f}")
print(f"Binary J:    {bj:.4f}")

# Decompose reorganization into magnitude vs sign components
divergence = implementation_divergence(corr_baseline, corr_regime)
print(f"Sign inversion %: {divergence['sign_inversion_pct']:.1f}")
print(f"Magnitude %:      {divergence['magnitude_change_pct']:.1f}")
```

## Functions

| Function | Purpose |
|---|---|
| `weighted_jaccard(corr_a, corr_b)` | Unsigned WJ (magnitude reorganization) |
| `signed_weighted_jaccard(corr_a, corr_b)` | Signed WJ (magnitude + sign) |
| `binary_jaccard(corr_a, corr_b, threshold)` | Topological reorganization at edge threshold |
| `implementation_divergence(corr_a, corr_b)` | Decompose magnitude vs sign components |
| `fast_spearman_matrix(data)` | Vectorized Spearman correlation matrix |
| `fast_pearson_matrix(data)` | Vectorized Pearson correlation matrix |
| `weighted_jaccard_chunked(vec_a, vec_b)` | Memory-efficient WJ for >10M-element vectors |

## Methodology References

- **Financial regime detection:** Harbert, D.H. (2026). A Pairing-Family Decomposition of the Weighted Jaccard Index... *Physica A* (under review). Code: https://github.com/nwharbert8-ui/financial-wj-structural-regimes
- **Genomics application:** Harbert, D.H. (2026). Sigma-1 and Sigma-2 receptors exhibit divergent genome-wide co-expression architectures... *Frontiers in Pharmacology, Neuropharmacology* (in press).
- **Industrial monitoring:** Harbert, D.H. (2026). Weighted Jaccard decomposition detects sensor network reorganization preceding mechanical failure in turbofan engines, Scania trucks, and chemical processes. *Mech. Syst. Signal Process.* (under review).
- **Ecological tipping points:** Harbert, D.H. (2026). Weighted Jaccard similarity reveals water quality parameter reorganization preceding trophic state transitions. *Ecological Indicators* (under review).
- **Pairing-family framework note:** Layer 2H methodology, articulated 2026-04-29.

## Premium Tier

The pairing-family decomposition implementations (Type 1 continuous-discrete, Type 2 sign-treatment, Type 5 local-global), full regime detection algorithms, macro-stress alignment utilities, and reference datasets per domain are available in a separate distribution `wjpy-premium`. Contact: Drake@innerarchitecturellc.com

## License

MIT License (core). See LICENSE.

## Author

Drake H. Harbert
Inner Architecture LLC, Canton, OH
ORCID: [0009-0007-7740-3616](https://orcid.org/0009-0007-7740-3616)
Email: Drake@innerarchitecturellc.com

## Citation

If you use `wjpy` in published work, please cite:

```bibtex
@software{harbert_wjpy_2026,
  author       = {Harbert, Drake H.},
  title        = {wjpy: Weighted Jaccard methodology for correlation network analysis},
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19025536},
  url          = {https://github.com/nwharbert8-ui/wjpy}
}
```
