Skip to content

Commit

Permalink
Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@IoannisPanagiotas
IoannisPanagiotas committed Dec 6, 2024
1 parent d794ba1 commit afd845a
Show file tree
Hide file tree
Showing 3 changed files with 246 additions and 7 deletions.
8 changes: 7 additions & 1 deletion doc-test/src/test/java/org/neo4j/gds/doc/PrizeSteinerTreeDocTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,10 @@
package org.neo4j.gds.doc;

import org.neo4j.gds.functions.AsNodeFunc;
import org.neo4j.gds.paths.prizesteiner.PrizeCollectingSteinerTreeMutateProc;
import org.neo4j.gds.paths.prizesteiner.PrizeCollectingSteinerTreeStatsProc;
import org.neo4j.gds.paths.prizesteiner.PrizeCollectingSteinerTreeStreamProc;
import org.neo4j.gds.paths.prizesteiner.PrizeCollectingSteinerTreeWriteProc;

import java.util.List;

Expand All @@ -34,7 +37,10 @@ protected List<Class<?>> functions() {
@Override
protected List<Class<?>> procedures() {
return List.of(
PrizeCollectingSteinerTreeStreamProc.class
PrizeCollectingSteinerTreeStreamProc.class,
PrizeCollectingSteinerTreeStatsProc.class,
PrizeCollectingSteinerTreeMutateProc.class,
PrizeCollectingSteinerTreeWriteProc.class
);
}

Expand Down
5 changes: 4 additions & 1 deletion doc-test/src/test/java/org/neo4j/gds/doc/syntax/PrizeSteinerTreeSyntaxTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,10 @@ class PrizeSteinerTreeSyntaxTest extends SyntaxTestBase {
@Override
protected Iterable<SyntaxModeMeta> syntaxModes() {
return List.of(
SyntaxModeMeta.of(SyntaxMode.STREAM)
SyntaxModeMeta.of(SyntaxMode.MUTATE),
SyntaxModeMeta.of(SyntaxMode.STATS),
SyntaxModeMeta.of(SyntaxMode.STREAM),
SyntaxModeMeta.of(SyntaxMode.WRITE)
);
}

Expand Down
240 changes: 235 additions & 5 deletions doc/modules/ROOT/pages/algorithms/prize-collecting-steiner-tree.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ This should be done as a pre-processing step prior to projecting the in-memory g
.Run the algorithm in stream mode on a named graph.
[source, cypher, role=noplay]
----
CALL gds.steinerTree.stream(
CALL gds.prizeSteinerTree.stream(
graphName: String,
configuration: Map
)
Expand Down Expand Up @@ -79,11 +79,141 @@ include::partial$/algorithms/prize-steiner/specific-configuration.adoc[]

======
[.include-with-stats]
======
.Run the algorithm in stats mode on a named graph.
[source, cypher, role=noplay]
----
CALL gds.prizeSteinerTree.stats(
graphName: String,
configuration: Map
)
YIELD
effectiveNodeCount: Integer,
totalWeight: Float,
sumOfPrizes: Float,
preProcessingMillis: Integer,
computeMillis: Integer,
configuration: Map
----
include::partial$/algorithms/common-configuration/common-parameters.adoc[]

.Configuration
[opts="header",cols="3,2,3m,2,8"]
|===
| Name | Type | Default | Optional | Description
include::partial$/algorithms/common-configuration/common-stream-stats-configuration-entries.adoc[]
include::partial$/algorithms/prize-steiner/specific-configuration.adoc[]
|===

.Results
[opts="header",cols="1,1,6"]
|===
| Name | Type | Description
| effectiveNodeCount | Integer | The number of nodes in the spanning tree.
| totalWeight | Float | The sum of the weights of the relationships in the spanning tree.
| sumOfPrizes | Float | The sum of prizes for the nodes in the spanning tree.
| preProcessingMillis | Integer | Milliseconds for preprocessing the data.
| computeMillis | Integer | Milliseconds for running the algorithm.
| configuration | Map | The configuration used for running the algorithm.
|===

======
[.include-with-mutate]
======
.Run the algorithm in mutate mode on a named graph.
[source, cypher, role=noplay]
----
CALL gds.prizeSteinerTree.mutate(
graphName: String,
configuration: Map
)
YIELD
effectiveNodeCount: Integer,
totalWeight: Float,
sumOfPrizes: Float,
preProcessingMillis: Integer,
computeMillis: Integer,
mutateMillis: Integer,
relationshipsWritten: Integer,
configuration: Map
----
include::partial$/algorithms/common-configuration/common-parameters.adoc[]

.Configuration
[opts="header",cols="3,2,3m,2,8"]
|===
| Name | Type | Default | Optional | Description
include::partial$/algorithms/common-configuration/common-mutate-configuration-entries.adoc[]
include::partial$/algorithms/prize-steiner/specific-configuration.adoc[]
|===

.Results
[opts="header",cols="1,1,6"]
|===
| Name | Type | Description
| effectiveNodeCount | Integer | The number of nodes in the spanning tree.
| totalWeight | Float | The sum of the weights of the relationships in the spanning tree.
| sumOfPrizes | Float | The sum of prizes for the nodes in the spanning tree.
| preProcessingMillis | Integer | Milliseconds for preprocessing the data.
| computeMillis | Integer | Milliseconds for running the algorithm.
| mutateMillis | Integer | Milliseconds for writing result data back.
| relationshipsWritten | Integer | The number of relationships added to the in-memory graph.
| configuration | Map | The configuration used for running the algorithm.
|===

======
[.include-with-write]
======
.Run the algorithm in mutate mode on a named graph.
[source, cypher, role=noplay]
----
CALL gds.prizeSteinerTree.write(
graphName: String,
configuration: Map
)
YIELD
effectiveNodeCount: Integer,
totalWeight: Float,
sumOfPrizes: Float,
preProcessingMillis: Integer,
computeMillis: Integer,
writeMillis: Integer,
relationshipsWritten: Integer,
configuration: Map
----
include::partial$/algorithms/common-configuration/common-parameters.adoc[]

.Configuration
[opts="header",cols="3,2,3m,2,8"]
|===
| Name | Type | Default | Optional | Description
include::partial$/algorithms/common-configuration/common-write-configuration-entries.adoc[]
include::partial$/algorithms/prize-steiner/specific-configuration.adoc[]
|===

.Results
[opts="header",cols="1,1,6"]
|===
| Name | Type | Description
| effectiveNodeCount | Integer | The number of nodes in the spanning tree.
| totalWeight | Float | The sum of the weights of the relationships in the spanning tree.
| sumOfPrizes | Float | The sum of prizes for the nodes in the spanning tree.
| preProcessingMillis | Integer | Milliseconds for preprocessing the data.
| computeMillis | Integer | Milliseconds for running the algorithm.
| writeMillis | Integer | Milliseconds for writing result data back.
| relationshipsWritten | Integer | The number of relationships written to the graph.
| configuration | Map | The configuration used for running the algorithm.
|===

======
====


[[algorithms-directed-steiner-tree-sample]]
[[algorithms-pcst-sample]]
== Examples

include::partial$/algorithms/shared/examples-named-native-note.adoc[]
Expand Down Expand Up @@ -150,12 +280,12 @@ RETURN nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory
[opts="header"]
|===
| nodeCount | relationshipCount | bytesMin | bytesMax | requiredMemory
| 6 | 14 | 3873 | 561592 | "[3873 Bytes \... 548 KiB]"
| 6 | 14 | 3897 | 561616 | "[3897 Bytes \... 548 KiB]"
|===
--


[[algorithms-prize-tree-examples-sream]]
[[algorithms-prize-tree-examples-stream]]
=== Stream
:!stream-details:

Expand Down Expand Up @@ -187,5 +317,105 @@ ORDER BY node
|===
--

The algorithm finds a tree cntaing A,B,C,D, and E.
The algorithm finds a tree containing A,B,C,D, and E.
The node F is skipped because it's price is very low and connecting it with the other nodes would yield an inferior solution.

=== Stats
:stats-syntax: algorithms-prize-steiner-tree-syntax

include::partial$/algorithms/shared/examples-stats-intro.adoc[]

[role=query-example]
--
.The following will run the Prize-Collecting Steiner Tree algorithm in stats mode and return its statistics.
[source,cypher,role=noplay]
----
CALL gds.prizeSteinerTree.stats('graph', {
relationshipWeightProperty: 'cost',
prizeProperty: 'prize'
})
YIELD effectiveNodeCount, totalWeight, sumOfPrizes
RETURN effectiveNodeCount, totalWeight, sumOfPrizes
----

.Results
[opts="header"]
|===
| effectiveNodeCount | totalWeight | sumOfPrizes
| 5 | 14.0 | 54.0
|===
--

The stats mode provides us with information about the total sum weights of the relationships in the connected tree, which is `14.0`, as well as the sum of prizes for nodes A,B,C,D, and E, which is `54.0`.

=== Mutate

include::partial$/algorithms/shared/examples-mutate-intro.adoc[]

[role=query-example]
--
.The following will run the Prize-Collecting Steiner Tree algorithm in mutate mode and return its statistics.
[source,cypher,role=noplay]
----
CALL gds.prizeSteinerTree.mutate('graph', {
relationshipWeightProperty: 'cost',
prizeProperty: 'prize',
mutateProperty: 'weight',
mutateRelationshipType: 'STEINER'
})
YIELD effectiveNodeCount, totalWeight, sumOfPrizes, relationshipsWritten
RETURN effectiveNodeCount, totalWeight, sumOfPrizes, relationshipsWritten
----

.Results
[opts="header"]
|===
| effectiveNodeCount | totalWeight | sumOfPrizes | relationshipsWritten
| 5 | 14.0 | 54.0 | 4
|===
--

The mutate mode updates the in-memory graph `graph` with new relationship type
called `STEINER` with a single property `weight`.
From the `relationshipsWritten` column, we can see that exactly four such relationships were added.
They connect the nodes in the steiner tree, and their property is the cost of each connection.

[NOTE]
====
The relationships added back to the graph are always directed, even if the input graph is undirected. They point from `parent` to `node` in a fixed tree ordering.
====

=== Write

include::partial$/algorithms/shared/examples-write-intro.adoc[]

[role=query-example]
--
.The following will run the Prize-Collecting Steiner Tree algorithm in write mode and return its statistics.
[source,cypher,role=noplay]
----
CALL gds.prizeSteinerTree.write('graph', {
relationshipWeightProperty: 'cost',
prizeProperty: 'prize',
writeProperty: 'weight',
writeRelationshipType: 'STEINER'
})
YIELD effectiveNodeCount, totalWeight, sumOfPrizes, relationshipsWritten
RETURN effectiveNodeCount, totalWeight, sumOfPrizes, relationshipsWritten
----

.Results
[opts="header"]
|===
| effectiveNodeCount | totalWeight | sumOfPrizes | relationshipsWritten
| 5 | 14.0 | 54.0 | 4
|===
--

This query writes back to the database four new relationships
each of type `STEINER` with a single property `weight`.

[NOTE]
====
The relationships added back are always directed, even if the input graph is undirected. They point from `parent` to `node` in a fixed tree ordering.
====

0 comments on commit afd845a

Please sign in to comment.