Metadata-Version: 2.4
Name: dual-vade
Version: 0.1.0
Summary: Unsupervised image clustering with trainable VaDE, Freq-VaDE, and Dual-VaDE
Author: Wugeng Zheng
Maintainer: Wugeng Zheng
License-Expression: MIT
Project-URL: Repository, https://github.com/ZhengWugeng/dual-vade
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.6
Requires-Dist: scikit-learn>=1.3
Dynamic: license-file

# Dual-VaDE

Unsupervised neural image clustering with VaDE, Freq-VaDE, and Dual-VaDE.
Author and maintainer: Wugeng Zheng. Code license: MIT.

## Installation

```text
python -m pip install dual-vade
```

Requires Python 3.10 or newer. Runtime dependencies are NumPy, PyTorch, and
scikit-learn. For GPU use, install a PyTorch build compatible with your GPU and
driver before installing this package. Use `device="cpu"` for CPU operation.

Give the model your prepared images, train without labels, save the complete
model, and reload it for inference on new images. There is no required dataset,
official pretrained model, model registry, or automatic model download.
The interface encapsulates neural training and GMM fitting; it does not claim
source-code or weight secrecy.

## Train, cluster, and save

```python
from dual_vade import DualVaDE

# images: a float array shaped (N, 128, 128), with values in [0, 1].
# No ground-truth labels are passed to fit.
model = DualVaDE(n_clusters=3, device="cuda")
model.fit(images, epochs=200, verbose=True)
labels = model.predict(images)
model.save("my_model")

# Later, with no training data or further fitting:
restored = DualVaDE.load("my_model", device="cpu")
new_labels = restored.predict(new_images)
probabilities = restored.predict_proba(new_images)
embeddings = restored.transform(new_images)
```

`fit` trains the neural encoders, decoder, and native mixture prior, then fits a
separate diagonal GMM to the final training posterior means. It is not a GMM-only
refit. A new constructor starts from random neural weights. Calling `fit` again,
or after loading your own saved model, continues those weights with a new
optimizer and final GMM. `fit` returns `self`; `predict` returns cluster IDs.
The user chooses `n_clusters`; the package does not select it automatically or
assign semantic names to clusters.

## Model choices

- `VaDE(n_clusters=3, ...)`: spatial-only.
- `FreqVaDE(n_clusters=3, spectral="reim", ...)`: frequency-only.
- `DualVaDE(n_clusters=3, spectral="reim", ...)`: spatial and frequency branches.

The four spectral choices are `fullfreq`, `lowfreq`, `polarfreq`, and `reim`.
ReIm is the default for FreqVaDE and DualVaDE. The old internal FullCplx source
is named PolarFreq publicly. Together with VaDE, this provides nine training
configurations. The preserved network implementations are unchanged.

## Input requirements

Supply finite, real-valued grayscale image arrays shaped `(N,H,W)` or
`(N,1,H,W)`, already scaled to `[0,1]`. All images must match the constructor's
`image_size`: default 128, or a power of two at least 64. Training requires at
least `max(2, n_clusters)` images; practical training usually needs more data.

The same format applies to medical or non-medical images; no specific dataset is
required. RGB images, 3D volumes, and file-directory paths are not direct inputs.
The package does not silently resize, normalize, register, or convert raw images.
Use the same preparation at training and prediction time. Train only on your
training split when evaluating held-out generalization.

`examples/train_local.py` reads your prepared `.npy` array or a `.npz` archive
containing `images`. See `docs/TRAINING.md` for the API, training recipe, and
lifecycle, and `docs/BUNDLE_FORMAT.md` for saved model contents.

## Saved models and scope

`save("my_model")` creates a new directory containing `config.json`,
`model_state.pth`, `clusterer.npz`, and `manifest.json`. A network `.pth` alone
cannot restore the full clustering pipeline. Loading and prediction never train
or fit a GMM. The package does not upload your images or saved models.

The MIT license covers this software, not rights to anyone's input data. This
release distributes neither datasets nor official pretrained weights/GMMs.
Users are responsible for the permissions applicable to their data and any
models they choose to share. Outputs are cluster IDs, not clinical diagnoses.

## Validation

The installed code-only rc3 wheel passed HPG job `46757892` on RTX PRO 6000.
All nine configurations trained on generated non-medical grayscale images,
without external data or pretrained assets. Neural parameter updates, final GMM,
held-out inference, saved-model GPU/CPU reload, CPU training, continued training,
and the CLI example passed. See `docs/TRAINING_VALIDATION_CODE_ONLY.json`.
The published TestPyPI wheel then passed the same nine-configuration checks in
job `46761432`, installed into a fresh package venv with the validated HPG
scientific dependencies. Its origin and API hash were verified, with no source
checkout used for package imports. See `docs/TESTPYPI_INSTALL_VALIDATION.json`.
Short functional checks do not establish clustering quality on a user's dataset.
Historical results are retained in `docs/VALIDATION_STATUS.md`.
