模块化优化

词汇表

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

简介

模块化优化算法试图根据图的模块化来检测社区。模块化是衡量图结构的一种度量，它衡量模块或社区内部连接的密度。具有高模块化分数的图将在社区内部拥有许多连接，而只有少数连接指向其他社区。该算法将为每个节点探索，如果将其社区更改为其相邻节点之一，其模块化分数是否可能增加。

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

运行此算法需要足够的内存。在运行此算法之前，我们建议您阅读内存估算。

语法

按模式划分的模块化优化语法

在流模式下对命名图运行模块化优化。

CALL gds.modularityOptimization.stream(graphName: String, configuration: Map)
YIELD
  nodeId: Integer,
  communityId: Integer

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

表 2. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[1]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
maxIterations	整数	`10`	是	要运行的最大迭代次数。
tolerance	浮点数	`0.0001`	是	迭代之间模块化度的最小变化。如果模块化度变化小于容差值，则结果被认为是稳定的，算法返回。
seedProperty	字符串	`不适用`	是	用于定义初始标签集（必须是非负数）。
consecutiveIds	布尔值	`false`	是	标志，用于决定组件标识符是否映射到连续 ID 空间（需要额外内存）。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
minCommunitySize	整数	`0`	是	仅返回社区规模大于或等于给定值的节点。
1. 在 GDS 会话中，默认值为可用处理器数量。

表 3. 结果
名称	类型	描述
nodeId	整数	节点 ID
communityId	整数	社区 ID

在统计模式下对命名图运行模块化优化。

CALL gds.modularityOptimization.stats(graphName: String, configuration: Map)
YIELD
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  communityCount: Integer,
  communityDistribution: Map,
  modularity: Float,
  ranIterations: Integer,
  didConverge: Boolean,
  nodes: Integer,
  configuration: Map

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

