Metadata-Version: 2.4
Name: hiwenet
Version: 0.6.0
Summary: Histogram-weighted pairwise distances for node-wise feature data.
Project-URL: Homepage, https://github.com/raamana/hiwenet
Author-email: Pradeep Reddy Raamana <raamana@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: medpy
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: coverage[toml]; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: nibabel; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Requires-Dist: sphinx-argparse; extra == 'dev'
Provides-Extra: docs
Requires-Dist: matplotlib; extra == 'docs'
Requires-Dist: nibabel; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-argparse; extra == 'docs'
Provides-Extra: test
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# Histogram-weighted Networks (`hiwenet`)

[![status](http://joss.theoj.org/papers/df10a3a527fe169447a64c0cc810ff3c/status.svg)](http://joss.theoj.org/papers/df10a3a527fe169447a64c0cc810ff3c)

`hiwenet` computes pairwise distances between groups of node-wise feature
values. Its main role today is as the numerical engine behind
[graynet](https://github.com/raamana/graynet), but it can also be used
directly whenever you need histogram-based or original-distribution-based
distances between groups.

Given:

- a 1D array of feature values
- a matching 1D array of group labels
- a distance metric

`hiwenet` returns either:

- a pairwise distance matrix
- an in-memory NetworkX graph with the same edge weights

This release is intentionally programmatic and does not provide a CLI.

![illustration](docs/illustration.png)

## Installation

```bash
pip install -U hiwenet
```

## Quick Start

```python
import numpy as np

from hiwenet import extract

features = np.array([0.2, 0.1, 0.3, 1.0, 1.2, 0.9])
groups = np.array([0, 0, 0, 1, 1, 1])

edge_weights = extract(
    features,
    groups,
    weight_method="manhattan",
)
```

The default output matches what `graynet` expects: a square NumPy array whose
upper triangle stores the pairwise edge weights.

## API

### `extract`

`extract()` is the main entry point.

```python
from hiwenet import extract

edge_weights = extract(
    features,
    groups,
    weight_method="manhattan",
    num_bins=25,
    edge_range=None,
    trim_outliers=True,
    trim_percentile=5,
    use_original_distribution=False,
    relative_to_all=False,
    asymmetric=False,
    return_networkx_graph=False,
)
```

### `ExtractConfig`

If you prefer a validated configuration object:

```python
from hiwenet import ExtractConfig, extract_with_config

config = ExtractConfig(
    weight_method="manhattan",
    num_bins=25,
)

edge_weights = extract_with_config(features, groups, config)
```

## Metrics

`hiwenet` supports both histogram-based distances and distances that operate on
the original values in each group.

Histogram-based metrics include:

- `manhattan`
- `euclidean`
- `chebyshev`
- `braycurtis`
- `canberra`
- `cosine`
- `correlation`
- `emd`
- `kl_divergence`
- `js_divergence`

Original-distribution metrics include:

- `diff_medians`
- `diff_medians_abs`
- `diff_means`
- `diff_means_abs`
- `exp_diff_means_norm_std`
- `ranksum_statistic`

Custom callables are also supported.

## Relative-To-All

`relative_to_all=True` remains available for workflows that compare each group
against the pooled distribution from all groups.

## Scientific Notes

- Explicit `edge_range` values are useful when you need consistent histogram
  support across subjects.
- Built-in non-histogram metrics operate on the original values in each group.
- Degenerate histogram cases are handled deterministically in this release
  instead of relying on runtime-warning-driven `NaN` outputs.

## Development

```bash
pytest -q
hatch build
```

## Citation

If `hiwenet` is useful in your work, please cite the JOSS paper linked above.
