.. image:: https://raw.githubusercontent.com/giotto-ai/giotto-tda/master/doc/images/tda_logo.svg :width: 850

|Version|_ |Azure-build|_ |Azure-cov|_ |Azure-test|_ |Twitter-follow|_ |Slack-join|_

.. |Version| image:: https://img.shields.io/pypi/v/giotto-tda .. _Version:

.. |Azure-build| image:: https://dev.azure.com/maintainers/Giotto/_apis/build/status/giotto-ai.giotto-tda?branchName=master .. _Azure-build: https://dev.azure.com/maintainers/Giotto/_build?definitionId=6&_a=summary&repositoryFilter=6&branchFilter=141&requestedForFilter=ae4334d8-48e3-4663-af95-cb6c654474ea

.. |Azure-cov| image:: https://img.shields.io/azure-devops/coverage/maintainers/Giotto/6/master .. _Azure-cov:

.. |Azure-test| image:: https://img.shields.io/azure-devops/tests/maintainers/Giotto/6/master .. _Azure-test:

.. |Twitter-follow| image:: https://img.shields.io/twitter/follow/giotto_ai?label=Follow%20%40giotto_ai&style=social .. _Twitter-follow: https://twitter.com/intent/follow?screen_name=giotto_ai

.. |Slack-join| image:: https://img.shields.io/badge/Slack-Join-yellow .. _Slack-join: https://slack.giotto.ai/

========== giotto-tda

giotto-tda 是一个基于 scikit-learn 构建的高性能 Python 拓扑机器学习工具箱，采用 GNU AGPLv3 许可证进行分发。它是 Giotto <https://github.com/giotto-ai>_ 开源项目家族的一部分。

项目起源

giotto-tda 是由 L2F SA <https://www.l2f.ch/>、EPFL 的 拓扑与神经科学实验室 <https://www.epfl.ch/labs/hessbellwald-lab/> 以及 HEIG-VD 的 可重构与嵌入式数字系统研究所 (REDS) <https://heig-vd.ch/en/research/reds>_ 共同协作的成果。

许可证

.. _L2F team: business@l2f.ch

giotto-tda 采用 AGPLv3 许可证进行分发，许可证文本见：https://github.com/giotto-ai/giotto-tda/blob/master/LICENSE。如需其他分发许可，请联系 L2F 团队_。

文档

请访问 https://giotto-ai.github.io/gtda-docs <https://giotto-ai.github.io/gtda-docs>_，并导航至您感兴趣的版本。

安装

依赖项

giotto-tda 最新稳定版需要以下依赖：

• Python (>= 3.7)
• NumPy (>= 1.19.1)
• SciPy (>= 1.5.0)
• joblib (>= 0.16.0)
• scikit-learn (>= 0.23.1)
• pyflagser (>= 0.4.3)
• python-igraph (>= 0.8.2)
• plotly (>= 4.8.2)
• ipywidgets (>= 7.5.1)

运行示例还需要 Jupyter。

用户安装

安装 giotto-tda 最简单的方式是使用 pip ::

python -m pip install -U giotto-tda

如有必要，这也将自动安装上述所有依赖项。请注意：我们建议将 pip 升级到最新版本，因为在非常旧的版本上可能会失败。

包含近期新增功能和/或错误修复的预发布实验性版本可以通过以下命令安装： ::

python -m pip install -U giotto-tda-nightly

giotto-tda-nightly 与开发者安装版本（见下文“贡献”部分）的主要区别在于，前者以预编译的 wheel 包形式发布（与稳定版类似），因此不需要任何 C++ 依赖。由于稳定版和夜间版中的主库模块都称为 gtda，因此不应在同一环境中同时安装 giotto-tda 和 giotto-tda-nightly。

开发者安装

有关如何在不同平台上从源代码构建 giotto-tda 的详细说明，请参阅 专用页面 <https://giotto-ai.github.io/gtda-docs/latest/installation.html#developer-installation>_。

.. _contributing-section:

贡献

我们欢迎各经验水平的新贡献者。Giotto 社区的目标是提供帮助、友好且高效。如需了解更多关于为 giotto-tda 做出贡献的信息，请参阅 相关页面 <https://giotto-ai.github.io/gtda-docs/latest/contributing/index.html>_。

