🍇 GRAPE

|pip| |downloads| |tutorials| |documentation| |python_version| |license| |telegram| |discord| |twitter|

GRAPE（图表示学习、预测和评估）是一个快速图处理和嵌入库，旨在适应大型图并可在普通笔记本电脑和台式电脑以及高性能计算集群工作站上运行。

该库使用Rust和Python编程语言编写，由米兰大学计算机科学系的AnacletoLAB开发，与杰克逊基因组医学实验室的Robinson实验室以及劳伦斯伯克利国家实验室的BBOP合作完成。

该库由两个主要模块组成：Ensmallen（Rust/Python高性能图处理子模块）和Embiggen（Python图表示学习、预测和评估子模块）。

GRAPE的安装

像往常一样，只需通过运行以下命令从PyPi安装：

.. code:: shell

pip install grape

通常，安装不会超过一分钟。

可以为任何支持Rust和LLVM的操作系统、libc版本和CPU架构（如Arm、AArch64、RiscV、Mips）手动编译Ensmallen。如果需要帮助，请开一个issue。

库的主要功能

|features|

• 强大的图加载和图检索：
  • 80,000多个图
  • 支持多种图格式
  • 图特征的人类可读报告
• 60多个节点嵌入模型，易于集成第三方库。
  • DeepWalk、Walklets和基于Node2Vec的CBOW、SkipGram和GloVe，还支持度归一化！
  • 一阶和二阶LINE
  • Unstructured、Structured Embedding、TransE
  • 所有嵌入模型都有MMAPP版本，可支持非常大的嵌入
  • 所有嵌入模型都支持混合精度，允许使用16位浮点数进行嵌入
  • 集成了Karate Club和PyKEEN的模型
• 20多个分类器模型，易于集成第三方库。
  • 所有sklearn模型，适用于边预测、边标签预测和节点标签预测
  • 用于边预测、边标签预测和节点标签预测的GraphSAGE和Kipf GCN
  • 用于边预测的基线感知器
  • 集成支持在SLURM集群上并行化holdouts
• 图处理：如果NetworkX有的功能，我们很可能也有，而且速度更快！
  • Resnik、Jaccard、Ancestors Jaccard相似度
  • 直径、顶点覆盖、连通分量、三角形、方形、介数中心性、基于HyperBall的近似接近度和谐波中心性、精确接近度中心性和精确谐波中心性
  • 图属性过滤和图边的集合操作
• 图可视化工具
  • 嵌入的TSNE、UMAP、PCA
  • 边属性

教程

您可以在这里找到涵盖GRAPE库各个方面的教程。所有教程尽可能自包含，可以在COLAB上立即执行。

如果您认为任何示例可能有帮助，请随时开一个GitHub issue描述我们在本教程中缺少的内容。

文档

在线文档（目前正在更新）

库的在线文档可在此处获得。由于Ensmallen是用Rust编写的，而我们用于Python绑定的PyO3不支持类型注解，因此文档是通过生成空的骨架包获得的。这允许有适当的文档，但您将无法在其中看到源代码。

使用自动方法建议工具
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
为了帮助使用该库，GRAPE提供了一个集成的推荐系统，旨在帮助您找到方法或在方法因任何原因被重命名时找到其新名称。

例如，在加载STRING人类图后，可以通过简单地输入components来检索计算连通分量的函数，如下所示：

.. code:: python

    from grape.datasets.string import HomoSapiens

    graph = HomoSapiens()
    graph.components

上述代码将引发以下错误，并会建议具有相似或相关名称的方法：

.. code-block:: python

    AttributeError                            Traceback (most recent call last)
    <ipython-input-3-52fac30ac7f6> in <module>()
    ----> 2 graph.components
AttributeError: 'components'方法不存在，你是否想使用以下方法之一？
    * 'remove_components'
    * 'connected_components'
    * 'strongly_connected_components'
    * 'get_connected_components_number'
    * 'get_total_edge_weights'
    * 'get_mininum_edge_weight'
    * 'get_maximum_edge_weight'
    * 'get_unchecked_maximum_node_degree'
    * 'get_unchecked_minimum_node_degree'
    * 'get_weighted_maximum_node_degree'

在我们的示例中，计算图的连通分量所需的方法是`connected_components`。

获取方法文档最简单的方法是使用Python的`help <https://docs.python.org/3/library/functions.html#help>`_，如下所示：

.. code:: python

    help(graph.connected_components)

上述代码将返回以下内容：

.. code-block:: rst

    connected_components(verbose) 方法，属于builtins.Graph实例
    使用[bader算法](https://www.sciencedirect.com/science/article/abs/pii/S0743731505000882)并行构建生成树来计算连通分量。
    
    **此方法仅适用于无向图。**
    
    返回的四元组包含：
    - 每个节点的连通分量向量。
    - 连通分量的数量。
    - 最小连通分量的大小。
    - 最大连通分量的大小。
    
    参数
    ----------
    verbose: Optional[bool]
        是否显示加载进度条。
    
    
    异常
    -------
    ValueError
        如果给定的图是有向图。
    ValueError
        如果系统配置不允许创建线程池。


引用GRAPE
----------------------------------------------
如果对您的研究有用，请引用以下论文：

.. code:: bib

    @article{cappelletti2023grape,
      title={GRAPE for Fast and Scalable Graph Processing and random walk-based Embedding}, 
      author={Cappelletti, L. and Fontana, T. and Casiraghi, E. and Ravanmehr, V. and  Callahan, T.J. and  Cano, C. and Joachimiak, M.P. and Mungall, C.J. and Robinson, P.N. and Reese, J. and Valentini, G.},
      year={2023},
      doi={10.1038/s43588-023-00465-8},
      journal={Nature Computational Science}}