HDBSCAN

术语表

有向: 有向特征。该算法在有向图上定义良好。
有向: 有向特征。该算法忽略图的方向。
有向: 有向特征。该算法不能在有向图上运行。
无向: 无向特征。该算法在无向图上定义良好。
无向: 无向特征。该算法忽略图的无向性。
异构节点: 异构节点完全支持。该算法有能力区分不同类型的节点。
异构节点: 异构节点允许。该算法平等对待所有选定的节点，无论其标签如何。
异构关系: 异构关系完全支持。该算法有能力区分不同类型的关系。
异构关系: 异构关系允许。该算法平等对待所有选定的关系，无论其类型如何。
加权关系: 加权特征。该算法支持将关系属性用作权重，通过 relationshipWeightProperty 配置参数指定。
加权关系: 加权特征。该算法将每个关系视为同等重要，忽略任何关系权重值。
节点属性: 节点属性特征。该算法使用节点属性。

简介

HDBSCAN 全称为“基于密度的带噪声空间聚类层次算法”(Hierarchical Density-Based Spatial Clustering of Applications with Noise)，是一种用于识别数据集中相似数据点聚类的算法。它建立在 DBSCAN 算法基础之上，并增加了层次结构，使其对数据中不同的密度更具鲁棒性。

与 DBSCAN 不同，HDBSCAN 不需要调整特定的密度参数；相反，它会在一系列参数上运行 DBSCAN，从而创建聚类的层次结构。这种层次化方法使得 HDBSCAN 能够发现不同密度的聚类，并更具适应现实世界数据的能力。

HDBSCAN 以其易用性、噪声容忍度以及处理不同密度数据的能力而闻名，使其成为聚类任务的多功能工具，尤其是在处理复杂的高维数据集时。

有关此算法的更多信息，请参阅

HDBSCAN：基于位置服务的密度聚类

注意事项

为了使 HDBSCAN 正常工作，所有节点的属性数组必须具有相同数量的元素。此外，它们必须仅包含数字，且不能包含任何 NaN 值。

语法

HDBSCAN 各模式语法

在命名图上以流 (stream) 模式运行 HDBSCAN。

CALL gds.hdbscan.stream(
  graphName: String,
  configuration: Map
)
YIELD
  nodeId: Integer,
  label: Integer

表 1. 参数
名称	类型	默认	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
配置	Map	`{}`	是	算法特定配置和/或图过滤配置。

表 2. 配置
名称	类型	默认	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4 ^[1]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可以提供一个 ID 以更轻松地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，进度百分比将不会被记录。
nodeProperty	字符串	`不适用`	否	对应一个浮点数数组的节点属性，HDBSCAN 使用该属性来计算聚类。
minClusterSize (最小聚类大小)	整数	`5`	是	一个聚类应包含的最小节点数。
samples (样本数)	整数	`10`	是	计算节点核心距离时要考虑的邻居数量。
leafSize (叶子节点大小)	整数	`1`	是	支撑树数据结构的叶子节点数量。
1. 在 GDS 会话中，默认值为可用处理器的数量。

表 3. 结果
名称	类型	描述
nodeId	整数	节点 ID。
标签 (label)	整数	标签 ID，如果节点被视为 `噪声`，则为 `-1`。

在命名图上以统计 (stats) 模式运行 HDBSCAN。

CALL gds.hdbscan.stats(
  graphName: String,
  configuration: Map
)
YIELD
  nodeCount: Integer,
  numberOfClusters: Integer,
  numberOfNoisePoints: Integer,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  configuration: Map

表 4. 参数
名称	类型	默认	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
配置	Map	`{}`	是	算法特定配置和/或图过滤配置。

表 5. 配置
名称	类型	默认	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4 ^[2]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可以提供一个 ID 以更轻松地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，进度百分比将不会被记录。
nodeProperty	字符串	`不适用`	否	对应一个浮点数数组的节点属性，HDBSCAN 使用该属性来计算聚类。
minClusterSize (最小聚类大小)	整数	`5`	是	一个聚类应包含的最小节点数。
samples (样本数)	整数	`10`	是	计算节点核心距离时要考虑的邻居数量。
leafSize (叶子节点大小)	整数	`1`	是	支撑树数据结构的叶子节点数量。
2. 在 GDS 会话中，默认值为可用处理器的数量。

表 6. 结果
名称	类型	描述
nodeCount	整数	算法运行的节点数量。
numberOfClusters (聚类数量)	整数	算法发现的聚类数量。
numberOfNoisePoints (噪声点数量)	整数	算法发现的噪声点数量。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
postProcessingMillis	整数	计算百分位数和社区数量所需的毫秒数。
配置	Map	用于运行算法的配置。

在命名图上以变异 (mutate) 模式运行 HDBSCAN。

CALL gds.hdbscan.mutate(
  graphName: String,
  configuration: Map
)
YIELD
  nodeCount: Integer,
  numberOfClusters: Integer,
  numberOfNoisePoints: Integer,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  mutateMillis: Integer,
  nodePropertiesWritten: Integer,
  configuration: Map

