比例属性

简介

比例属性算法是一个实用程序算法，用于预处理节点属性以进行模型训练或后处理算法结果（例如 PageRank 分数）。它根据指定的缩放器对节点属性进行缩放。可以一次缩放多个属性，并将其返回到列表属性中。

输入属性必须是数字或数字列表。所有列表必须具有相同的大小。输出属性始终为列表。输出列表的大小等于输入属性长度的总和。也就是说，如果输入属性是两个标量数值属性和一个长度为 3 的列表属性，则输出列表的总长度为 5。

如果节点缺少某个属性的值，则该节点将被从该属性的缩放中排除。它将接收 NaN 的输出值。这包括列表属性。

比例属性算法支持许多缩放器。这些可以通过 scaler 配置参数进行配置。

列表属性按索引进行缩放。有关更多详细信息，请参阅列表示例。

在以下等式中，p 表示包含图中所有节点的单个属性的所有属性值的向量。

最小-最大缩放器

将所有属性值缩放到 [0, 1] 范围内，其中最小值获得 0 的缩放值，最大值获得 1 的缩放值，根据以下公式

scaled p equals p minus minimum of p divided by maximum of p minus minimum of p

使用此缩放器时，最小值和最大值将作为统计信息报告。

最大缩放器

将所有属性值缩放到 [-1, 1] 范围内，其中绝对最大值获得 1 的缩放值，根据以下公式

scaled p equals p divided by the absolute maximum of p

使用此缩放器时，最大绝对值将作为统计信息报告。

平均值缩放器

将所有属性值缩放到 [-1, 1] 范围内，其中平均值获得 0 的缩放值。

scaled p equals p minus average of p divided by maximum of p minus minimum of p

使用此缩放器时，最小值、最大值和平均值将作为统计信息报告。

对数缩放器

使用自然对数变换所有属性值。C 表示可配置的常数偏移量，可用于避免值空间中的负值或零，因为它们的 logaritms 不是有限值。

标准分数

使用标准分数（维基百科）缩放所有属性值。

scaled p equals p minus average of p divided by standard deviation of p

使用此缩放器时，平均值和标准差将作为统计信息报告。

中心

通过减去平均值来变换所有属性。

使用此缩放器时，平均值将作为统计信息报告。

某些缩放器必须在其计算中进行除法。例如，计算“标准分数”需要除以标准差。如果计算缩放属性需要除以非法值（如 0 或 NaN），则所得缩放属性值将为 0。

语法

本节介绍在每种执行模式下执行比例属性算法时使用的语法。我们正在描述命名的图变体语法。要了解有关一般语法变体的更多信息，请参阅语法概述。

每种模式的比例属性语法

在命名图上以流模式运行比例属性。

CALL gds.scaleProperties.stream(
  graphName: String,
  configuration: Map
) YIELD
  nodeId: Integer,
  scaledProperty: List of Float

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

表 2. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以用来更方便地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，则不会记录进度百分比。
nodeProperties	字符串列表	`n/a`	否	要缩放的节点属性的名称。所有属性名称必须存在于投影图中。
scaler	字符串或映射	`n/a`	否	应用于属性的缩放器的名称。支持的值为 `MinMax`、`Max`、`Mean`、`Log`、`Center` 和 `StdScore`，不区分大小写。要应用特定于缩放器的配置，请使用映射语法：`{scaler: 'name', …}`。

表 3. 结果
名称	类型	描述
nodeId	整数	节点 ID。
scaledProperty	浮点数列表	每个输入节点属性的缩放值。

在命名图上以 mutate 模式运行 Scale Properties。

CALL gds.scaleProperties.mutate(
  graphName: String,
  configuration: Map
) YIELD
  scalerStatistics: Map,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  mutateMillis: Integer,
  postProcessingMillis: Integer,
  nodePropertiesWritten: Integer,
  configuration: Map

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

表 5. 配置
名称	类型	默认值	可选	描述
mutateProperty	字符串	`n/a`	否	GDS 图中要写入缩放属性的节点属性。
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以用来更方便地跟踪算法的进度。
nodeProperties	字符串列表	`n/a`	否	要缩放的节点属性的名称。所有属性名称必须存在于投影图中。
scaler	字符串或映射	`n/a`	否	应用于属性的缩放器的名称。支持的值为 `MinMax`、`Max`、`Mean`、`Log`、`Center` 和 `StdScore`，不区分大小写。要应用特定于缩放器的配置，请使用映射语法：`{scaler: 'name', …}`。

表 6. 结果
名称	类型	描述
scalerStatistics	映射	由指定的缩放器计算的统计信息（如果有）。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
mutateMillis	整数	将属性添加到投影图的毫秒数。
postProcessingMillis	整数	未使用。
nodePropertiesWritten	整数	写入的节点属性数量。
configuration	映射	用于运行算法的配置。

