PyMDE

PyMDE 的官方文档可在 www.pymde.org 上找到。

此仓库与专著 最小失真嵌入 配套使用。

PyMDE 是一个用于为有限集合中的项目（如图像、生物细胞、网络节点或其他抽象对象）计算向量嵌入的 Python 库。

通用框架。 PyMDE 与其他嵌入库的不同之处在于，它提供了一个简单而通用的嵌入框架，称为 最小失真嵌入 (MDE)。借助 MDE，您可以轻松地重现已知的嵌入方法，并根据您的特定应用创建新的嵌入。

CPU 上速度快，GPU 上更快。 PyMDE 在运行时性能上可与更专业的嵌入方法相媲美。在 GPU 上，嵌入计算的速度甚至更快。

用 Rust 实现的快速预处理。 PyMDE 使用用 Rust 实现的高效例程对原始数据矩阵进行预处理：

• 一种近似 k 最近邻算法，实现了 nndescent，其性能可与 pynndescent 相媲美，但没有 Numba 的 JIT 开销；
• 一种精确的 k 最近邻算法，在现代机器上通常非常快速；
• 一种广度优先搜索算法，用于计算所有点对之间的最短路径。

概述

PyMDE 既适合初学者，也适合专家。它可以用于：

• 可视化小型或大型数据集；
• 为监督学习生成特征向量；
• 压缩高维向量数据；
• 绘制图（比 NetworkX 等工具快几个数量级）；
• 创建自定义嵌入，带有自定义目标函数和约束条件（例如使特征列不相关）；
• 以及其他用途。

PyMDE 是一款非常年轻的软件，目前仍在积极开发中。如果您遇到任何问题或有任何反馈，请通过 提交 GitHub 问题 与我们联系。

本 README 提供了 PyMDE 的简要概述。请务必阅读位于 www.pymde.org 的官方文档，其中包含深入的教程和 API 文档。

• 安装
• 入门
• 示例笔记本
• 引用

安装

PyMDE 可在 Python 包索引 (PyPI) 和 Conda Forge 上获取。

使用 pip 安装：

pip install pymde

或者使用 conda 安装：

conda install -c pytorch -c conda-forge pymde

PyMDE 的依赖项如下：

• Python >= 3.7
• numpy >= 1.17.5
• scipy
• torch >= 1.7.1
• torchvision >= 0.8.2
• requests

可选依赖项

• pynndescent：用于高效地在稀疏矩阵上计算 k 最近邻。在大多数情况下，这并不是必需的。

入门

使用 PyMDE 很容易。对于开箱即用的嵌入，我们提供了两个主要函数：

pymde.preserve_neighbors

该函数保留原始数据的局部结构，以及

pymde.preserve_distances

该函数保留原始数据中的成对距离或相异性评分。

参数。 这些函数的输入是原始数据，可以表示为每行是一个特征向量的数据矩阵，也可以表示为编码成对距离的（可能稀疏的）图。嵌入维度由 embedding_dim 关键字参数指定，默认值为 2。

返回值。 返回值是一个 MDE 对象。调用该对象上的 embed() 方法会返回一个嵌入，即一个矩阵 (torch.Tensor)，其中每行是一个嵌入向量。例如，如果原始输入是形状为 (n_items, n_features) 的数据矩阵，则嵌入矩阵的形状为 (n_items, embedding_dim)。

我们将在下面给出这些函数的使用示例。

保留邻居

以下代码以类似于 LargeVis、t-SNE、UMAP 等基于邻域的嵌入方式，对 MNIST 数据集（手写数字图像）进行嵌入。原始数据是一个形状为 (70000, 784) 的矩阵，每行代表一张图像。

import pymde

mnist = pymde.datasets.MNIST()
embedding = pymde.preserve_neighbors(mnist.data, verbose=True).embed()
pymde.plot(embedding, color_by=mnist.attributes['digits'])

与大多数其他嵌入方法不同，PyMDE 可以计算满足约束条件的嵌入。例如：

embedding = pymde.preserve_neighbors(mnist.data, constraint=pymde.Standardized(), verbose=True).embed()
pymde.plot(embedding, color_by=mnist.attributes['digits'])

标准化约束确保嵌入向量居中，并且特征之间不相关。

保留距离

当您更关注保留整体全局结构而非局部结构时，pymde.preserve_distances 函数非常有用。

