interpretable-embeddings

interpretable-embeddings is the official implementation of RaDE, RaDE+, and GRaCE algorithms for generating rank-based interpretable and contextual embeddings from top-K similarity lists.

This package implements the RaDE, RaDE+, and GRaCE algorithms, which use graph-based measures to create interpretable, effective, and unsupervised embeddings for retrieval, clustering, classification, and visualization.

🔍 Overview

Unlike traditional embedding techniques that require raw features or supervised training, this package builds representations entirely from ranked similarity lists (e.g., from a kNN graph or retrieval system). Each embedding dimension corresponds to a similarity measure with the "leaders" (reference node).

Key benefits:

• Unsupervised: No labels or ground truth needed.
• Interpretable: Embedding dimensions are human-understandable.
• Versatile: Works for text, images, graphs—any domain with top-K similarities.

📦 Installation

pip install interpretable-embeddings

Dependencies:

• numpy
• tqdm

Requires Python ≥ 3.7.

🧠 Algorithms

RaDE (Rank-based Diffusion Embedding)

• Selects leaders by propagating rank-based affinities through a diffusion process. Each embedding dimension encodes the affinity to a single representative node.

RaDE+ (Multi-Representative RaDE)

• Extends RaDE by expanding each representative node into an expansion set of similar nodes (Algorithm 1 from the paper). Each embedding dimension aggregates affinities over the expansion set with linearly decreasing weights, producing more robust and diversified representations.

GRaCE (Graph and Rank-based Contextual Embeddings)

• Extends RaDE with unsupervised effectiveness estimation (e.g., Reciprocal Density, Accumulated JacMax) and rank correlation measures (e.g., Reciprocal Distance, JacMax).

🛠 Usage

Input Format

Your input must be a .txt file with one ranked list per line (space-separated item IDs):

15 3 8 22 7 9 ...
3 2 11 5 6 ...
...

Each line is a query, and each number is a retrieved item.

Alternatively, pass the ranked lists directly in memory with rks= — a list of lists of item IDs, in the same order. This skips the disk round-trip when the lists are already available:

rks = [
    [15, 3, 8, 22, 7, 9],
    [3, 2, 11, 5, 6],
    ...
]

rade = RaDE(rks=rks, rks_size_L=20)

All three classes accept either rks_path or rks; supplying neither raises ValueError.

RaDE Example

from interpretable_embeddings import RaDE

# Initialize
rade = RaDE(rks_path="data/ranked_lists.txt", rks_size_L=20)

# Compute internal structure
rade.fit(num_candidates=1000, num_leaders=128, t=2)

# Get embedding vectors
embeddings = rade.transform()

# Or do both in one call
embeddings = rade.fit_transform(num_candidates=1000, num_leaders=128, t=2)

RaDE+ Example

from interpretable_embeddings import RaDEPlus

rade_plus = RaDEPlus(rks_path="data/ranked_lists.txt", rks_size_L=20)

# Compute internal structure
rade_plus.fit(num_candidates=1000, num_leaders=128, t=2, m=3)

# Get embedding vectors
embeddings = rade_plus.transform()

# Or do both in one call
embeddings = rade_plus.fit_transform(num_candidates=1000, num_leaders=128, t=2, m=3)

Parameters:

• num_candidates: size of the candidate pool (top-k nodes by reciprocal affinity).
• num_leaders: embedding dimensionality (number of representative nodes).
• t: diffusion steps for the transition matrix A = W^t.
• m: number of nodes added to each leader's expansion set. Constraint: m * num_leaders ≤ num_candidates.

GRaCE Example

from interpretable_embeddings import GRaCE

grace = GRaCE(
    rks_path="data/ranked_lists.txt",
    top_K=20,
    correlation_measure="jacmax",  # or "reciprocal"
    estimation_measure="reciprocal_density",  # or "accjacmax"
    alpha=0.95
)

# Compute internal structure
grace.fit(num_leaders=128)

# Get embedding vectors
embeddings = grace.transform()

# Or do both in one call
embeddings = grace.fit_transform(num_leaders=128)

🔬 Example Applications

Retrieval

from sklearn.metrics.pairwise import cosine_similarity

query_idx = 0
sims = cosine_similarity(embeddings)
top_k = sims[query_idx].argsort()[::-1][1:11]
print("Top-10 results for query:", top_k)

Clustering

from sklearn.cluster import KMeans

kmeans = KMeans(n_clusters=5).fit(embeddings)
print(kmeans.labels_)

Classification

from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split

X_train, X_test, y_train, y_test = train_test_split(embeddings, labels)
clf = LogisticRegression(max_iter=1000).fit(X_train, y_train)
print("Accuracy:", clf.score(X_test, y_test))

Visualization

from sklearn.manifold import TSNE
import matplotlib.pyplot as plt

proj = TSNE(n_components=2).fit_transform(embeddings)
plt.scatter(proj[:, 0], proj[:, 1], c=labels, cmap="tab10")
plt.title("2D Visualization of RaDE Embeddings")
plt.show()

📁 Package Structure

interpretable-embeddings/
│
├── rade.py                 # RaDE implementation
├── rade_plus.py            # RaDE+ implementation (multi-representative)
├── grace.py                # GRaCE implementation
├── utils.py                # Ranked list reader
└── measures/
    ├── qpp.py              # Query performance prediction measures (AccJacMax, Reciprocal Density)
    └── correlation.py      # Rank correlation measures (JacMax, Reciprocal KNN)

📄 Relevant Papers Using RaDE and GRaCE

Castilho Almeida, T. C., Rosseto Letício, G., Sato Kawai, V. A., Guimarães Pedronette, D. C. Context-Aware Interpretable Representations for Retrieval and Graph Convolutional Network Classification Proceedings of the 2026 International Conference on Multimedia Retrieval (ICMR '26), pp. 1092–1101.

📚 Citation

If you use this package in your research, please cite:

GRaCE

Almeida, T. C. C., Letício, G. R., Valem, L. P., Freitas, A., Pedronette, D. C. G. Effective Graph and Rank-based Contextual Embeddings for Textual and Multimedia Data 2025 International Joint Conference on Neural Networks (IJCNN), Rome – Italy.

RaDE / RaDE+

De Fernando, F. A., Pedronette, D. C. G., De Sousa, G. J., Valem, L. P., Guilherme, I. R. RaDE+: A semantic rank-based graph embedding algorithm International Journal of Information Management Data Insights, 2(2), 100078, 2022.

De Fernando, F. A., Pedronette, D. C. G., De Sousa, G. J., Valem, L. P., Guilherme, I. R. RaDE: A Rank-based Graph Embedding Approach 15th International Conference on Computer Vision Theory and Applications (VISAPP), 2020.

🤝 Contact

• Thiago César Castilho Almeida: tc.almeida@unesp.br
• Lucas Pascotti Valem: lucaspascottivalem@gmail.com
• Daniel Carlos Guimarães Pedronette: pedronette@gmail.com