Metadata-Version: 2.4
Name: gfcca
Version: 0.1.0
Summary: Graph-embedded fuzzy kernel canonical correlation analysis for multimodal fusion
Project-URL: Homepage, https://github.com/BrianLam-agent/gfcca
Project-URL: Repository, https://github.com/BrianLam-agent/gfcca
Project-URL: Issues, https://github.com/BrianLam-agent/gfcca/issues
Project-URL: Changelog, https://github.com/BrianLam-agent/gfcca/releases
Author: BrianLam
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: canonical-correlation-analysis,classification,kernel-methods,machine-learning,multi-omics,multimodal-fusion,sklearn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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 :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: scipy
Provides-Extra: shap
Requires-Dist: shap; extra == 'shap'
Description-Content-Type: text/markdown

# gfcca

Graph-embedded fuzzy kernel canonical correlation analysis (GFCCA) for
multimodal / multi-omics feature fusion and classification.

GFCCA extends regularized kernel CCA with:

- **Intuitionistic fuzzy scoring** — each sample gets a confidence weight
  derived from its distance to its class centroid (membership) and the
  proportion of other-class neighbours within a relative distance threshold
  (non-membership).
- **Discriminative graph embedding** — a class-aware graph regularizer
  (`Lw - beta * Lb`) pulls same-class samples together while pushing
  different-class samples apart in the fused space.

The fused canonical variables are concatenated into a joint feature matrix
that can be fed into any scikit-learn classifier.

## Installation

```bash
pip install gfcca
```

Requires Python 3.10+.

## Quick start

```python
import numpy as np
from sklearn.ensemble import RandomForestClassifier
from gfcca import build_gfcca_features

# Two views (modalities) of the same samples, plus labels
X1 = np.random.rand(100, 20)  # e.g. eye imaging features
X2 = np.random.rand(100, 50)  # e.g. SNP genotypes
y = np.random.randint(0, 3, 100)

F_train, models = build_gfcca_features([X1, X2], y)
clf = RandomForestClassifier().fit(F_train, y)
```

## Package layout

| Path            | Contents                                                       |
|-----------------|----------------------------------------------------------------|
| `src/gfcca/`    | The published package (`cca`, `gfcca`, `classifiers`)          |
| `experiments/`  | Reproduction scripts for the diabetes multi-omics study (not published) |
| `tests/`        | pytest suite                                                   |

## Experiments

The full multi-modal classification pipeline (5-modality diabetes cohort,
CV + SHAP interpretability) lives in `experiments/` and is not part of the
PyPI package:

```bash
uv sync --group experiments
uv run --group experiments python experiments/main.py \
    --modalities eye fur methy pbmc snp \
    --feature gfcca --classifier rf --shap --seed 42
```

See [experiments/datasets/README.md](experiments/datasets/README.md) for the
expected data layout.

## Development

```bash
uv sync --group dev
uv run ruff check .
uv run ruff format .
uv run pytest tests/
uv run mypy src/gfcca
```

## License

Apache-2.0