在命名图上以 stats 模式运行 Scale Properties。

CALL gds.scaleProperties.stats(
  graphName: String,
  configuration: Map
)
YIELD
  scalerStatistics: Map,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  configuration: Map

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

表 8. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以用来更方便地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，则不会记录进度百分比。
nodeProperties	字符串列表	`n/a`	否	要缩放的节点属性的名称。所有属性名称必须存在于投影图中。
scaler	字符串或映射	`n/a`	否	应用于属性的缩放器的名称。支持的值为 `MinMax`、`Max`、`Mean`、`Log`、`Center` 和 `StdScore`，不区分大小写。要应用特定于缩放器的配置，请使用映射语法：`{scaler: 'name', …}`。

表 9. 结果
名称	类型	描述
scalerStatistics	映射	由指定的缩放器计算的统计信息（如果有）。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
postProcessingMillis	整数	未使用。
configuration	映射	用于运行算法的配置。

在命名图上以 write 模式运行 Scale Properties。

CALL gds.scaleProperties.write(
  graphName: String,
  configuration: Map
)
YIELD
  scalerStatistics: Map,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  writeMillis: Integer,
  postProcessingMillis: Integer,
  nodePropertiesWritten: Integer,
  configuration: Map

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

表 11. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。具有任何给定标签的节点都将被包含。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。具有任何给定类型的关系都将被包含。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以用来更方便地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，则不会记录进度百分比。
writeConcurrency	整数	`'concurrency' 的值`	是	用于将结果写入 Neo4j 的并发线程数。
writeProperty	字符串	`n/a`	否	Neo4j 数据库中要写入缩放属性的节点属性。
nodeProperties	字符串列表	`n/a`	否	要缩放的节点属性的名称。所有属性名称必须存在于投影图中。
scaler	字符串或映射	`n/a`	否	应用于属性的缩放器的名称。支持的值为 `MinMax`、`Max`、`Mean`、`Log`、`Center` 和 `StdScore`，不区分大小写。要应用特定于缩放器的配置，请使用映射语法：`{scaler: 'name', …}`。

表 12. 结果
名称	类型	描述
scalerStatistics	映射	由指定的缩放器计算的统计信息（如果有）。
preProcessingMillis	整数	预处理数据的毫秒数。
computeMillis	整数	运行算法的毫秒数。
writeMillis	整数	将结果写回 Neo4j 的毫秒数。
postProcessingMillis	整数	未使用。
nodePropertiesWritten	整数	写入的节点属性数量。
configuration	映射	用于运行算法的配置。

特定于缩放器的配置选项

log 缩放器支持特定配置，我们将在此处记录这些配置。

表 13. `log` 缩放器的特定配置
名称	类型	默认值	可选	描述
type	字符串	`n/a`	否	应用于属性的缩放器的类型。支持的值为 `MinMax`、`Max`、`Mean`、`Log`、`Center` 和 `StdScore`，不区分大小写。
offset	数字	`0`	是	在计算属性值的对数之前应用的常数加法项。

所有其他缩放器不支持其他自定义配置。

示例

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

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

在本节中，我们将展示在具体图上运行 Scale Properties 算法的示例。目的是说明结果的外观，并提供如何在实际环境中使用该算法的指南。我们将在一个小型酒店图上进行此操作，该图包含一些以特定模式连接的节点。示例图如下所示

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

CREATE
  (:Hotel {avgReview: 4.2, buildYear: 1978, storyCapacity: [32, 32, 0], name: 'East'}),
  (:Hotel {avgReview: 8.1, buildYear: 1958, storyCapacity: [18, 20, 0], name: 'Plaza'}),
  (:Hotel {avgReview: 19.0, buildYear: 1999, storyCapacity: [100, 100, 70], name: 'Central'}),
  (:Hotel {avgReview: -4.12, buildYear: 2005, storyCapacity: [250, 250, 250], name: 'West'}),
  (:Hotel {avgReview: 0.01, buildYear: 2020, storyCapacity: [1250, 1250, 900], name: 'Polar'}),
  (:Hotel {avgReview: 3.3, buildYear: 1981, storyCapacity: [240, 240, 0], name: 'Beach'}),
  (:Hotel {avgReview: 6.7, buildYear: 1984, storyCapacity: [80, 0, 0], name: 'Mountain'}),
  (:Hotel {avgReview: -1.2, buildYear: 2010, storyCapacity: [55, 20, 0], name: 'Forest'})

