diff --git a/docs/antora/modules/ROOT/content-nav.adoc b/docs/antora/modules/ROOT/content-nav.adoc index 1d5e0b3..be2ceba 100644 --- a/docs/antora/modules/ROOT/content-nav.adoc +++ b/docs/antora/modules/ROOT/content-nav.adoc @@ -1,8 +1,13 @@ * xref:index.adoc[] * xref:installation.adoc[] * xref:getting-started.adoc[] -* xref:integration.adoc[] * xref:rendering.adoc[] * xref:customizing.adoc[] +* xref:integration/index.adoc[] +** xref:integration/gds.adoc[] +** xref:integration/neo4j.adoc[] +** xref:integration/snowflake.adoc[] +** xref:integration/gql.adoc[] +** xref:integration/pandas.adoc[] * link:{tutorials-docs-uri}[Tutorials] * link:{api-docs-uri}[API reference] \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/customizing.adoc b/docs/antora/modules/ROOT/pages/customizing.adoc index a0692c0..7012e83 100644 --- a/docs/antora/modules/ROOT/pages/customizing.adoc +++ b/docs/antora/modules/ROOT/pages/customizing.adoc @@ -10,7 +10,7 @@ If you have not yet created a `VisualizationGraph` object, refer to one of the f * xref:getting-started.adoc[Getting started] for creating a visualization graph from scratch using `neo4j-viz` primitives like link:{api-docs-uri}/node/[Node] and link:{api-docs-uri}/relationship/[Relationship] and link:{api-docs-uri}/visualization-graph[`VisualizationGraph`] directly. -* xref:integration.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection. +* xref:integration/index.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection. == Setting node captions diff --git a/docs/antora/modules/ROOT/pages/getting-started.adoc b/docs/antora/modules/ROOT/pages/getting-started.adoc index 6d57033..d611ca3 100644 --- a/docs/antora/modules/ROOT/pages/getting-started.adoc +++ b/docs/antora/modules/ROOT/pages/getting-started.adoc @@ -86,6 +86,6 @@ Now that we have covered the basics of creating and rendering a visualization gr Here are some suggestions for what to do next: * Browse the link:{tutorials-docs-uri}[notebook examples] for more examples and use cases -* Learn about the xref:integration.adoc[integrations] with other libraries such as Neo4j GDS and Pandas +* Learn about the xref:integration/index.adoc[integrations] with other libraries such as Neo4j GDS and Pandas * Check out the xref:rendering.adoc[rendering options] and convenience methods of `VisualizationGraph` * Read about our link:{api-docs-uri}/[API reference] diff --git a/docs/antora/modules/ROOT/pages/index.adoc b/docs/antora/modules/ROOT/pages/index.adoc index 9f2ef11..491598c 100644 --- a/docs/antora/modules/ROOT/pages/index.adoc +++ b/docs/antora/modules/ROOT/pages/index.adoc @@ -1,10 +1,13 @@ = Introduction -This is the documentation for the `neo4j-viz` Python library by Neo4j. -The library allows you to visualize graph data interactively in Python using a simple API. +The Python Graph Visualization library allows you to visualize graph data interactively in Python. -The library wraps the link:https://neo4j.com/docs/nvl/current/[Neo4j Visualization JavaScript library (NVL)], and provides additional features for working with graph data in Python. -Notably, there are convenience methods for importing data from source such as link:https://pandas.pydata.org/[Pandas DataFrames], link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science], link:https://neo4j.com/docs/python-manual/current/[Neo4j Database], and link:https://docs.snowflake.com/[Snowflake tables]. +The library wraps the JavaScript-based link:https://neo4j.com/docs/nvl/current/[Neo4j Visualization Library (NVL)] and adds convenience methods to import data from sources such as: + +* xref:integration/pandas.adoc[] +* xref:integration/gds.adoc[] +* xref:integration/neo4j.adoc[] +* xref:integration/snowflake.adoc[] The source code is available on link:https://github.com/neo4j/python-graph-visualization[GitHub]. If you have a suggestion on how we can improve the library or want to report a problem, you can create a link:https://github.com/neo4j/python-graph-visualization/issues/new[new issue]. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/installation.adoc b/docs/antora/modules/ROOT/pages/installation.adoc index 47ef95f..d574ee6 100644 --- a/docs/antora/modules/ROOT/pages/installation.adoc +++ b/docs/antora/modules/ROOT/pages/installation.adoc @@ -1,6 +1,6 @@ = Installation -To install the latest version of the library, run: +You can install the latest version of the library with `pip`: [source, console] ---- @@ -9,47 +9,16 @@ pip install neo4j-viz == Optional dependencies -In addition, there are a few optional dependencies that you can install to enable additional features of the library. +There are a few optional dependencies that you can install to enable additional features of the library. -=== Pandas DataFrames `from_dfs` importer +=== Integration with external sources -To install the additional dependencies required for the link:{api-docs-uri}/from_pandas[`from_dfs`] importer you can run: - -[source, console] ----- -pip install neo4j-viz[pandas] ----- - -=== Neo4j `from_neo4j` importer - -To install the additional dependencies required for the link:{api-docs-uri}/from_neo4j[`from_neo4j`] importer you can run: - -[source, console] ----- -pip install neo4j-viz[neo4j] ----- - -=== Neo4j Graph Data Science `from_gds` importer - -To install the additional dependencies required for the link:{api-docs-uri}/from_gds[`from_gds`] importer you can run: - -[source, console] ----- -pip install neo4j-viz[gds] ----- - -=== Neo4j Graph Data Science `from_snowflake` importer - -To install the additional dependencies required for the link:{api-docs-uri}/from_snowflake[`from_snowflake`] importer you can run: - -[source, console] ----- -pip install neo4j-viz[snowflake] ----- +The library can import data directly from xref:integration/index.adoc[external sources]. +Each integration page includes installation instructions for the needed dependencies. === Notebook tutorials -To install all the additional dependencies required for the link:{tutorials-docs-uri}[notebook examples] you can run: +You need to install some additional dependencies to run the link:{tutorials-docs-uri}[Jupyter notebook tutorials]: [source, console] ---- diff --git a/docs/antora/modules/ROOT/pages/integration.adoc b/docs/antora/modules/ROOT/pages/integration.adoc deleted file mode 100644 index 67c7422..0000000 --- a/docs/antora/modules/ROOT/pages/integration.adoc +++ /dev/null @@ -1,286 +0,0 @@ -= Integration with other libraries - -In addition to creating graphs from scratch, with `neo4j-viz` as is shown in the -xref:getting-started.adoc[], you can also import data directly from external sources. -In this section we will cover how to import data from link:https://pandas.pydata.org/[Pandas DataFrames], -link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science], -link:https://neo4j.com/docs/python-manual/current/[Neo4j Database], -link:https://neo4j.com/docs/cypher-manual/current/clauses/create/[GQL `CREATE` queries], and link:https://docs.snowflake.com/[Snowflake tables]. - -== Pandas DataFrames - -The `neo4j-viz` library provides a convenience method for importing data from Pandas DataFrames. -These DataFrames can be created from many sources, such as CSV files. -It requires and additional dependency to be installed, which you can do by running: - -[source, console] ----- -pip install neo4j-viz[pandas] ----- - -Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_pandas[`from_pandas`] method -to import pandas DataFrames. - -The `from_dfs` method takes two mandatory positional parameters: - -* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the nodes of the graph. - The rows of the DataFrame(s) should represent the individual nodes, and the columns should represent the node - IDs and attributes. - The node ID will be set on the link:{api-docs-uri}/node[Node], Other columns will be a key in each node's properties dictionary, that maps to the node's corresponding value in the column. - If the graph has no node properties, the nodes can be derived from the relationships DataFrame alone. -* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the relationships of the graph. - The rows of the DataFrame(s) should represent the individual relationships, and the columns should represent the - relationship IDs and attributes. - The relationship id, source and target node IDs will be set on the link:{api-docs-uri}/relationship[Relationship]. - Other columns will be a key in each relationship's _properties_ dictionary, that maps to the relationship's corresponding value in the column. - -=== Example - -In this small example, we import a tiny toy graph representing a social network from two Pandas DataFrames. -As we can see the column names of the DataFrames map directly to the fields of link:{api-docs-uri}/node[Nodes] -and link:{api-docs-uri}/relationship[Relationships]. - -[source, python] ----- -from pandas import DataFrame -from neo4j_viz.pandas import from_dfs - -nodes = DataFrame({ - "id": [1, 2, 3], - "caption": ["Alice", "Bob", "Charlie"], - "size": [20, 10, 10], -}) - -relationships = DataFrame({ - "source": [1, 2], - "target": [2, 3], - "caption": ["LIKES", "KNOWS"], -}) - -VG = from_dfs(nodes, relationships) ----- - -== Neo4j Graph Data Science (GDS) library - -The `neo4j-viz` library provides a convenience method for importing data from the Neo4j Graph Data Science (GDS) -library. -It requires and additional dependency to be installed, which you can do by running: - -[source, console] ----- -pip install neo4j-viz[gds] ----- - -Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_gds[`from_gds`] method -to import projections from the GDS library. - -The `from_gds` method takes two mandatory positional parameters: - -* An initialized `GraphDataScience` object for the connection to the GDS instance, and -* A `Graph` representing the projection that one wants to import. - -The optional `max_node_count` parameter can be used to limit the number of nodes that are imported from the projection. -By default, it is set to 10.000, meaning that if the projection has more than 10.000 nodes, `from_gds` will sample from it using random walk with restarts, to get a smaller graph that can be visualized. -If you want to have more control of the sampling, such as choosing a specific start node for the sample, you can call a link:https://neo4j.com/docs/graph-data-science/current/management-ops/graph-creation/sampling/[sampling] method yourself and passing the resulting projection to `from_gds`. - -The `node_properties` parameter is also optional, and should be a list of additional node properties of the projection that you want to include in the visualization. -The default is `None`, which means that all properties of the nodes in the projection will be included. -Apart from being visible through on-hover tooltips, these properties could be used to color the nodes, or give captions to them in the visualization, or simply included in the nodes' `Node.properties` maps without directly impacting the visualization. -If you want to include node properties stored at the Neo4j database, you can include them in the visualization by using the _db_node_properties_ parameter. - -=== Example - -In this small example, we import a graph projection from the GDS library, that has the node properties "pagerank" and -"componentId". -We use the "pagerank" property to determine the size of the nodes, and the "componentId" property to color the nodes. - -[source, python] ----- -from graphdatascience import GraphDataScience -from neo4j_viz.gds import from_gds -gds = GraphDataScience(...) -G = gds.graph.project(...) -# Compute the PageRank and Weakly Connected Components -gds.pageRank.mutate(G, mutateProperty="pagerank") -gds.wcc.mutate(G, mutateProperty="componentId") -# Import the projection into a `VisualizationGraph` -# Make sure to include `pagerank` and `componentId` -VG = from_gds( - gds, - G, - size_property="pagerank", - additional_node_properties=["componentId"], -) -# Color the nodes by the `componentId` property, so that the nodes are -# colored by the connected component they belong to -VG.color_nodes(property="componentId") ----- - -See the link:/tutorials/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for a more extensive example. - -== Neo4j Database - -The `neo4j-viz` library provides a convenience method for importing data from Neo4j. -It requires and additional dependency to be installed, which you can do by running: - -[source, console] ----- -pip install neo4j-viz[neo4j] ----- - -Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_neo4j[`from_neo4j`] method -to import query results from Neo4j. - -The `from_neo4j` method takes one mandatory positional parameter: A `data` argument representing either a query result in the shape of a `neo4j.graph.Graph` or `neo4j.Result`, or a `neo4j.Driver` in which case a simple default query will be executed internally to retrieve the graph data. - -The optional `max_rows` parameter can be used to limit the number of relationships shown in the visualization. -By default, it is set to 10.000, meaning that if the database has more than 10.000 rows, a warning will be raised. -Note, this only applies if the `data` parameter is a `neo4j.Driver`. - -=== Example - -In this small example, we import a graph from a Neo4j query result. - -[source, python] ----- -from neo4j import GraphDatabase, RoutingControl, Result -from neo4j_viz.gds import from_gds - -# Modify this to match your Neo4j instance's URI and credentials -URI = "neo4j://localhost:7687" -auth = ("neo4j", "password") - -with GraphDatabase.driver(URI, auth=auth) as driver: - driver.verify_connectivity() - result = driver.execute_query( - "MATCH (n)-[r]->(m) RETURN n,r,m", - database_="neo4j", - routing_=RoutingControl.READ, - result_transformer_=Result.graph, - ) - -VG = from_neo4j(result) ----- - -See the link:/tutorials/neo4j-example[Visualizing Neo4j Graphs tutorial] for a more extensive example. - -== GQL `CREATE` query - -The `neo4j-viz` library provides convenience for creating visualization graphs from GQL `CREATE` queries via the link:{api-docs-uri}/from_gql_create[`from_gql_create`] method. - -The `from_gql_create` method takes one mandatory positional parameter: - -* A valid `query` representing a GQL `CREATE` query as a string. - -=== Example - -In this small example, we create a visualization graph from a GQL `CREATE` query. - -[source, python] ----- -from neo4j_viz.gql_create import from_gql_create - -query = """ - CREATE - (a:User {name: 'Alice', age: 23}), - (b:User {name: 'Bridget', age: 34}), - (c:User {name: 'Charles', age: 45}), - (d:User {name: 'Dana', age: 56}), - (e:User {name: 'Eve', age: 67}), - (f:User {name: 'Fawad', age: 78}), - (a)-[:LINK {weight: 0.5}]->(b), - (a)-[:LINK {weight: 4}]->(c), - (e)-[:LINK {weight: 1.1}]->(d), - (e)-[:LINK {weight: -2}]->(f); - """ - -VG = from_gql_create(query) ----- - -== Snowflake Tables - -The `neo4j-viz` library provides a convenience method for importing data from Snowflake tables. -It requires and additional dependency to be installed, which you can do by running: - -[source, console] ----- -pip install neo4j-viz[snowflake] ----- - -Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_snowflake[`from_snowflake`] method to import Snowflake tables into a `VisualizationGraph`. - -The `from_snowflake` method takes two mandatory positional parameters: - -* A `snowflake.snowpark.Session` object for the connection to Snowflake, and - -* A link:https://neo4j.com/docs/snowflake-graph-analytics/current/jobs/#jobs-project[project configuration] as a dictionary, that specifies how you want your tables to be projected as a graph. -This configuration is the same as the project configuration of the link:https://neo4j.com/docs/snowflake-graph-analytics/current/[Neo4j Snowflake Graph Analytics application]. - -You can further customize the visualization after the _VisualizationGraph_ has been created, by using the methods described in the link:{api-docs-uri}/customizing/[Customizing the visualization] section. - -=== Default behavior - -The node and relationship captions will be set to the names of the corresponding tables. -The nodes will be colored so that nodes from the same table have the same color, and different tables have different colors. - -=== Example - -In this small example, we import a toy graph representing a social network from two tables in Snowflake. - -[source, python] ----- -from snowflake.snowpark import Session -from neo4j_viz.snowflake import from_dfs - -# Configure according to your own setup -connection_parameters = { - "account": os.environ.get("SNOWFLAKE_ACCOUNT"), - "user": os.environ.get("SNOWFLAKE_USER"), - "password": os.environ.get("SNOWFLAKE_PASSWORD"), - "role": os.environ.get("SNOWFLAKE_ROLE"), - "warehouse": os.environ.get("SNOWFLAKE_WAREHOUSE"), -} - -session.sql( - "CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.PERSONS (NODEID VARCHAR);" -).collect() - -session.sql(""" -INSERT INTO EXAMPLE_DB.DATA_SCHEMA.PERSONS VALUES - ('Alice'), - ('Bob'), - ('Carol'), - ('Dave'), - ('Eve'); - """).collect() - -session.sql( - "CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.KNOWS (SOURCENODEID VARCHAR, TARGETNODEID VARCHAR);" -).collect() - -session.sql(""" -INSERT INTO EXAMPLE_DB.DATA_SCHEMA.KNOWS VALUES - ('Alice', 'Dave'), - ('Alice', 'Carol'), - ('Bob', 'Carol'), - ('Dave', 'Eve'), - """).collect() - -VG = from_snowflake( - session, - { - "nodeTables": [ - "EXAMPLE_DB.DATA_SCHEMA.PERSONS", - ], - "relationshipTables": { - "EXAMPLE_DB.DATA_SCHEMA.KNOWS": { - "sourceTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS", - "targetTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS", - "orientation": "UNDIRECTED", - } - }, - }, -) ----- - -For a full example of the `from_snowflake` importer in action, please see the link:http://localhost:9000/tutorials/snowflake-example/[Visualizing Snowflake Tables tutorial]. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/gds.adoc b/docs/antora/modules/ROOT/pages/integration/gds.adoc new file mode 100644 index 0000000..a61beae --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/gds.adoc @@ -0,0 +1,56 @@ += Neo4j Graph Data Science + +The `neo4j-viz` library provides a convenience method for importing data from the link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science] (GDS) library. +It requires and additional dependency to be installed, which you can do by running: + +[source, console] +---- +pip install neo4j-viz[gds] +---- + +Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_gds[`from_gds`] method +to import projections from the GDS library. + +The `from_gds` method takes two mandatory positional parameters: + +* An initialized `GraphDataScience` object for the connection to the GDS instance, and +* A `Graph` representing the projection that one wants to import. + +The optional `max_node_count` parameter can be used to limit the number of nodes that are imported from the projection. +By default, it is set to 10.000, meaning that if the projection has more than 10.000 nodes, `from_gds` will sample from it using random walk with restarts, to get a smaller graph that can be visualized. +If you want to have more control of the sampling, such as choosing a specific start node for the sample, you can call a link:https://neo4j.com/docs/graph-data-science/current/management-ops/graph-creation/sampling/[sampling] method yourself and passing the resulting projection to `from_gds`. + +The `node_properties` parameter is also optional, and should be a list of additional node properties of the projection that you want to include in the visualization. +The default is `None`, which means that all properties of the nodes in the projection will be included. +Apart from being visible through on-hover tooltips, these properties could be used to color the nodes, or give captions to them in the visualization, or simply included in the nodes' `Node.properties` maps without directly impacting the visualization. +If you want to include node properties stored at the Neo4j database, you can include them in the visualization by using the _db_node_properties_ parameter. + +== Example + +In this small example, we import a graph projection from the GDS library, that has the node properties "pagerank" and +"componentId". +We use the "pagerank" property to determine the size of the nodes, and the "componentId" property to color the nodes. + +[source, python] +---- +from graphdatascience import GraphDataScience +from neo4j_viz.gds import from_gds +gds = GraphDataScience(...) +G = gds.graph.project(...) +# Compute the PageRank and Weakly Connected Components +gds.pageRank.mutate(G, mutateProperty="pagerank") +gds.wcc.mutate(G, mutateProperty="componentId") +# Import the projection into a `VisualizationGraph` +# Make sure to include `pagerank` and `componentId` +VG = from_gds( + gds, + G, + size_property="pagerank", + additional_node_properties=["componentId"], +) +# Color the nodes by the `componentId` property, so that the nodes are +# colored by the connected component they belong to +VG.color_nodes(property="componentId") +---- + +See the link:/tutorials/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for a more extensive example. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/gql.adoc b/docs/antora/modules/ROOT/pages/integration/gql.adoc new file mode 100644 index 0000000..a632441 --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/gql.adoc @@ -0,0 +1,32 @@ += GQL `CREATE` queries + +The `neo4j-viz` library provides convenience for creating visualization graphs from link:https://neo4j.com/docs/cypher-manual/current/clauses/create/[GQL `CREATE` queries] via the `from_gql_create` method. + +The link:{api-docs-uri}/from_gql_create[`from_gql_create`] method takes one mandatory positional parameter: + +* A valid `query` representing a GQL `CREATE` query as a string. + +== Example + +In this small example, we create a visualization graph from a GQL `CREATE` query. + +[source, python] +---- +from neo4j_viz.gql_create import from_gql_create + +query = """ + CREATE + (a:User {name: 'Alice', age: 23}), + (b:User {name: 'Bridget', age: 34}), + (c:User {name: 'Charles', age: 45}), + (d:User {name: 'Dana', age: 56}), + (e:User {name: 'Eve', age: 67}), + (f:User {name: 'Fawad', age: 78}), + (a)-[:LINK {weight: 0.5}]->(b), + (a)-[:LINK {weight: 4}]->(c), + (e)-[:LINK {weight: 1.1}]->(d), + (e)-[:LINK {weight: -2}]->(f); + """ + +VG = from_gql_create(query) +---- \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/index.adoc b/docs/antora/modules/ROOT/pages/integration/index.adoc new file mode 100644 index 0000000..9d41e1b --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/index.adoc @@ -0,0 +1,10 @@ += Visualizing existing data + +In addition to creating graphs from scratch, you can import and visualize data directly from external sources such as: + +* xref:integration/pandas.adoc[] +* xref:integration/gds.adoc[] +* xref:integration/neo4j.adoc[] +* xref:integration/snowflake.adoc[] + +You can also visualize the effect of running a xref:integration/gql.adoc[GQL `create` query] without having to run it on a Neo4j database. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/neo4j.adoc b/docs/antora/modules/ROOT/pages/integration/neo4j.adoc new file mode 100644 index 0000000..baffdd1 --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/neo4j.adoc @@ -0,0 +1,45 @@ += Neo4j database + +The `neo4j-viz` library provides a convenience method for importing data from the Neo4j database via the link:https://neo4j.com/docs/python-manual/current/[Neo4j Python driver]. +It requires and additional dependency to be installed, which you can do by running: + +[source, console] +---- +pip install neo4j-viz[neo4j] +---- + +Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_neo4j[`from_neo4j`] method +to import query results from Neo4j. + +The `from_neo4j` method takes one mandatory positional parameter: A `data` argument representing either a query result in the shape of a `neo4j.graph.Graph` or `neo4j.Result`, or a `neo4j.Driver` in which case a simple default query will be executed internally to retrieve the graph data. + +The optional `max_rows` parameter can be used to limit the number of relationships shown in the visualization. +By default, it is set to 10.000, meaning that if the database has more than 10.000 rows, a warning will be raised. +Note, this only applies if the `data` parameter is a `neo4j.Driver`. + +== Example + +In this small example, we import a graph from a Neo4j query result. + +[source, python] +---- +from neo4j import GraphDatabase, RoutingControl, Result +from neo4j_viz.gds import from_gds + +# Modify this to match your Neo4j instance's URI and credentials +URI = "neo4j://localhost:7687" +auth = ("neo4j", "password") + +with GraphDatabase.driver(URI, auth=auth) as driver: + driver.verify_connectivity() + result = driver.execute_query( + "MATCH (n)-[r]->(m) RETURN n,r,m", + database_="neo4j", + routing_=RoutingControl.READ, + result_transformer_=Result.graph, + ) + +VG = from_neo4j(result) +---- + +See the link:/tutorials/neo4j-example[Visualizing Neo4j Graphs tutorial] for a more extensive example. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/pandas.adoc b/docs/antora/modules/ROOT/pages/integration/pandas.adoc new file mode 100644 index 0000000..629cea2 --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/pandas.adoc @@ -0,0 +1,52 @@ += Pandas DataFrames + +The `neo4j-viz` library provides a convenience method for importing data from link:https://pandas.pydata.org/[Pandas DataFrames]. +These DataFrames can be created from many sources, such as CSV files. +It requires and additional dependency to be installed, which you can do by running: + +[source, console] +---- +pip install neo4j-viz[pandas] +---- + +Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_pandas[`from_pandas`] method +to import pandas DataFrames. + +The `from_dfs` method takes two mandatory positional parameters: + +* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the nodes of the graph. + The rows of the DataFrame(s) should represent the individual nodes, and the columns should represent the node + IDs and attributes. + The node ID will be set on the link:{api-docs-uri}/node[Node], Other columns will be a key in each node's properties dictionary, that maps to the node's corresponding value in the column. + If the graph has no node properties, the nodes can be derived from the relationships DataFrame alone. +* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the relationships of the graph. + The rows of the DataFrame(s) should represent the individual relationships, and the columns should represent the + relationship IDs and attributes. + The relationship id, source and target node IDs will be set on the link:{api-docs-uri}/relationship[Relationship]. + Other columns will be a key in each relationship's _properties_ dictionary, that maps to the relationship's corresponding value in the column. + +== Example + +In this small example, we import a tiny toy graph representing a social network from two Pandas DataFrames. +As we can see the column names of the DataFrames map directly to the fields of link:{api-docs-uri}/node[Nodes] +and link:{api-docs-uri}/relationship[Relationships]. + +[source, python] +---- +from pandas import DataFrame +from neo4j_viz.pandas import from_dfs + +nodes = DataFrame({ + "id": [1, 2, 3], + "caption": ["Alice", "Bob", "Charlie"], + "size": [20, 10, 10], +}) + +relationships = DataFrame({ + "source": [1, 2], + "target": [2, 3], + "caption": ["LIKES", "KNOWS"], +}) + +VG = from_dfs(nodes, relationships) +---- \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/integration/snowflake.adoc b/docs/antora/modules/ROOT/pages/integration/snowflake.adoc new file mode 100644 index 0000000..f36405f --- /dev/null +++ b/docs/antora/modules/ROOT/pages/integration/snowflake.adoc @@ -0,0 +1,87 @@ += Snowflake tables + +The `neo4j-viz` library provides a convenience method for importing data from link:https://docs.snowflake.com/[Snowflake tables]. +It requires and additional dependency to be installed, which you can do by running: + +[source, console] +---- +pip install neo4j-viz[snowflake] +---- + +Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_snowflake[`from_snowflake`] method to import Snowflake tables into a `VisualizationGraph`. + +The `from_snowflake` method takes two mandatory positional parameters: + +* A `snowflake.snowpark.Session` object for the connection to Snowflake, and + +* A link:https://neo4j.com/docs/snowflake-graph-analytics/current/jobs/#jobs-project[project configuration] as a dictionary, that specifies how you want your tables to be projected as a graph. +This configuration is the same as the project configuration of the link:https://neo4j.com/docs/snowflake-graph-analytics/current/[Neo4j Snowflake Graph Analytics application]. + +You can further customize the visualization after the _VisualizationGraph_ has been created, by using the methods described in the link:{api-docs-uri}/customizing/[Customizing the visualization] section. + +== Default behavior + +The node and relationship captions will be set to the names of the corresponding tables. +The nodes will be colored so that nodes from the same table have the same color, and different tables have different colors. + +== Example + +In this small example, we import a toy graph representing a social network from two tables in Snowflake. + +[source, python] +---- +from snowflake.snowpark import Session +from neo4j_viz.snowflake import from_dfs + +# Configure according to your own setup +connection_parameters = { + "account": os.environ.get("SNOWFLAKE_ACCOUNT"), + "user": os.environ.get("SNOWFLAKE_USER"), + "password": os.environ.get("SNOWFLAKE_PASSWORD"), + "role": os.environ.get("SNOWFLAKE_ROLE"), + "warehouse": os.environ.get("SNOWFLAKE_WAREHOUSE"), +} + +session.sql( + "CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.PERSONS (NODEID VARCHAR);" +).collect() + +session.sql(""" +INSERT INTO EXAMPLE_DB.DATA_SCHEMA.PERSONS VALUES + ('Alice'), + ('Bob'), + ('Carol'), + ('Dave'), + ('Eve'); + """).collect() + +session.sql( + "CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.KNOWS (SOURCENODEID VARCHAR, TARGETNODEID VARCHAR);" +).collect() + +session.sql(""" +INSERT INTO EXAMPLE_DB.DATA_SCHEMA.KNOWS VALUES + ('Alice', 'Dave'), + ('Alice', 'Carol'), + ('Bob', 'Carol'), + ('Dave', 'Eve'), + """).collect() + +VG = from_snowflake( + session, + { + "nodeTables": [ + "EXAMPLE_DB.DATA_SCHEMA.PERSONS", + ], + "relationshipTables": { + "EXAMPLE_DB.DATA_SCHEMA.KNOWS": { + "sourceTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS", + "targetTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS", + "orientation": "UNDIRECTED", + } + }, + }, +) +---- + +For a full example of the `from_snowflake` importer in action, please see the link:http://localhost:9000/tutorials/snowflake-example/[Visualizing Snowflake Tables tutorial]. \ No newline at end of file diff --git a/docs/antora/modules/ROOT/pages/rendering.adoc b/docs/antora/modules/ROOT/pages/rendering.adoc index 2ce089e..c55c18f 100644 --- a/docs/antora/modules/ROOT/pages/rendering.adoc +++ b/docs/antora/modules/ROOT/pages/rendering.adoc @@ -8,7 +8,7 @@ If you have not yet created a `VisualizationGraph` object, refer to one of the f * xref:getting-started.adoc[Getting started] for creating a visualization graph from scratch using `neo4j-viz` primitives like link:{api-docs-uri}/node[Node] and link:{api-docs-uri}/relationship[Relationship] and link:{api-docs-uri}/visualization-graph>[`VisualizationGraph`] directly. -* xref:integration.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection. +* xref:integration/index.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection. == The `render` method