表 7. 参数
名称	类型	默认	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
配置	Map	`{}`	是	算法特定配置和/或图过滤配置。

表 8. 配置
名称	类型	默认	可选	描述
mutateProperty	字符串	`不适用`	否	GDS 图中写入聚类结果的节点属性。
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
logProgress	布尔值	`true`	是	如果禁用，进度百分比将不会被记录。
jobId	字符串	`内部生成`	是	可以提供一个 ID 以更轻松地跟踪算法的进度。
nodeProperty	字符串	`不适用`	否	对应一个浮点数数组的节点属性，HDBSCAN 使用该属性来计算聚类。
minClusterSize (最小聚类大小)	整数	`5`	是	一个聚类应包含的最小节点数。
samples (样本数)	整数	`10`	是	计算节点核心距离时要考虑的邻居数量。
leafSize (叶子节点大小)	整数	`1`	是	支撑树数据结构的叶子节点数量。

表 9. 结果
名称	类型	描述
nodeCount	整数	算法运行的节点数量。
numberOfClusters (聚类数量)	整数	算法发现的聚类数量。
numberOfNoisePoints (噪声点数量)	整数	算法发现的噪声点数量。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
mutateMillis	整数	向投影图添加属性的毫秒数。
postProcessingMillis	整数	计算百分位数和社区数量所需的毫秒数。
nodePropertiesWritten	整数	添加到投影图中的属性数量。
配置	Map	用于运行算法的配置。

在命名图上以写入 (write) 模式运行 HDBSCAN。

CALL gds.hdbscan.write(
  graphName: String,
  configuration: Map
)
YIELD
  nodeCount: Integer,
  numberOfClusters: Integer,
  numberOfNoisePoints: Integer,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  writeMillis: Integer,
  nodePropertiesWritten: Integer,
  configuration: Map

表 10. 参数
名称	类型	默认	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
配置	Map	`{}`	是	算法特定配置和/或图过滤配置。

表 11. 配置
名称	类型	默认	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4 ^[3]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可以提供一个 ID 以更轻松地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，进度百分比将不会被记录。
writeConcurrency	整数	`'concurrency' 的值`	是	用于将结果写入 Neo4j 的并发线程数。
writeProperty	字符串	`不适用`	否	Neo4j 数据库中写入聚类结果的节点属性。
nodeProperty	字符串	`不适用`	否	对应一个浮点数数组的节点属性，HDBSCAN 使用该属性来计算聚类。
minClusterSize (最小聚类大小)	整数	`5`	是	一个聚类应包含的最小节点数。
samples (样本数)	整数	`10`	是	计算节点核心距离时要考虑的邻居数量。
leafSize (叶子节点大小)	整数	`1`	是	支撑树数据结构的叶子节点数量。
3. 在 GDS 会话中，默认值为可用处理器的数量。

表 12. 结果
名称	类型	描述
nodeCount	整数	算法运行的节点数量。
numberOfClusters (聚类数量)	整数	算法发现的聚类数量。
numberOfNoisePoints (噪声点数量)	整数	算法发现的噪声点数量。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
writeMillis	整数	向 Neo4j 数据库添加属性所需的毫秒数。
postProcessingMillis	整数	计算百分位数和社区数量所需的毫秒数。
nodePropertiesWritten	整数	添加到投影图中的属性数量。
配置	Map	用于运行算法的配置。

示例

以下所有示例应在空数据库中运行。

这些示例将 Cypher 投影作为规范。原生投影将在未来版本中弃用。

在本节中，我们将展示在具体图上运行 HDBSCAN 算法的示例。目的是说明结果的样子，并提供如何在实际场景中使用该算法的指南。我们将使用一个小型的城市图，其中包含以特定模式连接的少数节点。示例图如下所示

以下 Cypher 语句将在 Neo4j 数据库中创建示例图：

CREATE
  (:City {name: 'Surbiton', coordinates: [51.39148, -0.29825]}),
  (:City {name: 'Liverpool', coordinates: [53.41058, -2.97794]}),
  (:City {name: 'Kingston upon Thames', coordinates: [51.41259, -0.2974]}),
  (:City {name: 'Sliven', coordinates: [42.68583, 26.32917]}),
  (:City {name: 'Solna', coordinates: [59.36004, 18.00086]}),
  (:City {name: 'Örkelljunga', coordinates: [56.28338, 13.27773]}),
  (:City {name: 'Malmö', coordinates: [55.60587, 13.00073]}),
  (:City {name: 'Xánthi', coordinates: [41.13488, 24.888]});

该图由各种 城市 (City) 节点组成，位于三个全球地点——英国、瑞典和欧洲的巴尔干地区。

现在我们可以投影该图并将其存储在图目录中。我们加载带有 coordinates（坐标）节点属性的 City 节点标签。

以下语句将投影图并将其存储在图目录中。

MATCH (c:City)
RETURN gds.graph.project(
  'cities',
  c,
  null,
  {
    sourceNodeProperties: c { .coordinates },
    targetNodeProperties: {}
  }
)

