Neo4j Graph Data Science Client

graphdatascience is a Python client for operating and working with the Neo4j Graph Data Science (GDS) library. It enables users to write pure Python code to project graphs, run algorithms, as well as define and use machine learning pipelines in GDS.

The API is designed to mimic the GDS Cypher procedure API in Python code. It abstracts the necessary operations of the Neo4j Python driver to offer a simpler surface. Additionally, the client-specific graph, model, and pipeline objects offer convenient functions that heavily reduce the need to use Cypher to access and operate these GDS resources.

graphdatascience is only guaranteed to work with GDS versions 2.0+.

Please leave any feedback as issues on the source repository. Happy coding!

Installation

To install the latest deployed version of graphdatascience, simply run:

pip install graphdatascience

Getting started

To use the GDS Python Client, we need to instantiate a GraphDataScience object. Then, we can project graphs, create pipelines, train models, and run algorithms.

from graphdatascience import GraphDataScience

# Configure the driver with AuraDS-recommended settings
gds = GraphDataScience("neo4j+s://my-aura-ds.databases.neo4j.io:7687", auth=("neo4j", "my-password"), aura_ds=True)

# Import the Cora common dataset to GDS
G = gds.graph.load_cora()
assert G.node_count() == 2708

# Run PageRank in mutate mode on G
pagerank_result = gds.pageRank.mutate(G, tolerance=0.5, mutateProperty="pagerank")
assert pagerank_result["nodePropertiesWritten"] == G.node_count()

# Create a Node Classification pipeline
pipeline = gds.nc_pipe("myPipe")
assert pipeline.type() == "Node classification training pipeline"

# Add a Degree Centrality feature to the pipeline
pipeline.addNodeProperty("degree", mutateProperty="rank")
pipeline.selectFeatures("rank")
features = pipeline.feature_properties()
assert len(features) == 1
assert features[0]["feature"] == "rank"

# Add a training method
pipeline.addLogisticRegression(penalty=(0.1, 2))

# Train a model on G
model, train_result = pipeline.train(G, modelName="myModel", targetProperty="myClass", metrics=["ACCURACY"])
assert model.metrics()["ACCURACY"]["test"] > 0
assert train_result["trainMillis"] >= 0

# Compute predictions in stream mode
predictions = model.predict_stream(G)
assert len(predictions) == G.node_count()

The example here assumes using an AuraDS instance. For additional examples and extensive documentation of all capabilities, please refer to the GDS Python Client Manual.

Full end-to-end examples in Jupyter ready-to-run notebooks can be found in the examples source directory:

• Machine learning pipelines: Node classification
• Node Regression with Subgraph and Graph Sample projections
• Product recommendations with kNN based on FastRP embeddings
• Sampling, Export and Integration with PyG example
• Load data to a projected graph via graph construction
• Heterogeneous Node Classification with HashGNN and Autotuning

Documentation

The primary source for learning everything about the GDS Python Client is the manual, hosted at https://neo4j.com/docs/graph-data-science-client/current/. The manual is versioned to cover all GDS Python Client versions, so make sure to use the correct version to get the correct information.

Known limitations

Operations known to not yet work with graphdatascience:

• Numeric utility functions (will never be supported)
• Cypher on GDS (might be supported in the future)
• Projecting graphs using Cypher Aggregation (might be supported in the future)

License

graphdatascience is licensed under the Apache Software License version 2.0. All content is copyright © Neo4j Sweden AB.

Acknowledgements

This work has been inspired by the great work done in the following libraries:

• pygds by stellasia
• gds-python by moxious