有了 Neo4j 中的图，我们现在可以将其投影到图目录中，以准备算法执行。我们使用针对 Hotel 节点的 Cypher 投影来执行此操作，包括它们的属性。请注意，缩放节点属性不需要任何关系。因此，我们对关系使用星形投影 ('*')。

以下语句将使用 Cypher 投影投影图，并将其存储在名为 'myGraph' 的图目录中。

MATCH (hotel:Hotel)
RETURN gds.graph.project(
  'myGraph',
  hotel,
  null,
  {
    sourceNodeProperties: hotel { .avgReview, .buildYear, .storyCapacity },
    targetNodeProperties: {}
  }
)

在以下示例中，我们将演示如何缩放此图的节点属性。

内存估算

首先，我们将使用 estimate 过程估算运行算法的成本。这可以在任何执行模式下完成。在本例中，我们将使用 stream 模式。估算算法有助于了解在图上运行算法将产生的内存影响。当您稍后以其中一种执行模式实际运行算法时，系统将执行估算。如果估算表明执行有很大可能超过其内存限制，则会禁止执行。有关此内容的更多信息，请参阅自动估算和执行阻塞。

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

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

CALL gds.scaleProperties.stream.estimate('myGraph', {
  nodeProperties: ['buildYear', 'storyCapacity'],
  scaler: 'MinMax'
})
YIELD nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory

表 14. 结果
nodeCount	relationshipCount	bytesMin	bytesMax	requiredMemory
8	0	480	480	"480 字节"

流

在 stream 执行模式下，算法会返回每个节点的缩放属性。这使我们可以直接检查结果，或在没有任何副作用的情况下在 Cypher 中对其进行后处理。请注意，输出始终是单个列表属性，包含按输入顺序排列的所有缩放节点属性。

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

以下内容将以 stream 模式运行算法

CALL gds.scaleProperties.stream('myGraph', {
  nodeProperties: ['buildYear', 'avgReview'],
  scaler: 'MinMax'
}) YIELD nodeId, scaledProperty
RETURN gds.util.asNode(nodeId).name AS name, scaledProperty
  ORDER BY name ASC

表 15. 结果
name	scaledProperty
"海滩"	[0.3709677419354839, 0.3209342560553633]
"中心"	[0.6612903225806451, 1.0]
"东"	[0.3225806451612903, 0.35986159169550175]
"森林"	[0.8387096774193549, 0.12629757785467127]
"山"	[0.41935483870967744, 0.4679930795847751]
"广场"	[0.0, 0.5285467128027681]
"极地"	[1.0, 0.17863321799307957]
"西"	[0.7580645161290323, 0.0]

在结果中，我们可以观察到，在得到的 scaledProperty 中，第一个元素是 buildYear 的最小-最大-缩放值，其中 Plaza 酒店的值最小，缩放为零，而 Polar 酒店的值最大，缩放为一。这可以通过示例图验证。scaledProperty 结果中的第二个值是 avgReview 属性的缩放值。

变异

mutate 执行模式允许使用包含该节点的缩放属性的新节点属性更新命名图。新属性的名称使用强制配置参数 mutateProperty 指定。结果是一个包含计算指标的单个摘要行。mutate 模式在联合使用多个算法时特别有用。

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

在本例中，我们将使用平均值缩放器缩放 buildYear 和 avgReview 的两个酒店属性。输出是一个列表属性，我们将将其称为 hotelFeatures，假设我们将在以后将其用作机器学习模型的输入。

以下内容将以 mutate 模式运行算法

CALL gds.scaleProperties.mutate('myGraph', {
  nodeProperties: ['buildYear', 'avgReview'],
  scaler: 'Mean',
  mutateProperty: 'hotelFeatures'
}) YIELD nodePropertiesWritten, scalerStatistics

表 16. 结果
nodePropertiesWritten	scalerStatistics
8	{avgReview={avg=[4.49875], max=[19.0], min=[-4.12]}, buildYear={avg=[1991.875], max=[2020.0], min=[1958.0]}}

结果表明，内存中图中现在有八个新的节点属性。这些包含来自输入属性的缩放值，其中缩放的 buildYear 值在第一个列表位置，缩放的 avgReview 值在第二个列表位置。要了解如何检查内存中图的新模式，请参阅列出目录中的图。

统计信息

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

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

以下内容将使用 "中心" 缩放器以 stats 模式运行算法

CALL gds.scaleProperties.stats('myGraph', {
  nodeProperties: ['buildYear', 'avgReview'],
  scaler: 'center'
}) YIELD scalerStatistics

表 17. 结果
scalerStatistics
{avgReview={avg=[4.49875]}, buildYear={avg=[1991.875]}}