在接下来的示例中，我们将演示如何在此时图上使用 HDBSCAN 算法，以找到地理位置彼此靠近的城市群。

内存估算

首先，我们将使用 estimate 过程估算运行算法的成本。这可以在任何执行模式下完成。在这个例子中我们将使用 write 模式。估算算法有助于了解在您的图上运行该算法将产生的内存影响。当您随后在其中一种执行模式下真正运行算法时，系统将执行一次估算。如果估算显示执行超出其内存限制的可能性非常高，则禁止执行。要阅读更多关于此的内容，请参阅自动估算和执行阻塞。

有关 estimate 的更多详细信息，请参阅内存估算。

以下内容将估算运行算法所需的内存

CALL gds.hdbscan.write.estimate('cities', {
  writeProperty: 'label',
  nodeProperty: 'coordinates'
})
YIELD nodeCount, bytesMin, bytesMax, requiredMemory

表 13. 结果
nodeCount	bytesMin	bytesMax	requiredMemory
8	9920	9920	"9920 字节"

流 (Stream)

在 stream 执行模式下，算法返回每个节点的聚类结果。这允许我们直接检查结果或在 Cypher 中对其进行后处理，而不会产生任何副作用。

有关 stream 模式的更多详细信息，请参阅流式读取。

以下命令将运行算法并流式传输结果

CALL gds.hdbscan.stream('cities', {
  nodeProperty: 'coordinates',
  minClusterSize: 2,
  samples: 2
})
YIELD nodeId, label
RETURN gds.util.asNode(nodeId).name AS name, label
ORDER BY label, name ASC

表 14. 结果
名称 (name)	标签 (label)
"Sliven" (斯利文)	-1
"Xánthi" (克桑西)	-1
"Kingston upon Thames" (泰晤士河畔金斯顿)	1
"Liverpool" (利物浦)	1
"Surbiton" (瑟比顿)	1
"Malmö" (马尔默)	2
"Solna" (索尔纳)	2
"Örkelljunga" (厄尔克尔永加)	2

在上面的示例中，我们可以看到城市在地理上聚集在一起。

统计 (Stats)

在 stats 执行模式下，算法返回包含算法结果摘要的单行数据。此执行模式没有任何副作用。通过检查 computeMillis 返回项来评估算法性能非常有用。在下面的示例中，我们将省略返回计时信息。该过程的完整签名可以在语法部分找到。

有关 stats 模式的更多详细信息，请参阅统计。

以下命令将运行算法并以统计和测量值的形式返回结果

CALL gds.hdbscan.stats('cities', {
  nodeProperty: 'coordinates',
  minClusterSize: 2,
  samples: 2
})
YIELD nodeCount, numberOfClusters, numberOfNoisePoints

表 15. 结果
nodeCount	numberOfClusters (聚类数量)	numberOfNoisePoints (噪声点数量)
8	2	2

变异 (Mutate)

mutate 执行模式扩展了 stats 模式，并具有一个重要的副作用：使用包含该节点聚类的新节点属性来更新命名图。新属性的名称使用强制配置参数 mutateProperty 指定。结果是单行汇总行，类似于 stats，但带有一些额外的指标。当多个算法结合使用时，mutate 模式特别有用。

有关 mutate 模式的更多详细信息，请参阅变更。

以下代码将运行算法并将结果存储在 cities 图中

CALL gds.hdbscan.mutate('cities', {
  nodeProperty: 'coordinates',
  minClusterSize: 2,
  samples: 2,
  mutateProperty: 'label'
})
YIELD nodeCount, numberOfClusters, nodePropertiesWritten, numberOfNoisePoints

表 16. 结果
nodeCount	numberOfClusters (聚类数量)	nodePropertiesWritten	numberOfNoisePoints (噪声点数量)
8	2	8	2

在 mutate 模式下，该过程仅返回一行。结果被写入 GDS 内存图，而不是 Neo4j 数据库。

写入 (Write)

write 执行模式扩展了 stats 模式，并具有一个重要的副作用：将每个节点的聚类作为属性写入 Neo4j 数据库。新属性的名称使用强制配置参数 writeProperty 指定。结果是单行汇总行，类似于 stats，但带有一些额外的指标。write 模式支持将结果直接持久化到数据库中。

有关 write 模式的更多详细信息，请参阅写入。

以下代码将运行算法并将结果写回 Neo4j

CALL gds.hdbscan.write('cities', {
  nodeProperty: 'coordinates',
  minClusterSize: 2,
  samples: 2,
  writeProperty: 'label'
})
YIELD nodeCount, numberOfClusters, nodePropertiesWritten, numberOfNoisePoints

表 17. 结果
nodeCount	numberOfClusters (聚类数量)	nodePropertiesWritten	numberOfNoisePoints (噪声点数量)
8	2	8	2

在 write 模式下，该过程仅返回一行。结果被写入 Neo4j 数据库，而不是 GDS 内存图。