表 5. 一般配置
名称	类型	默认值	可选	描述
concurrency	整数	`4 ^[2]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
communityProperty	字符串	`不适用`	否	存储每个节点的社区 ID（整数类型）的节点属性。请注意，只有非负社区 ID 才被视为有效，并会计算其模块化分数。
2. 在 GDS 会话中，默认值为可用处理器数量。

表 6. 算法特定配置
名称	类型	默认值	可选	描述
maxIterations	整数	10	是	要运行的最大迭代次数。
tolerance	浮点数	0.0001	是	迭代之间模块化度的最小变化。如果模块化度变化小于容差值，则结果被认为是稳定的，算法返回。
seedProperty	字符串	不适用	是	用于定义初始标签集（必须是非负数）。
consecutiveIds	布尔值	false	是	标志，用于决定组件标识符是否映射到连续 ID 空间（需要额外内存）。
relationshipWeightProperty	字符串	null	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。

表 7. 结果
名称	类型	描述
preProcessingMillis	整数	预处理数据所用的毫秒数。
computeMillis	整数	运行算法所用的毫秒数。
postProcessingMillis	整数	计算百分位数和社区计数所用的毫秒数。
nodes	整数	考虑的节点数量。
didConverge	布尔值	如果算法在提供的最大迭代次数内收敛到稳定的模块化分数，则为 True。
ranIterations	整数	运行的迭代次数。
modularity	浮点数	最终模块化分数。
communityCount	整数	找到的社区数量。
communityDistribution	映射	包含社区规模的最小值、最大值、平均值以及 50、75、90、95、99 和 999 百分位数。
配置	映射	用于运行算法的配置。

在变异模式下对命名图运行模块化优化。

CALL gds.modularityOptimization.mutate(graphName: String, configuration: Map})
YIELD
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  mutateMillis: Integer,
  communityCount: Integer,
  communityDistribution: Map,
  modularity: Float,
  ranIterations: Integer,
  didConverge: Boolean,
  nodes: Integer,
  configuration: Map

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

mutate 模式的配置与 write 模式类似。我们不需要指定 writeProperty，而是需要指定 mutateProperty。此外，在 mutate 模式下无法指定 writeConcurrency。

表 9. 结果
名称	类型	描述
preProcessingMillis	整数	预处理数据所用的毫秒数。
computeMillis	整数	运行算法所用的毫秒数。
mutateMillis	整数	将属性添加到投影图所用的毫秒数。
postProcessingMillis	整数	计算百分位数和社区计数所用的毫秒数。
nodes	整数	考虑的节点数量。
didConverge	布尔值	如果算法在提供的最大迭代次数内收敛到稳定的模块化分数，则为 True。
ranIterations	整数	运行的迭代次数。
modularity	浮点数	最终模块化分数。
communityCount	整数	找到的社区数量。
communityDistribution	映射	包含社区规模的最小值、最大值、平均值以及 50、75、90、95、99 和 999 百分位数。
配置	映射	用于运行算法的配置。

在写入模式下对命名图运行模块化优化。

CALL gds.modularityOptimization.write(graphName: String, configuration: Map})
YIELD
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  writeMillis: Integer,
  communityCount: Integer,
  communityDistribution: Map,
  modularity: Float,
  ranIterations: Integer,
  didConverge: Boolean,
  nodes: Integer,
  configuration: Map

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

表 11. 一般配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[3]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
writeConcurrency	整数	`“并发度”的值`	是	用于将结果写入 Neo4j 的并发线程数。
writeProperty	字符串	`不适用`	否	将社区写入 Neo4j 数据库的节点属性。
3. 在 GDS 会话中，默认值为可用处理器数量。

表 12. 算法特定配置
名称	类型	默认值	可选	描述
seedProperty	字符串	`不适用`	是	用于设置节点的初始社区。属性值必须是数字。
writeProperty	字符串	`不适用`	是	写回特定节点所属分区 ID 的属性名称。
maxIterations	整数	`10`	是	模块化优化在每个级别上运行的最大迭代次数。
tolerance	浮点数	`0.0001`	是	迭代之间模块化度的最小变化。如果模块化度变化小于容差值，则结果被认为是稳定的，算法返回。
consecutiveIds	布尔值	`false`	是	标志，用于决定组件标识符是否映射到连续 ID 空间（需要额外内存）。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
minCommunitySize	整数	`0`	是	仅将社区规模大于或等于给定值的社区 ID 写入 Neo4j。

表 13. 结果
名称	类型	描述
preProcessingMillis	整数	预处理数据所用的毫秒数。
computeMillis	整数	运行算法所用的毫秒数。
writeMillis	整数	写回结果数据所用的毫秒数。
postProcessingMillis	整数	计算百分位数和社区计数所用的毫秒数。
nodes	整数	考虑的节点数量。
didConverge	布尔值	如果算法在提供的最大迭代次数内收敛到稳定的模块化分数，则为 True。
ranIterations	整数	运行的迭代次数。
modularity	浮点数	最终模块化分数。
communityCount	整数	找到的社区数量。
communityDistribution	映射	包含社区规模的最小值、最大值、平均值以及 50、75、90、95、99 和 999 百分位数。
配置	映射	用于运行算法的配置。

示例

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

示例通常使用 Cypher 投影。原生投影将在未来版本中弃用。

考虑由以下 Cypher 语句创建的图：

CREATE
  (a:Person {name:'Alice'})
, (b:Person {name:'Bridget'})
, (c:Person {name:'Charles'})
, (d:Person {name:'Doug'})
, (e:Person {name:'Elton'})
, (f:Person {name:'Frank'})
, (a)-[:KNOWS {weight: 0.01}]->(b)
, (a)-[:KNOWS {weight: 5.0}]->(e)
, (a)-[:KNOWS {weight: 5.0}]->(f)
, (b)-[:KNOWS {weight: 5.0}]->(c)
, (b)-[:KNOWS {weight: 5.0}]->(d)
, (c)-[:KNOWS {weight: 0.01}]->(e)
, (f)-[:KNOWS {weight: 0.01}]->(d)

该图由两个中心节点“Alice”和“Bridget”组成，每个节点都有两个或更多邻居。此外，“Alice”的每个邻居都连接到“Bridget”的一个邻居。从关系的权重来看，可以发现两个中心节点与其邻居之间的连接非常强，而这些组之间的连接则很弱。因此，模块化优化算法应该检测出两个社区：“Alice”和“Bob”分别连同它们的邻居。

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

MATCH (source:Person)-[r:KNOWS]->(target:Person)
RETURN gds.graph.project(
  'myGraph',
  source,
  target,
  { relationshipProperties: r { .weight } },
  { undirectedRelationshipTypes: ['*'] }
)

内存估算

首先，我们将使用 estimate 过程估算运行算法的成本。这可以通过任何执行模式完成。在此示例中，我们将使用 write 模式。估算算法有助于了解在图上运行算法对内存的影响。当您稍后实际以某种执行模式运行算法时，系统将执行估算。如果估算表明执行超出内存限制的可能性非常高，则禁止执行。要了解更多信息，请参阅自动估算和执行阻止。

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

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

CALL gds.modularityOptimization.write.estimate('myGraph', { relationshipWeightProperty: 'weight', writeProperty: 'community' })
YIELD nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory

表 14. 结果
nodeCount	relationshipCount	bytesMin	bytesMax	requiredMemory
6	14	5160	5248	"[5160 字节 ... 5248 字节]"

流式

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

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

在流模式下运行模块化优化算法

CALL gds.modularityOptimization.stream('myGraph', { relationshipWeightProperty: 'weight' })
YIELD nodeId, communityId
RETURN gds.util.asNode(nodeId).name AS name, communityId
ORDER BY name

表 15. 结果
name	communityId
"Alice"	3
"Bridget"	1
"Charles"	1
"Doug"	1
"Elton"	3
"Frank"	3

统计

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

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

在统计模式下运行模块化优化算法

CALL gds.modularityOptimization.stats('myGraph', { relationshipWeightProperty: 'weight' })
YIELD nodes, communityCount, ranIterations, didConverge

表 16. 结果
nodes	communityCount	ranIterations	didConverge
6	2	2	true

写入

write 执行模式在 stats 模式的基础上扩展了一个重要的副作用：将每个节点的社区作为属性写入 Neo4j 数据库。新属性的名称通过强制配置参数 writeProperty 指定。结果是单行摘要，类似于 stats，但带有一些附加指标。 write 模式允许将结果直接持久化到数据库中。

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

在写入模式下运行模块化优化算法

CALL gds.modularityOptimization.write('myGraph', { relationshipWeightProperty: 'weight', writeProperty: 'community' })
YIELD nodes, communityCount, ranIterations, didConverge

表 17. 结果
nodes	communityCount	ranIterations	didConverge
6	2	2	true

当使用 write 模式时，该过程将返回有关算法执行的信息。在此示例中，我们返回已处理的节点数、分配给图中节点的社区数、迭代次数以及算法是否收敛的信息。

在不指定 relationshipWeightProperty 的情况下运行算法，将默认所有关系权重为 1.0。

变异

mutate 执行模式在 stats 模式的基础上扩展了一个重要的副作用：使用包含该节点社区的新节点属性更新命名图。新属性的名称通过强制配置参数 mutateProperty 指定。结果是单行摘要，类似于 stats，但带有一些附加指标。 mutate 模式在多个算法结合使用时特别有用。

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

在变异模式下运行模块化优化算法

CALL gds.modularityOptimization.mutate('myGraph', { relationshipWeightProperty: 'weight', mutateProperty: 'community' })
YIELD nodes, communityCount, ranIterations, didConverge

表 18. 结果
nodes	communityCount	ranIterations	didConverge
6	2	2	true

当使用 mutate 模式时，该过程将返回与 write 模式中相同的算法执行信息。