Metadata-Version: 2.4
Name: graph_dictlearn
Version: 0.11.0
Summary: A set of representation learning and dictionary learning algorithms for graph data.
Author-email: Nimendra Gnawardana <nimendraamiththa1@gmail.com>, Siyathma Wedamulla <wedamullasiyathma@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nimendra-ag/graph_dictlearn
Project-URL: Repository, https://github.com/nimendra-ag/graph_dictlearn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gensim==4.4.0
Requires-Dist: joblib==1.5.3
Requires-Dist: matplotlib==3.11.0
Requires-Dist: networkx==3.6.1
Requires-Dist: numpy==2.5.0
Requires-Dist: pandas==3.0.3
Requires-Dist: rdkit==2026.3.3
Requires-Dist: scikit-learn==1.9.0
Requires-Dist: scipy==1.18.0
Requires-Dist: seaborn==0.13.2
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"
Dynamic: license-file

# graph_dictlearn

A Python package for graph-level dictionary learning — combining graph representation learning with sparse coding techniques for graph classification tasks.

## Installation

```bash
pip install graph_dictlearn
```

For GPU-accelerated dictionary learners (BayesianDLGPU, FrozenKSVDLearnerGPU, FDDLGPU, CSFDDLGPU), install PyTorch with CUDA support separately from [pytorch.org](https://pytorch.org/get-started/locally/) before using them:

```bash
# Example for CUDA 12.4
pip install torch --index-url https://download.pytorch.org/whl/cu124
```

## Overview

`graph_dictlearn` provides a modular pipeline for graph classification with three stages:

1. **Load** graph data from molecular SDF files
2. **Encode** graphs into fixed-length vector representations
3. **Learn** sparse dictionaries over those representations

Each stage has interchangeable components, so you can mix and match encoders and dictionary learners.

## Quick Start

```python
from graph_dictlearn import SDFLoader, WL, AKSVD

# 1. Load molecular graphs
loader = SDFLoader("molecules.sdf", label_property="value")
graphs, labels = loader.load()

# 2. Encode graphs into fixed-length embeddings
encoder = WL(wl_iterations=2, attributed=True)
embeddings = encoder.generate_training_embeddings(graphs, labels)

# 3. Learn a sparse dictionary
learner = AKSVD(dimensions=16, n_non_zero_coefs=10)
learner.fit(embeddings)
sparse_codes = learner.infer(embeddings)
```

## Components

### Data Loader

| Class | Description |
|-------|-------------|
| `SDFLoader` | Loads molecular graphs and labels from SDF files via RDKit |

### Graph Encoders

| Class | Description | Supervised |
|-------|-------------|------------|
| `WL` | Weisfeiler-Lehman subtree kernel with imbalance-aware discriminative feature selection | Yes |
| `EdgeWL` | WL variant that incorporates edge features alongside node labels | Yes |
| `GSpanCORK` | Frequent subgraph mining (gSpan) with CORK-based discriminative subgraph selection | Yes |
| `FSM` | Frequent Shape Motif encoder using ego-network structural signatures | No |

### Dictionary Learners

| Class | Description | Supervised | GPU |
|-------|-------------|------------|-----|
| `AKSVD` | Approximate K-SVD sparse dictionary learning | No | No |
| `OnlineDL` | Online dictionary learning via scikit-learn (Mairal et al.) | No | No |
| `LCKSVDLearner` | Label-Consistent K-SVD with discriminative sparse codes | Yes | No |
| `BayesianDLGPU` | Non-parametric Bayesian dictionary learning (Beta Process Factor Analysis) | No | Yes |
| `FrozenKSVDLearnerGPU` | Incremental frozen-dictionary K-SVD (Carroll et al. 2017) | Yes | Yes |
| `FDDLGPU` | Fisher Discrimination Dictionary Learning | Yes | Yes |
| `CSFDDLGPU` | Cost-Sensitive FDDL with class-rebalancing weights | Yes | Yes |

## Usage Examples

### Using a supervised encoder with a supervised dictionary learner

```python
from graph_dictlearn import SDFLoader, WL, LCKSVDLearner

loader = SDFLoader("molecules.sdf")
graphs, labels = loader.load()

encoder = WL(wl_iterations=2, selection="energy", energy=0.99)
embeddings = encoder.generate_training_embeddings(graphs, labels)

learner = LCKSVDLearner(dimensions=256, variant="lcksvd2", alpha=32.0, beta=2.0)
learner.fit(embeddings, y_train=labels)
sparse_codes = learner.infer(embeddings)
```

### Using a GPU-accelerated dictionary learner

```python
from graph_dictlearn import WL, BayesianDLGPU

# Encode (CPU)
encoder = WL(wl_iterations=2)
embeddings = encoder.generate_training_embeddings(graphs, labels)

# Learn dictionary (GPU)
learner = BayesianDLGPU(dimensions=32, n_iter=20, device="cuda")
learner.fit(embeddings)
sparse_codes = learner.infer(embeddings)
```

### Using the FSM encoder

```python
from graph_dictlearn import FSM, AKSVD

encoder = FSM(radius=1, n_vocab=1000, min_count=2)
embeddings = encoder.generate_training_embeddings(graphs)

learner = AKSVD(dimensions=16)
learner.fit(embeddings)
sparse_codes = learner.infer(embeddings)
```

### Inference on new data

```python
# After fitting the encoder and learner on training data
new_embeddings = encoder.generate_inferencing_embeddings(new_graphs)
new_sparse_codes = learner.infer(new_embeddings)
```

## Requirements

- Python >= 3.12
- Core: numpy, scipy, scikit-learn, networkx, gensim, rdkit, pandas, matplotlib, seaborn, joblib
- GPU learners: PyTorch >= 2.0 (install separately with CUDA support)

## License

MIT