以下是一个示例，展示了如何对来自 Google 学术搜索的学术合著网络进行嵌入。原始数据是一个关于约 40,000 名作者的稀疏图，如果两位作者至少合作发表过一篇论文，则他们之间有一条边。

import pymde

google_scholar = pymde.datasets.google_scholar()
embedding = pymde.preserve_distances(google_scholar.data, verbose=True).embed()
pymde.plot(embedding, color_by=google_scholar.attributes['coauthors'], color_map='viridis', background_color='black')

合作更多的作者颜色更亮，且位于嵌入的中心附近。

示例笔记本

我们有几个 示例笔记本，展示了如何在真实（和合成）数据集上使用 PyMDE。

引用

若需引用我们的工作，请使用以下 BibTex 条目。

@article{agrawal2021minimum,
  author  = {Agrawal, Akshay and Ali, Alnur and Boyd, Stephen},
  title   = {Minimum-Distortion Embedding},
  journal = {arXiv},
  year    = {2021},
}

PyMDE 由 Akshay Agrawal 设计并开发。

PyMDE 快速上手指南

PyMDE 是一个用于计算有限项集（如图像、生物细胞、网络节点等）向量嵌入的 Python 库。它基于“最小失真嵌入”（Minimum-Distortion Embedding, MDE）框架，支持在 CPU 和 GPU 上高效运行，并能通过自定义约束生成特定应用的嵌入。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS, 或 Windows
• Python 版本：>= 3.7
• 核心依赖：
  • numpy >= 1.17.5
  • scipy
  • torch >= 1.7.1 (PyTorch)
  • torchvision >= 0.8.2
  • requests
• 可选依赖：pynndescent（用于稀疏矩阵的高效 k-近邻计算，大多数情况下非必需）

提示：PyMDE 底层使用 Rust 进行数据预处理以获得更快的速度，安装时会自动处理相关二进制文件。

安装步骤

您可以选择通过 pip 或 conda 进行安装。国内用户建议使用清华或阿里镜像源以加速下载。

方式一：使用 pip 安装

pip install pymde -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 conda 安装

conda install -c pytorch -c conda-forge pymde

(注：Conda 安装通常会自动解析 PyTorch 依赖，若需指定国内源可在命令后添加 --channel https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/ 等)

基本使用

PyMDE 提供了两个开箱即用的主要函数：

1. pymde.preserve_neighbors：保留数据的局部结构（类似 t-SNE, UMAP）。
2. pymde.preserve_distances：保留数据的全局成对距离或相异度。

以下是最简单的使用示例，演示如何对 MNIST 手写数字数据集进行嵌入并可视化。

示例：保留邻居结构 (Preserve Neighbors)

此代码将高维图像数据映射到 2D 空间，并保持相似的图像在空间中相邻。

import pymde

# 加载内置的 MNIST 数据集
mnist = pymde.datasets.MNIST()

# 生成嵌入：默认维度为 2，verbose=True 显示进度
# 返回一个 MDE 对象，调用 .embed() 获取结果矩阵 (torch.Tensor)
embedding = pymde.preserve_neighbors(mnist.data, verbose=True).embed()

# 可视化结果，按数字标签着色
pymde.plot(embedding, color_by=mnist.attributes['digits'])

进阶：添加约束

PyMDE 的独特之处在于支持在嵌入过程中添加约束。例如，使用 Standardized() 约束可以使嵌入向量居中且特征不相关。

import pymde

mnist = pymde.datasets.MNIST()

# 添加标准化约束
embedding = pymde.preserve_neighbors(
    mnist.data, 
    constraint=pymde.Standardized(), 
    verbose=True
).embed()

pymde.plot(embedding, color_by=mnist.attributes['digits'])

示例：保留距离 (Preserve Distances)

如果您更关注全局结构（例如学术合作网络），可以使用此函数。

import pymde

# 加载 Google Scholar 合作者网络数据
google_scholar = pymde.datasets.google_scholar()

# 生成保留距离的嵌入
embedding = pymde.preserve_distances(google_scholar.data, verbose=True).embed()

# 可视化：合作越多的作者颜色越亮，通常位于中心
pymde.plot(
    embedding, 
    color_by=google_scholar.attributes['coauthors'], 
    color_map='viridis', 
    background_color='black'
)

更多详细教程和 API 文档请访问官方站点：www.pymde.org。