测试

完成开发者安装后，您可以在源代码目录之外启动测试套件： ::

pytest gtda

重要链接

• 官方源代码仓库：https://github.com/giotto-ai/giotto-tda
• 发布版本下载：https://pypi.org/project/giotto-tda/
• 问题跟踪器：https://github.com/giotto-ai/giotto-tda/issues

引用 giotto-tda

如果您在科学出版物中使用了 giotto-tda，我们非常感谢您引用以下论文：

giotto-tda：用于机器学习和数据探索的拓扑数据分析工具包 <https://www.jmlr.org/papers/volume22/20-325/20-325.pdf>_, Tauzin 等人, J. Mach. Learn. Res. 22.39 (2021): 1-6。

您可以使用以下 BibTeX 条目：

.. code:: bibtex

@article{giotto-tda,
  author  = {Guillaume Tauzin and Umberto Lupo and Lewis Tunstall and Julian Burella P\'{e}rez and Matteo Caorsi and Anibal M. Medina-Mardones and Alberto Dassatti and Kathryn Hess},
  title   = {giotto-tda: A Topological Data Analysis Toolkit for Machine Learning and Data Exploration},
  journal = {Journal of Machine Learning Research},
  year    = {2021},
  volume  = {22},
  number  = {39},
  pages   = {1-6},
  url     = {http://jmlr.org/papers/v22/20-325.html}
}

社区

giotto-ai Slack 工作区：https://slack.giotto.ai/

联系方式

maintainers@giotto.ai

giotto-tda 快速上手指南

giotto-tda 是一个基于 scikit-learn 构建的高性能拓扑机器学习（Topological Machine Learning）Python 工具箱，专为机器学习和数据探索设计。

环境准备

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

• 操作系统：支持 Linux、macOS 或 Windows（建议 Linux/macOS 以获得最佳性能）。
• Python 版本：>= 3.7
• 核心依赖：安装时会自动处理以下库的依赖关系：
  • NumPy (>= 1.19.1)
  • SciPy (>= 1.5.0)
  • scikit-learn (>= 0.23.1)
  • joblib, pyflagser, python-igraph, plotly, ipywidgets 等

提示：运行示例代码需要安装 jupyter。

安装步骤

1. 升级 pip（推荐）

为了避免在旧版本 pip 上安装失败，建议先升级包管理工具：

python -m pip install --upgrade pip

2. 安装稳定版

使用 pip 直接安装最新稳定版本，系统将自动安装所有必要的依赖项：

python -m pip install -U giotto-tda

国内加速建议：如果您在中国大陆地区，建议使用清华或阿里云镜像源以加快下载速度：

python -m pip install -U giotto-tda -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装开发版（可选）

如果需要体验最新功能或修复补丁，可安装夜间构建版（注意：不要与稳定版在同一环境中混用）：

python -m pip install -U giotto-tda-nightly

基本使用

giotto-tda 的 API 设计与 scikit-learn 高度一致，主要模块导入名为 gtda。以下是一个计算持久同调（Persistent Homology）并可视化条形码图的最简示例：

import numpy as np
from gtda.homology import VietorisRipsPersistence
from gtda.plotting import plot_diagram

# 1. 准备数据：生成一个简单的三维点云示例（圆环形状）
theta = np.linspace(0, 2 * np.pi, 100)
X = np.column_stack((np.cos(theta), np.sin(theta), np.zeros_like(theta)))
# 添加少量噪声
X += np.random.normal(0, 0.05, X.shape)

# 将数据转换为 gtda 需要的格式 (n_samples, n_points, n_dimensions)
X_gtda = X[np.newaxis, :, :]

# 2. 初始化变换器并拟合
vr = VietorisRipsPersistence(homology_dimensions=[0, 1])
diagrams = vr.fit_transform(X_gtda)

# 3. 可视化结果
plot_diagram(diagrams[0], show=True)

代码说明：

• VietorisRipsPersistence：用于计算点云的 Vietoris-Rips 复形及其持久同调。
• fit_transform：输入形状为 (n_samples, n_points, n_dimensions) 的数组，输出持久图（Persistence Diagrams）。
• plot_diagram：直接绘制持久图或条形码，直观展示数据的拓扑特征（如连通分量、孔洞等）。