不同的缩放器需要计算不同的统计信息作为其计算的一部分。这将反映在返回的 scalerStatistics 中。"中心" 计算各种输入属性的平均值，因此在这种情况下，我们将其作为缩放器统计信息结果得到。

写入

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

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

以下内容将以 write 模式运行算法

CALL gds.scaleProperties.write('myGraph', {
  nodeProperties: ['buildYear', 'avgReview'],
  scaler: 'stdscore',
  writeProperty: 'hotelStdScore'
}) YIELD nodePropertiesWritten, scalerStatistics

表 18. 结果
nodePropertiesWritten	scalerStatistics
8	{avgReview={avg=[4.49875], std=[6.6758378454]}, buildYear={avg=[1991.875], std=[18.9171714323]}}

结果表明，数据库图中现在有八个新的节点属性，这些属性位于与投影 'myGraph' 中的节点相对应的节点上。这些节点属性包含来自输入属性的缩放值，其中缩放的 buildYear 值在第一个列表位置，缩放的 avgReview 值在第二个列表位置。

列表属性

storyCapacity 属性模拟酒店每层楼的房间数量。该属性已标准化，因此具有较少楼层的酒店的值为零。这是因为 Scale Properties 算法要求同一属性的所有值具有相同的长度。在本例中，我们将展示如何使用 Scale Properties 算法缩放这些列表中的值。我们假设将输出用作特征向量以输入机器学习算法。此外，我们将把 avgReview 属性包含在特征向量中。

以下内容将以 mutate 模式运行算法

CALL gds.scaleProperties.stream('myGraph', {
  nodeProperties: ['avgReview', 'storyCapacity'],
  scaler: 'StdScore'
}) YIELD nodeId, scaledProperty
RETURN gds.util.asNode(nodeId).name AS name, scaledProperty AS features
  ORDER BY name ASC

表 19. 结果
name	features
"海滩"	[-0.17956547594003253, -0.03401933556831381, 0.00254261210704973, -0.5187592498702616]
"中心"	[2.172199255871029, -0.3968922482969945, -0.3534230828799124, -0.2806402499298136]
"东"	[-0.0447509371737933, -0.5731448059080679, -0.526320706159294, -0.5187592498702616]
"森林"	[-0.8536381697712284, -0.513529970245499, -0.5568320514438908, -0.5187592498702616]
"山"	[0.32973389273242665, -0.4487312358296632, -0.6076842935848854, -0.5187592498702616]
"广场"	[0.5394453974799097, -0.609432097180936, -0.5568320514438908, -0.5187592498702616]
"极地"	[-0.672387512096618, 2.583849534831454, 2.5705808402272767, 2.542770749364069]
"西"	[-1.2910364511016934, -0.00809984180197948, 0.027968733177547028, 0.3316657499170525]

生成的特征向量包含 avgReview 属性的标准分数缩放值，位于第一个列表位置。我们可以看到一些值为负数，并且 Central 酒店的最高值突出显示。

其他三个列表位置是 `storyCapacity` 列表属性的缩放值。请注意，每个列表项仅相对于其他列表中的对应项进行缩放。因此，`Polar` 酒店在所有列表位置中具有最大的缩放值。

缩放器特定配置

`log` 缩放器支持可配置的偏移参数。在本例中，我们将说明如何配置该偏移量。

我们希望缩放 `avgReview` 属性，但它包含负数，而负数的对数是未定义的。首先，我们将使用 Cypher 的 `min()` 聚合函数来确定最小值。

CALL gds.graph.nodeProperty.stream('myGraph', 'avgReview') YIELD propertyValue
RETURN min(propertyValue) AS minimumAvgReview

表 20. 结果
minimumAvgReview
-4.12

了解此值后，我们可以使用更大的值，从而确保对数为有限值。我们将使用 `5.12`，因为这将使最小的缩放值为零。

以下将使用针对 log 缩放器的自定义偏移量运行算法。

CALL gds.scaleProperties.stream('myGraph', {
  nodeProperties: ['avgReview'],
  scaler: {type: 'Log', offset: 5.12}
}) YIELD nodeId, scaledProperty
RETURN gds.util.asNode(nodeId).name AS name, scaledProperty
  ORDER BY name ASC

表 21. 结果
name	scaledProperty
"海滩"	[2.130609828254235]
"中心"	[3.183041371858985]
"东"	[2.2321626286975]
"森林"	[1.366091653802371]
"山"	[2.469793011977952]
"广场"	[2.581730834423540]
"极地"	[1.635105659182678]
"西"	[0.0]

我们可以看到，所有缩放值都是有限数。特别是，最小的缩放值为零。如果您对结果感到好奇，请尝试使用低于 `4.12` 的偏移量运行此示例。