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
• scipy
• tqdm

Requires Python ≥ 3.10.

🧠 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

All three classes take the ranked lists as rks, either as the path to a .txt file with one ranked list per line (space-separated item IDs):

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

or directly in memory, as a list of lists (or an array) of item IDs in the same order, which 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)
rade = RaDE(rks="data/ranked_lists.txt", rks_size_L=20)  # same, from a file

Each list is a query, and each number is a retrieved item. Every list needs at least as many entries as the size requested (top_K for GRaCE, rks_size_L for RaDE and RaDE+). The former rks_path argument still works but is deprecated and will be removed in version 3.

RaDE Example

from interpretable_embeddings import RaDE

# Initialize
rade = RaDE(rks="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="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="data/ranked_lists.txt",
    top_K=20,
    correlation_measure="jacmax",  # or "reciprocal", "rbo"
    estimation_measure="reciprocal_density",  # or "accjacmax"
    alpha=0.95,  # Accumulated JacMax decay (only for estimation_measure="accjacmax")
    rbo_p=0.9,   # RBO persistence (only for correlation_measure="rbo")
)

# 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, RBO)

📄 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.

Castilho Almeida, T. C., Guimarães Pedronette, D. C. A Manifold-Aware Topic Modeling Approach via Rank-Based Prototypes Proceedings of the 2026 Conference on Empirical Methods in Natural Language Processing (EMNLP).

📚 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