From eb372b0d65c6a3adcb35c5909e7c736fe153748e Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 06:55:56 -0800 Subject: [PATCH 01/25] docs: add collections usage --- docs/source/visualization/layout/settings.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 8014e73fa8..7865301247 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -36,6 +36,39 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.scene_settings` to modify the appe - ``edge_opacity``: Range 0.0 to 1.0 (0.0 fully transparent, 1.0 fully opaque, displayed as 0-100 in UI) - ``point_opacity``: Range 0.0 to 1.0 (0.0 fully transparent, 1.0 fully opaque, displayed as 0-100 in UI) +Collections +~~~~~~~~~~~ + +Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections (subsets) with optional encodings: + +.. code-block:: python + + import graphistry + + collections = [ + { + "type": "set", + "id": "newsletter_subscribers", + "name": "Newsletter Subscribers", + "node_color": "#32CD32", + "expr": { + "type": "gfql_chain", + "gfql": [graphistry.n({"subscribed_to_newsletter": True})], + }, + } + ] + + g2 = g.collections( + collections=collections, + show_collections=True, + collections_global_node_color="CCCCCC", + collections_global_edge_color="CCCCCC", + ) + g2.plot() + +The collections list is JSON-minified and URL-encoded automatically. For full schema details, see +`Collections URL options `_. + Styling the Background and Foreground ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b9f00fff4e43a03d5c33b907a122497e05fa4dfd Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 07:10:47 -0800 Subject: [PATCH 02/25] docs: add collections notebook and gfql ast example --- .../graphistry_features/collections.ipynb | 107 ++++++++++++++++++ docs/source/notebooks/visualization.rst | 1 + docs/source/visualization/layout/settings.rst | 11 +- 3 files changed, 113 insertions(+), 6 deletions(-) create mode 100644 demos/more_examples/graphistry_features/collections.ipynb diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb new file mode 100644 index 0000000000..f8274040aa --- /dev/null +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -0,0 +1,107 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Collections in PyGraphistry\n", + "\n", + "Define collections (subsets) using GFQL AST helpers and apply visual encodings." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Collections use GFQL operations (like `graphistry.n(...)`) to define sets, and can be combined using intersections." + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "import pandas as pd\n", + "import graphistry\n", + "\n", + "edges = pd.DataFrame({\n", + " 'src': ['acct1', 'acct2', 'acct3'],\n", + " 'dst': ['user1', 'user2', 'user3'],\n", + " 'rel': ['owns', 'owns', 'owns']\n", + "})\n", + "\n", + "nodes = pd.DataFrame({\n", + " 'id': ['acct1', 'acct2', 'acct3', 'user1', 'user2', 'user3'],\n", + " 'type': ['account', 'account', 'account', 'user', 'user', 'user'],\n", + " 'subscribed': [False, True, True, True, False, True],\n", + " 'status': ['purchased', 'purchased', 'new', 'new', 'purchased', 'new']\n", + "})\n", + "\n", + "g = graphistry.edges(edges, 'src', 'dst').nodes(nodes, 'id')\n" + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "collections = [\n", + " {\n", + " 'type': 'set',\n", + " 'id': 'purchasers',\n", + " 'name': 'Purchasers',\n", + " 'node_color': '#00BFFF',\n", + " 'expr': [graphistry.n({'status': 'purchased'})],\n", + " },\n", + " {\n", + " 'type': 'set',\n", + " 'id': 'subscribers',\n", + " 'name': 'Subscribers',\n", + " 'node_color': '#32CD32',\n", + " 'expr': [graphistry.n({'subscribed': True})],\n", + " },\n", + " {\n", + " 'type': 'intersection',\n", + " 'name': 'High Value Subscribers',\n", + " 'node_color': '#AABBCC',\n", + " 'expr': {\n", + " 'type': 'intersection',\n", + " 'sets': ['purchasers', 'subscribers']\n", + " }\n", + " },\n", + "]\n", + "\n", + "g2 = g.collections(\n", + " collections=collections,\n", + " show_collections=True,\n", + " collections_global_node_color='CCCCCC',\n", + " collections_global_edge_color='CCCCCC',\n", + ")\n", + "\n", + "g2._url_params\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To render, authenticate and call `g2.plot()` as usual." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3.x" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} \ No newline at end of file diff --git a/docs/source/notebooks/visualization.rst b/docs/source/notebooks/visualization.rst index 2774803be3..4456c8026a 100644 --- a/docs/source/notebooks/visualization.rst +++ b/docs/source/notebooks/visualization.rst @@ -13,6 +13,7 @@ Encodings Sizes <../demos/more_examples/graphistry_features/encodings-sizes.ipynb> Icons <../demos/more_examples/graphistry_features/encodings-icons.ipynb> Badges <../demos/more_examples/graphistry_features/encodings-badges.ipynb> + Collections <../demos/more_examples/graphistry_features/collections.ipynb> Geographic (Kepler.gl) ---------------------- diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 7865301247..72157d5d80 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -51,10 +51,7 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections "id": "newsletter_subscribers", "name": "Newsletter Subscribers", "node_color": "#32CD32", - "expr": { - "type": "gfql_chain", - "gfql": [graphistry.n({"subscribed_to_newsletter": True})], - }, + "expr": [graphistry.n({"subscribed_to_newsletter": True})], } ] @@ -66,8 +63,10 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections ) g2.plot() -The collections list is JSON-minified and URL-encoded automatically. For full schema details, see -`Collections URL options `_. +The collections list is JSON-minified and URL-encoded automatically. GFQL operations use the +Python AST helpers; see `GFQL documentation `_. +For full schema details, see `Collections URL options `_. +For a full walkthrough, see the `Collections tutorial notebook `_. Styling the Background and Foreground From b30a176cf3beb9ad6f422edfe8a248f8a1fd005b Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 13:24:33 -0800 Subject: [PATCH 03/25] docs: link collections in overview guides --- docs/source/10min.rst | 17 +++++++++++++++++ docs/source/cheatsheet.md | 5 +++++ docs/source/visualization/10min.rst | 17 +++++++++++++++++ docs/source/visualization/index.rst | 2 ++ 4 files changed, 41 insertions(+) diff --git a/docs/source/10min.rst b/docs/source/10min.rst index 8910be19f8..2a57ed2ab7 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -173,6 +173,23 @@ You can adjust further node and edge settings using data. Sample calls include: - ``encode_point_weight()``: Adjust node weights based on a column - Equivalent functions for edges: ``encode_edge_size()``, ``encode_edge_icon()``, ``encode_edge_badge()`` +For advanced, subset-based coloring, use Collections with GFQL AST helpers: + +.. code-block:: python + + collections = [ + { + "type": "set", + "name": "VIP", + "node_color": "#FF8800", + "expr": [graphistry.n({"vip": True})], + } + ] + g.collections(collections=collections, show_collections=True).plot() + +See :ref:`Layout settings ` and the +`Collections tutorial notebook `_. + Additional settings, such as background colors and logo watermarks, can also be configured. diff --git a/docs/source/cheatsheet.md b/docs/source/cheatsheet.md index bbe887b382..69ab005472 100644 --- a/docs/source/cheatsheet.md +++ b/docs/source/cheatsheet.md @@ -560,6 +560,11 @@ g.encode_point_color('type', as_categorical=True, categorical_mapping={"cat": "red", "sheep": "blue"}, default_mapping='#CCC') ``` +For subset-based coloring and conditional styling across multiple encodings, use Collections +via `g.collections(...)` with GFQL AST helpers. See the +[layout settings](https://pygraphistry.readthedocs.io/en/latest/visualization/layout/settings.html) +and the [Collections tutorial notebook](https://github.com/graphistry/pygraphistry/blob/master/demos/more_examples/graphistry_features/collections.ipynb). + For more in-depth examples, check out the tutorials on [colors](https://github.com/graphistry/pygraphistry/tree/master/demos/more_examples/graphistry_features/encodings-colors.ipynb). ### Custom icons and badges diff --git a/docs/source/visualization/10min.rst b/docs/source/visualization/10min.rst index 60e7f10c33..8666c7a4d8 100644 --- a/docs/source/visualization/10min.rst +++ b/docs/source/visualization/10min.rst @@ -224,6 +224,23 @@ You can encode your graph attributes visually using colors, sizes, icons, and mo - :meth:`graphistry.PlotterBase.PlotterBase.encode_edge_color` - :meth:`graphistry.PlotterBase.PlotterBase.encode_edge_icon` +* **Collections (advanced coloring)**: Define subsets using GFQL AST helpers and color them consistently: + + .. code-block:: python + + collections = [ + { + "type": "set", + "name": "Subscribers", + "node_color": "#32CD32", + "expr": [graphistry.n({"subscribed_to_newsletter": True})], + } + ] + g.collections(collections=collections, show_collections=True).plot() + + See :doc:`Layout settings ` and the + `Collections tutorial notebook `_. + * **Bind**: Simpler data-driven settings are done through :meth:`graphistry.PlotterBase.PlotterBase.bind`: .. code-block:: python diff --git a/docs/source/visualization/index.rst b/docs/source/visualization/index.rst index 5aaba1745e..95daf6632a 100644 --- a/docs/source/visualization/index.rst +++ b/docs/source/visualization/index.rst @@ -2,6 +2,8 @@ Visualize ============= We recommend getting started with :ref:`10 Minutes to PyGraphistry <10min-pygraphistry>`, :ref:`10 Minutes to Graphistry Visualization<10min-viz>`, and the :ref:`layout guide `. +For advanced, subset-based coloring, see :ref:`Layout settings ` and the +`Collections tutorial notebook `_. For static image export (documentation, reports), see the `static rendering tutorial <../demos/demos_databases_apis/graphviz/static_rendering.ipynb>`_. From 7023f8c1bc2ceeeae86f74c956b4a2452cc98a1f Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 16:09:29 -0800 Subject: [PATCH 04/25] docs: link color encodings from collections --- demos/more_examples/graphistry_features/collections.ipynb | 7 +++++++ docs/source/visualization/layout/settings.rst | 1 + 2 files changed, 8 insertions(+) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index f8274040aa..75bf653f16 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -89,6 +89,13 @@ "source": [ "To render, authenticate and call `g2.plot()` as usual." ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For more on color encodings, see the [Color encodings notebook](https://github.com/graphistry/pygraphistry/blob/master/demos/more_examples/graphistry_features/encodings-colors.ipynb).\n" + ] } ], "metadata": { diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 72157d5d80..1d985588dd 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -67,6 +67,7 @@ The collections list is JSON-minified and URL-encoded automatically. GFQL operat Python AST helpers; see `GFQL documentation `_. For full schema details, see `Collections URL options `_. For a full walkthrough, see the `Collections tutorial notebook `_. +For color encoding basics, see the `Color encodings notebook `_. Styling the Background and Foreground From 86f3b985768e889e1ceb64d05a09972c70ab4744 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 16:14:48 -0800 Subject: [PATCH 05/25] docs: replace absolute collections links --- demos/more_examples/graphistry_features/collections.ipynb | 2 +- docs/source/10min.rst | 2 +- docs/source/cheatsheet.md | 4 ++-- docs/source/visualization/10min.rst | 2 +- docs/source/visualization/index.rst | 2 +- docs/source/visualization/layout/settings.rst | 6 +++--- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 75bf653f16..6e4beb2fe1 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -94,7 +94,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "For more on color encodings, see the [Color encodings notebook](https://github.com/graphistry/pygraphistry/blob/master/demos/more_examples/graphistry_features/encodings-colors.ipynb).\n" + "For more on color encodings, see the [Color encodings notebook](encodings-colors.ipynb).\n" ] } ], diff --git a/docs/source/10min.rst b/docs/source/10min.rst index 2a57ed2ab7..85d462d746 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -188,7 +188,7 @@ For advanced, subset-based coloring, use Collections with GFQL AST helpers: g.collections(collections=collections, show_collections=True).plot() See :ref:`Layout settings ` and the -`Collections tutorial notebook `_. +:doc:`Collections tutorial notebook `. Additional settings, such as background colors and logo watermarks, can also be configured. diff --git a/docs/source/cheatsheet.md b/docs/source/cheatsheet.md index 69ab005472..a03abe9a59 100644 --- a/docs/source/cheatsheet.md +++ b/docs/source/cheatsheet.md @@ -562,8 +562,8 @@ g.encode_point_color('type', as_categorical=True, For subset-based coloring and conditional styling across multiple encodings, use Collections via `g.collections(...)` with GFQL AST helpers. See the -[layout settings](https://pygraphistry.readthedocs.io/en/latest/visualization/layout/settings.html) -and the [Collections tutorial notebook](https://github.com/graphistry/pygraphistry/blob/master/demos/more_examples/graphistry_features/collections.ipynb). +[layout settings](visualization/layout/settings.html) +and the [Collections tutorial notebook](demos/more_examples/graphistry_features/collections.ipynb). For more in-depth examples, check out the tutorials on [colors](https://github.com/graphistry/pygraphistry/tree/master/demos/more_examples/graphistry_features/encodings-colors.ipynb). diff --git a/docs/source/visualization/10min.rst b/docs/source/visualization/10min.rst index 8666c7a4d8..f5c2bb9b23 100644 --- a/docs/source/visualization/10min.rst +++ b/docs/source/visualization/10min.rst @@ -239,7 +239,7 @@ You can encode your graph attributes visually using colors, sizes, icons, and mo g.collections(collections=collections, show_collections=True).plot() See :doc:`Layout settings ` and the - `Collections tutorial notebook `_. + :doc:`Collections tutorial notebook `. * **Bind**: Simpler data-driven settings are done through :meth:`graphistry.PlotterBase.PlotterBase.bind`: diff --git a/docs/source/visualization/index.rst b/docs/source/visualization/index.rst index 95daf6632a..cf85e2b7a2 100644 --- a/docs/source/visualization/index.rst +++ b/docs/source/visualization/index.rst @@ -3,7 +3,7 @@ Visualize We recommend getting started with :ref:`10 Minutes to PyGraphistry <10min-pygraphistry>`, :ref:`10 Minutes to Graphistry Visualization<10min-viz>`, and the :ref:`layout guide `. For advanced, subset-based coloring, see :ref:`Layout settings ` and the -`Collections tutorial notebook `_. +:doc:`Collections tutorial notebook `. For static image export (documentation, reports), see the `static rendering tutorial <../demos/demos_databases_apis/graphviz/static_rendering.ipynb>`_. diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 1d985588dd..c5e63c7889 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -64,10 +64,10 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections g2.plot() The collections list is JSON-minified and URL-encoded automatically. GFQL operations use the -Python AST helpers; see `GFQL documentation `_. +Python AST helpers; see :doc:`GFQL documentation `. For full schema details, see `Collections URL options `_. -For a full walkthrough, see the `Collections tutorial notebook `_. -For color encoding basics, see the `Color encodings notebook `_. +For a full walkthrough, see the :doc:`Collections tutorial notebook `. +For color encoding basics, see the :doc:`Color encodings notebook `. Styling the Background and Foreground From 59ba59049c9b847ca8a7b6741d2bc51e5f242af5 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 16:56:55 -0800 Subject: [PATCH 06/25] docs: expand collections guidance and validation --- .../graphistry_features/collections.ipynb | 33 ++++++++++++++++++ docs/source/visualization/layout/settings.rst | 34 +++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 6e4beb2fe1..b1ea620783 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -83,6 +83,39 @@ "g2._url_params\n" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Notes and validation\n", + "\n", + "- Order matters: earlier collections override later ones.\n", + "- Provide `id` for sets used by intersections.\n", + "- Global colors apply to nodes/edges not in any collection; `#` is optional.\n", + "- Use `validate='strict'` to raise, or `warn=False` to silence warnings.\n", + "\n", + "Wire protocol and pre-encoded strings:\n", + "\n", + "```python\n", + "collections_wire = [\n", + " {\n", + " \"type\": \"set\",\n", + " \"name\": \"Wire Protocol Example\",\n", + " \"node_color\": \"#AA00AA\",\n", + " \"expr\": {\n", + " \"type\": \"gfql_chain\",\n", + " \"gfql\": [\n", + " {\"type\": \"Node\", \"filter_dict\": {\"status\": \"purchased\"}}\n", + " ]\n", + " }\n", + " }\n", + "]\n", + "g.collections(collections=collections_wire)\n", + "\n", + "g.collections(collections=encoded_collections, encode=False)\n", + "```\n" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index c5e63c7889..08ba0af0e0 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -69,6 +69,40 @@ For full schema details, see `Collections URL options `. For color encoding basics, see the :doc:`Color encodings notebook `. +Notes and validation +^^^^^^^^^^^^^^^^^^^^ + +- Order matters: earlier collections have higher priority and override later ones. +- Intersections reference set IDs; provide ``id`` for any set used in an intersection. +- Omitting ``node_color`` or ``edge_color`` leaves encodings as passthrough. +- ``collections_global_node_color`` and ``collections_global_edge_color`` apply to nodes/edges + not in any collection (leading ``#`` is optional). +- Accepted inputs for ``expr`` include GFQL AST helpers, ``Chain`` objects, and wire-protocol dicts. +- Use ``validate='strict'`` to raise on invalid collections; the default ``autofix`` warns and + drops invalid entries. Use ``warn=False`` to silence warnings. +- If you already have an encoded collections string, pass ``encode=False``. When using + ``settings(url_params=...)`` directly, provide an encoded ``collections`` value. + +Wire protocol example +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + collections_wire = [ + { + "type": "set", + "name": "Wire Protocol Example", + "node_color": "#AA00AA", + "expr": { + "type": "gfql_chain", + "gfql": [ + {"type": "Node", "filter_dict": {"status": "purchased"}} + ] + } + } + ] + g.collections(collections=collections_wire) + Styling the Background and Foreground ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 76d86cbf797fbf3f3fb0464c967ca12f43417d86 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Mon, 29 Dec 2025 16:59:04 -0800 Subject: [PATCH 07/25] docs: add quick collections tips --- docs/source/10min.rst | 1 + docs/source/visualization/10min.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/source/10min.rst b/docs/source/10min.rst index 85d462d746..2ba793facb 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -189,6 +189,7 @@ For advanced, subset-based coloring, use Collections with GFQL AST helpers: See :ref:`Layout settings ` and the :doc:`Collections tutorial notebook `. +Tip: order matters (earlier collections override later ones) and intersections require set IDs. Additional settings, such as background colors and logo watermarks, can also be configured. diff --git a/docs/source/visualization/10min.rst b/docs/source/visualization/10min.rst index f5c2bb9b23..528f90be4f 100644 --- a/docs/source/visualization/10min.rst +++ b/docs/source/visualization/10min.rst @@ -240,6 +240,7 @@ You can encode your graph attributes visually using colors, sizes, icons, and mo See :doc:`Layout settings ` and the :doc:`Collections tutorial notebook `. + Tip: order matters (earlier collections override later ones) and intersections require set IDs. * **Bind**: Simpler data-driven settings are done through :meth:`graphistry.PlotterBase.PlotterBase.bind`: From 6f125d54fed677117275b99622ce86c695fc2225 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 00:57:17 -0800 Subject: [PATCH 08/25] docs: clarify when to use collections --- demos/more_examples/graphistry_features/collections.ipynb | 1 + docs/source/visualization/layout/settings.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index b1ea620783..99dce83ecd 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -90,6 +90,7 @@ "## Notes and validation\n", "\n", "- Order matters: earlier collections override later ones.\n", + "- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors.\n", "- Provide `id` for sets used by intersections.\n", "- Global colors apply to nodes/edges not in any collection; `#` is optional.\n", "- Use `validate='strict'` to raise, or `warn=False` to silence warnings.\n", diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 08ba0af0e0..b498441355 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -73,6 +73,7 @@ Notes and validation ^^^^^^^^^^^^^^^^^^^^ - Order matters: earlier collections have higher priority and override later ones. +- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors. - Intersections reference set IDs; provide ``id`` for any set used in an intersection. - Omitting ``node_color`` or ``edge_color`` leaves encodings as passthrough. - ``collections_global_node_color`` and ``collections_global_edge_color`` apply to nodes/edges From 21ca5d06791600a580bd32683d4034e3173bc008 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 13:09:31 -0800 Subject: [PATCH 09/25] docs: add collections overlap example --- .../graphistry_features/collections.ipynb | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 99dce83ecd..af979c4933 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -124,6 +124,35 @@ "To render, authenticate and call `g2.plot()` as usual." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Overlap priority example\n", + "\n", + "Earlier collections override later ones when they overlap.\n", + "\n", + "```python\n", + "collections_priority = [\n", + " {\n", + " \"type\": \"set\",\n", + " \"id\": \"vip\",\n", + " \"name\": \"VIP\",\n", + " \"node_color\": \"#FFAA00\",\n", + " \"expr\": [graphistry.n({\"vip\": True})],\n", + " },\n", + " {\n", + " \"type\": \"set\",\n", + " \"id\": \"recent\",\n", + " \"name\": \"Recent\",\n", + " \"node_color\": \"#00BFFF\",\n", + " \"expr\": [graphistry.n({\"recent\": True})],\n", + " },\n", + "]\n", + "g.collections(collections=collections_priority)\n", + "```\n" + ] + }, { "cell_type": "markdown", "metadata": {}, From 29f3847dd72f15942748978bc7f2137d78ad15cc Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 13:52:40 -0800 Subject: [PATCH 10/25] docs: mention collections helper constructors --- demos/more_examples/graphistry_features/collections.ipynb | 1 + docs/source/visualization/layout/settings.rst | 2 ++ 2 files changed, 3 insertions(+) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index af979c4933..4e1516bdbc 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -91,6 +91,7 @@ "\n", "- Order matters: earlier collections override later ones.\n", "- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors.\n", + "- Helper constructors: `graphistry.collection_set(...)` and `graphistry.collection_intersection(...)` return dicts for `collections=`.\n", "- Provide `id` for sets used by intersections.\n", "- Global colors apply to nodes/edges not in any collection; `#` is optional.\n", "- Use `validate='strict'` to raise, or `warn=False` to silence warnings.\n", diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index b498441355..af96be1d28 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -74,6 +74,8 @@ Notes and validation - Order matters: earlier collections have higher priority and override later ones. - Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors. +- Helper constructors: ``graphistry.collection_set(...)`` and ``graphistry.collection_intersection(...)`` + return dicts you can pass to ``collections=`` (useful for typed/structured construction). - Intersections reference set IDs; provide ``id`` for any set used in an intersection. - Omitting ``node_color`` or ``edge_color`` leaves encodings as passthrough. - ``collections_global_node_color`` and ``collections_global_edge_color`` apply to nodes/edges From 7f5555cee4baf9ee2bc2d8bfdfa2482af64a81c0 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 14:14:25 -0800 Subject: [PATCH 11/25] docs: note helpers wrap ast to gfql chain --- demos/more_examples/graphistry_features/collections.ipynb | 2 +- docs/source/visualization/layout/settings.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 4e1516bdbc..2b9bf8b28a 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -91,7 +91,7 @@ "\n", "- Order matters: earlier collections override later ones.\n", "- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors.\n", - "- Helper constructors: `graphistry.collection_set(...)` and `graphistry.collection_intersection(...)` return dicts for `collections=`.\n", + "- Helper constructors: `graphistry.collection_set(...)` and `graphistry.collection_intersection(...)` return JSON-friendly dicts (AST inputs wrap to `gfql_chain`).\n", "- Provide `id` for sets used by intersections.\n", "- Global colors apply to nodes/edges not in any collection; `#` is optional.\n", "- Use `validate='strict'` to raise, or `warn=False` to silence warnings.\n", diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index af96be1d28..109a906e7f 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -75,7 +75,7 @@ Notes and validation - Order matters: earlier collections have higher priority and override later ones. - Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors. - Helper constructors: ``graphistry.collection_set(...)`` and ``graphistry.collection_intersection(...)`` - return dicts you can pass to ``collections=`` (useful for typed/structured construction). + return JSON-friendly dicts (AST inputs are wrapped into ``gfql_chain``) for ``collections=``. - Intersections reference set IDs; provide ``id`` for any set used in an intersection. - Omitting ``node_color`` or ``edge_color`` leaves encodings as passthrough. - ``collections_global_node_color`` and ``collections_global_edge_color`` apply to nodes/edges From 3d35f9fe6f3a37eabe461788a758bd5c69eccc8f Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 14:18:13 -0800 Subject: [PATCH 12/25] docs: use collections helper constructors --- .../graphistry_features/collections.ipynb | 40 ++++++++----------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 2b9bf8b28a..2256e50ac5 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -48,29 +48,23 @@ "outputs": [], "source": [ "collections = [\n", - " {\n", - " 'type': 'set',\n", - " 'id': 'purchasers',\n", - " 'name': 'Purchasers',\n", - " 'node_color': '#00BFFF',\n", - " 'expr': [graphistry.n({'status': 'purchased'})],\n", - " },\n", - " {\n", - " 'type': 'set',\n", - " 'id': 'subscribers',\n", - " 'name': 'Subscribers',\n", - " 'node_color': '#32CD32',\n", - " 'expr': [graphistry.n({'subscribed': True})],\n", - " },\n", - " {\n", - " 'type': 'intersection',\n", - " 'name': 'High Value Subscribers',\n", - " 'node_color': '#AABBCC',\n", - " 'expr': {\n", - " 'type': 'intersection',\n", - " 'sets': ['purchasers', 'subscribers']\n", - " }\n", - " },\n", + " graphistry.collection_set(\n", + " expr=graphistry.n({'status': 'purchased'}),\n", + " id='purchasers',\n", + " name='Purchasers',\n", + " node_color='#00BFFF',\n", + " ),\n", + " graphistry.collection_set(\n", + " expr=graphistry.n({'subscribed': True}),\n", + " id='subscribers',\n", + " name='Subscribers',\n", + " node_color='#32CD32',\n", + " ),\n", + " graphistry.collection_intersection(\n", + " sets=['purchasers', 'subscribers'],\n", + " name='High Value Subscribers',\n", + " node_color='#AABBCC',\n", + " ),\n", "]\n", "\n", "g2 = g.collections(\n", From 60d63be483acdc44c75b844ad4b6ed1dbdc5d8ae Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 14:23:08 -0800 Subject: [PATCH 13/25] docs: use collections helpers in examples --- docs/source/10min.rst | 11 +++++------ docs/source/visualization/10min.rst | 11 +++++------ docs/source/visualization/layout/settings.rst | 13 ++++++------- 3 files changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/source/10min.rst b/docs/source/10min.rst index 2ba793facb..354cee51a4 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -178,12 +178,11 @@ For advanced, subset-based coloring, use Collections with GFQL AST helpers: .. code-block:: python collections = [ - { - "type": "set", - "name": "VIP", - "node_color": "#FF8800", - "expr": [graphistry.n({"vip": True})], - } + graphistry.collection_set( + expr=graphistry.n({"vip": True}), + name="VIP", + node_color="#FF8800", + ) ] g.collections(collections=collections, show_collections=True).plot() diff --git a/docs/source/visualization/10min.rst b/docs/source/visualization/10min.rst index 528f90be4f..de84a80a04 100644 --- a/docs/source/visualization/10min.rst +++ b/docs/source/visualization/10min.rst @@ -229,12 +229,11 @@ You can encode your graph attributes visually using colors, sizes, icons, and mo .. code-block:: python collections = [ - { - "type": "set", - "name": "Subscribers", - "node_color": "#32CD32", - "expr": [graphistry.n({"subscribed_to_newsletter": True})], - } + graphistry.collection_set( + expr=graphistry.n({"subscribed_to_newsletter": True}), + name="Subscribers", + node_color="#32CD32", + ) ] g.collections(collections=collections, show_collections=True).plot() diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 109a906e7f..ed2846c69f 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -46,13 +46,12 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections import graphistry collections = [ - { - "type": "set", - "id": "newsletter_subscribers", - "name": "Newsletter Subscribers", - "node_color": "#32CD32", - "expr": [graphistry.n({"subscribed_to_newsletter": True})], - } + graphistry.collection_set( + expr=graphistry.n({"subscribed_to_newsletter": True}), + id="newsletter_subscribers", + name="Newsletter Subscribers", + node_color="#32CD32", + ) ] g2 = g.collections( From fc05db791b091cdf9e1edd4fd1592473c628c772 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 14:23:20 -0800 Subject: [PATCH 14/25] docs: add collections wire protocol note --- docs/source/gfql/wire_protocol_examples.md | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/source/gfql/wire_protocol_examples.md b/docs/source/gfql/wire_protocol_examples.md index 01db9e8ddf..d900fc1543 100644 --- a/docs/source/gfql/wire_protocol_examples.md +++ b/docs/source/gfql/wire_protocol_examples.md @@ -579,3 +579,29 @@ filter3 = n(filter_dict={"date": gt({"type": "datetime", "value": "2023-01-01T00 - Timezone conversions are handled efficiently - For large datasets, ensure datetime columns are properly typed (not object dtype) - Use `pd.Timestamp` for best performance when creating many predicates programmatically + +## Collections and Wire Protocol + +Collections accept GFQL wire protocol dicts inside the `expr` field for set definitions. +You can pass the dict directly or through the helper constructors: + +```python +import graphistry + +collections = [ + graphistry.collection_set( + expr={ + "type": "gfql_chain", + "gfql": [ + {"type": "Node", "filter_dict": {"status": {"type": "EQ", "val": "purchased"}}} + ], + }, + name="Purchasers", + node_color="#00BFFF", + ) +] +g.collections(collections=collections) +``` + +See the [Collections guide](../visualization/layout/settings.html) for full usage details and +intersection examples. From 3cda05f1adbdcab047d30e92ce0f7310ab12ba6d Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 14:27:45 -0800 Subject: [PATCH 15/25] docs: note collections after gfql --- docs/source/gfql/quick.rst | 3 +++ docs/source/gfql/remote.rst | 7 +++++++ 2 files changed, 10 insertions(+) diff --git a/docs/source/gfql/quick.rst b/docs/source/gfql/quick.rst index dcaa3fcdc5..e98fd2d326 100644 --- a/docs/source/gfql/quick.rst +++ b/docs/source/gfql/quick.rst @@ -637,6 +637,9 @@ Run graph algorithms like PageRank, community detection, and layouts directly wi # Results have x, y coordinates for visualization result.plot() +Tip: For subset-based coloring after GFQL, use ``result.collections(...)`` and see +:doc:`/visualization/layout/settings`. + Remote Graph References ----------------------- diff --git a/docs/source/gfql/remote.rst b/docs/source/gfql/remote.rst index cf5fd36f80..e81d6b9307 100644 --- a/docs/source/gfql/remote.rst +++ b/docs/source/gfql/remote.rst @@ -19,6 +19,13 @@ Run chain remotely and fetch results ``gfql_remote()`` accepts the same input types as local ``gfql()``: +.. note:: + Collections are visualization URL settings; apply them after GFQL results + (for example, ``g2.collections(...)``). The GFQL remote/upload APIs do not + accept collections payloads yet. + +Method :meth:`chain_remote ` runs chain remotely and fetched the computed graph + - **Chain / List[ASTObject]**: Native GFQL chain syntax (as above). - **Cypher string**: Compiled locally, sent as wire-protocol JSON. - **ASTLet / Let dict**: DAG patterns with named bindings. From ebf8f6e52eaf69f696b3054de7fcea73568152d5 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 15:49:15 -0800 Subject: [PATCH 16/25] docs: use helper imports in collections examples --- .../graphistry_features/collections.ipynb | 37 +++++++++---------- docs/source/10min.rst | 6 ++- docs/source/gfql/wire_protocol_examples.md | 4 +- docs/source/visualization/10min.rst | 6 ++- docs/source/visualization/layout/settings.rst | 6 +-- 5 files changed, 31 insertions(+), 28 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 2256e50ac5..44633572eb 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -24,6 +24,7 @@ "source": [ "import pandas as pd\n", "import graphistry\n", + "from graphistry import collection_set, collection_intersection, n\n", "\n", "edges = pd.DataFrame({\n", " 'src': ['acct1', 'acct2', 'acct3'],\n", @@ -48,19 +49,19 @@ "outputs": [], "source": [ "collections = [\n", - " graphistry.collection_set(\n", - " expr=graphistry.n({'status': 'purchased'}),\n", + " collection_set(\n", + " expr=n({'status': 'purchased'}),\n", " id='purchasers',\n", " name='Purchasers',\n", " node_color='#00BFFF',\n", " ),\n", - " graphistry.collection_set(\n", - " expr=graphistry.n({'subscribed': True}),\n", + " collection_set(\n", + " expr=n({'subscribed': True}),\n", " id='subscribers',\n", " name='Subscribers',\n", " node_color='#32CD32',\n", " ),\n", - " graphistry.collection_intersection(\n", + " collection_intersection(\n", " sets=['purchasers', 'subscribers'],\n", " name='High Value Subscribers',\n", " node_color='#AABBCC',\n", @@ -129,20 +130,18 @@ "\n", "```python\n", "collections_priority = [\n", - " {\n", - " \"type\": \"set\",\n", - " \"id\": \"vip\",\n", - " \"name\": \"VIP\",\n", - " \"node_color\": \"#FFAA00\",\n", - " \"expr\": [graphistry.n({\"vip\": True})],\n", - " },\n", - " {\n", - " \"type\": \"set\",\n", - " \"id\": \"recent\",\n", - " \"name\": \"Recent\",\n", - " \"node_color\": \"#00BFFF\",\n", - " \"expr\": [graphistry.n({\"recent\": True})],\n", - " },\n", + " collection_set(\n", + " expr=n({\"vip\": True}),\n", + " id=\"vip\",\n", + " name=\"VIP\",\n", + " node_color=\"#FFAA00\",\n", + " ),\n", + " collection_set(\n", + " expr=n({\"recent\": True}),\n", + " id=\"recent\",\n", + " name=\"Recent\",\n", + " node_color=\"#00BFFF\",\n", + " ),\n", "]\n", "g.collections(collections=collections_priority)\n", "```\n" diff --git a/docs/source/10min.rst b/docs/source/10min.rst index 354cee51a4..bbd80fabb9 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -177,9 +177,11 @@ For advanced, subset-based coloring, use Collections with GFQL AST helpers: .. code-block:: python + from graphistry import collection_set, n + collections = [ - graphistry.collection_set( - expr=graphistry.n({"vip": True}), + collection_set( + expr=n({"vip": True}), name="VIP", node_color="#FF8800", ) diff --git a/docs/source/gfql/wire_protocol_examples.md b/docs/source/gfql/wire_protocol_examples.md index d900fc1543..1a8e2e5fee 100644 --- a/docs/source/gfql/wire_protocol_examples.md +++ b/docs/source/gfql/wire_protocol_examples.md @@ -586,10 +586,10 @@ Collections accept GFQL wire protocol dicts inside the `expr` field for set defi You can pass the dict directly or through the helper constructors: ```python -import graphistry +from graphistry import collection_set collections = [ - graphistry.collection_set( + collection_set( expr={ "type": "gfql_chain", "gfql": [ diff --git a/docs/source/visualization/10min.rst b/docs/source/visualization/10min.rst index de84a80a04..9e35b5502e 100644 --- a/docs/source/visualization/10min.rst +++ b/docs/source/visualization/10min.rst @@ -228,9 +228,11 @@ You can encode your graph attributes visually using colors, sizes, icons, and mo .. code-block:: python + from graphistry import collection_set, n + collections = [ - graphistry.collection_set( - expr=graphistry.n({"subscribed_to_newsletter": True}), + collection_set( + expr=n({"subscribed_to_newsletter": True}), name="Subscribers", node_color="#32CD32", ) diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index ed2846c69f..e30becb431 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -43,11 +43,11 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections .. code-block:: python - import graphistry + from graphistry import collection_set, n collections = [ - graphistry.collection_set( - expr=graphistry.n({"subscribed_to_newsletter": True}), + collection_set( + expr=n({"subscribed_to_newsletter": True}), id="newsletter_subscribers", name="Newsletter Subscribers", node_color="#32CD32", From 264bad08fe941d240b0914f1f4b1090a88a14b86 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 16:36:46 -0800 Subject: [PATCH 17/25] docs: show graph-level collection chain --- demos/more_examples/graphistry_features/collections.ipynb | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 44633572eb..dc44cc91b2 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -24,7 +24,7 @@ "source": [ "import pandas as pd\n", "import graphistry\n", - "from graphistry import collection_set, collection_intersection, n\n", + "from graphistry import collection_set, collection_intersection, n, e_forward, Chain\n", "\n", "edges = pd.DataFrame({\n", " 'src': ['acct1', 'acct2', 'acct3'],\n", @@ -50,10 +50,11 @@ "source": [ "collections = [\n", " collection_set(\n", - " expr=n({'status': 'purchased'}),\n", + " expr=Chain([n({'status': 'purchased'}), e_forward(), n()]),\n", " id='purchasers',\n", - " name='Purchasers',\n", + " name='Purchasers + Connections',\n", " node_color='#00BFFF',\n", + " edge_color='#00BFFF',\n", " ),\n", " collection_set(\n", " expr=n({'subscribed': True}),\n", From 2325c29a632df369ad18d1f5e3d438e313edb3fb Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 16:47:16 -0800 Subject: [PATCH 18/25] docs: add plot call in collections notebook --- .../graphistry_features/collections.ipynb | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index dc44cc91b2..9a3ce9cd40 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -79,6 +79,16 @@ "g2._url_params\n" ] }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "# Render (requires graphistry.register(...))\n", + "g2.plot()\n" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -118,7 +128,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "To render, authenticate and call `g2.plot()` as usual." + "Run `g2.plot()` in a notebook session with valid credentials to render inline.\n" ] }, { From a1e0fa1a08f02a58f09bf8291d62da1d278e448f Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 30 Dec 2025 16:53:27 -0800 Subject: [PATCH 19/25] docs: use honeypot dataset in collections notebook --- .../graphistry_features/collections.ipynb | 50 ++++++++----------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 9a3ce9cd40..1a975872e4 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -22,24 +22,13 @@ "execution_count": null, "outputs": [], "source": [ + "from pathlib import Path\n", "import pandas as pd\n", "import graphistry\n", "from graphistry import collection_set, collection_intersection, n, e_forward, Chain\n", "\n", - "edges = pd.DataFrame({\n", - " 'src': ['acct1', 'acct2', 'acct3'],\n", - " 'dst': ['user1', 'user2', 'user3'],\n", - " 'rel': ['owns', 'owns', 'owns']\n", - "})\n", - "\n", - "nodes = pd.DataFrame({\n", - " 'id': ['acct1', 'acct2', 'acct3', 'user1', 'user2', 'user3'],\n", - " 'type': ['account', 'account', 'account', 'user', 'user', 'user'],\n", - " 'subscribed': [False, True, True, True, False, True],\n", - " 'status': ['purchased', 'purchased', 'new', 'new', 'purchased', 'new']\n", - "})\n", - "\n", - "g = graphistry.edges(edges, 'src', 'dst').nodes(nodes, 'id')\n" + "edges = pd.read_csv(Path('demos/data/honeypot.csv'))\n", + "g = graphistry.edges(edges, \"attackerIP\", \"victimIP\")\n" ] }, { @@ -48,24 +37,27 @@ "execution_count": null, "outputs": [], "source": [ + "# Use Chain to select subgraphs (nodes + edges) by edge attributes\n", "collections = [\n", " collection_set(\n", - " expr=Chain([n({'status': 'purchased'}), e_forward(), n()]),\n", - " id='purchasers',\n", - " name='Purchasers + Connections',\n", + " expr=Chain([n(), e_forward({\"vulnName\": \"MS08067 (NetAPI)\"}), n()]),\n", + " id='netapi',\n", + " name='MS08067 (NetAPI)',\n", " node_color='#00BFFF',\n", " edge_color='#00BFFF',\n", " ),\n", " collection_set(\n", - " expr=n({'subscribed': True}),\n", - " id='subscribers',\n", - " name='Subscribers',\n", + " expr=Chain([n(), e_forward({\"victimPort\": 445.0}), n()]),\n", + " id='port445',\n", + " name='Port 445',\n", " node_color='#32CD32',\n", + " edge_color='#32CD32',\n", " ),\n", " collection_intersection(\n", - " sets=['purchasers', 'subscribers'],\n", - " name='High Value Subscribers',\n", + " sets=['netapi', 'port445'],\n", + " name='NetAPI + 445',\n", " node_color='#AABBCC',\n", + " edge_color='#AABBCC',\n", " ),\n", "]\n", "\n", @@ -142,16 +134,18 @@ "```python\n", "collections_priority = [\n", " collection_set(\n", - " expr=n({\"vip\": True}),\n", - " id=\"vip\",\n", - " name=\"VIP\",\n", + " expr=Chain([n(), e_forward({\"vulnName\": \"MS08067 (NetAPI)\"}), n()]),\n", + " id=\"netapi\",\n", + " name=\"MS08067 (NetAPI)\",\n", " node_color=\"#FFAA00\",\n", + " edge_color=\"#FFAA00\",\n", " ),\n", " collection_set(\n", - " expr=n({\"recent\": True}),\n", - " id=\"recent\",\n", - " name=\"Recent\",\n", + " expr=Chain([n(), e_forward({\"victimPort\": 445.0}), n()]),\n", + " id=\"port445\",\n", + " name=\"Port 445\",\n", " node_color=\"#00BFFF\",\n", + " edge_color=\"#00BFFF\",\n", " ),\n", "]\n", "g.collections(collections=collections_priority)\n", From c6575bab1a57b5a068ce2509f6d6418f805dca64 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Fri, 2 Jan 2026 01:53:50 -0800 Subject: [PATCH 20/25] docs: clarify collections usage --- .../graphistry_features/collections.ipynb | 11 +++- docs/source/10min.rst | 33 ++++++----- docs/source/gfql/spec/wire_protocol.md | 44 ++++++++++++++ docs/source/gfql/wire_protocol_examples.md | 26 --------- docs/source/visualization/layout/settings.rst | 57 +++++-------------- 5 files changed, 84 insertions(+), 87 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index 1a975872e4..b8e1055a1c 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -6,14 +6,21 @@ "source": [ "# Collections in PyGraphistry\n", "\n", - "Define collections (subsets) using GFQL AST helpers and apply visual encodings." + "Collections define labeled subsets of a graph (nodes, edges, or subgraphs) using full GFQL. They enable advanced, layered styling that overrides base encodings when you need precise highlights.\n", + "\n", + "Use collections when you want:\n", + "- baseline encodings (for example, by entity type) plus overlays for alerts or critical paths\n", + "- multiple overlapping highlights with a priority order\n", + "- a UI panel for toggling focused subsets on and off\n", + "\n", + "Collections are evaluated in priority order, with higher priority collections overriding lower ones for styling.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Collections use GFQL operations (like `graphistry.n(...)`) to define sets, and can be combined using intersections." + "In this notebook, we build sets using GFQL AST helpers, combine them with intersections, and apply node and edge colors. Collections can be based on nodes, edges, or multi-step graph traversals (Chain).\n" ] }, { diff --git a/docs/source/10min.rst b/docs/source/10min.rst index bbd80fabb9..d8cfd79e14 100644 --- a/docs/source/10min.rst +++ b/docs/source/10min.rst @@ -161,19 +161,11 @@ Example visualization: Now, edges are colored based on the type of vulnerability, helping you distinguish different attack types. -Adjusting Sizes, Labels, Icons, Badges, and More ------------------------------------------------- - -You can adjust further node and edge settings using data. Sample calls include: - -- ``bind(point_title=)``: Assign labels to nodes based on a column -- ``encode_point_size()``: Adjust node sizes based on a column -- ``encode_point_icon()``: Assign different icons to nodes based on a column -- ``encode_point_badge()``: Add badges to nodes based on a column -- ``encode_point_weight()``: Adjust node weights based on a column -- Equivalent functions for edges: ``encode_edge_size()``, ``encode_edge_icon()``, ``encode_edge_badge()`` +Advanced: Collections for layered highlights +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For advanced, subset-based coloring, use Collections with GFQL AST helpers: +Use collections when you want GFQL-driven subsets (nodes, edges, or subgraphs) to override base encodings. +This is useful for overlays like alerts or critical paths that take precedence over your normal color rules. .. code-block:: python @@ -188,9 +180,20 @@ For advanced, subset-based coloring, use Collections with GFQL AST helpers: ] g.collections(collections=collections, show_collections=True).plot() -See :ref:`Layout settings ` and the -:doc:`Collections tutorial notebook `. -Tip: order matters (earlier collections override later ones) and intersections require set IDs. +See the :doc:`Collections tutorial notebook ` and +:doc:`GFQL docs ` for full details. + +Adjusting Sizes, Labels, Icons, Badges, and More +------------------------------------------------ + +You can adjust further node and edge settings using data. Sample calls include: + +- ``bind(point_title=)``: Assign labels to nodes based on a column +- ``encode_point_size()``: Adjust node sizes based on a column +- ``encode_point_icon()``: Assign different icons to nodes based on a column +- ``encode_point_badge()``: Add badges to nodes based on a column +- ``encode_point_weight()``: Adjust node weights based on a column +- Equivalent functions for edges: ``encode_edge_size()``, ``encode_edge_icon()``, ``encode_edge_badge()`` Additional settings, such as background colors and logo watermarks, can also be configured. diff --git a/docs/source/gfql/spec/wire_protocol.md b/docs/source/gfql/spec/wire_protocol.md index 9e1ca858d7..1612a90394 100644 --- a/docs/source/gfql/spec/wire_protocol.md +++ b/docs/source/gfql/spec/wire_protocol.md @@ -595,6 +595,50 @@ Example: **Note**: The `timezone` field is optional for DateTime values and defaults to "UTC" if omitted. This ensures consistent behavior across systems while allowing explicit timezone specification when needed. +## Collections Payloads + +Collections are Graphistry visualization overlays that use GFQL wire protocol operations to define subsets +of nodes, edges, or subgraphs. They are applied in priority order, with earlier collections overriding later +ones for styling. + +### Collection Set + +Collection sets wrap GFQL operations in a `gfql_chain` object: + +```json +{ + "type": "set", + "id": "purchasers", + "name": "Purchasers", + "node_color": "#00BFFF", + "expr": { + "type": "gfql_chain", + "gfql": [ + {"type": "Node", "filter_dict": {"status": "purchased"}} + ] + } +} +``` + +### Collection Intersection + +Intersections reference previously defined set IDs: + +```json +{ + "type": "intersection", + "name": "High Value Purchasers", + "node_color": "#AA00AA", + "expr": { + "type": "intersection", + "sets": ["purchasers", "vip"] + } +} +``` + +For Python examples and helper constructors, see the +:doc:`Collections tutorial notebook `. + ## Examples ### `MATCH ... RETURN` Row Pipeline diff --git a/docs/source/gfql/wire_protocol_examples.md b/docs/source/gfql/wire_protocol_examples.md index 1a8e2e5fee..01db9e8ddf 100644 --- a/docs/source/gfql/wire_protocol_examples.md +++ b/docs/source/gfql/wire_protocol_examples.md @@ -579,29 +579,3 @@ filter3 = n(filter_dict={"date": gt({"type": "datetime", "value": "2023-01-01T00 - Timezone conversions are handled efficiently - For large datasets, ensure datetime columns are properly typed (not object dtype) - Use `pd.Timestamp` for best performance when creating many predicates programmatically - -## Collections and Wire Protocol - -Collections accept GFQL wire protocol dicts inside the `expr` field for set definitions. -You can pass the dict directly or through the helper constructors: - -```python -from graphistry import collection_set - -collections = [ - collection_set( - expr={ - "type": "gfql_chain", - "gfql": [ - {"type": "Node", "filter_dict": {"status": {"type": "EQ", "val": "purchased"}}} - ], - }, - name="Purchasers", - node_color="#00BFFF", - ) -] -g.collections(collections=collections) -``` - -See the [Collections guide](../visualization/layout/settings.html) for full usage details and -intersection examples. diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index e30becb431..4abfb71eb7 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -36,10 +36,22 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.scene_settings` to modify the appe - ``edge_opacity``: Range 0.0 to 1.0 (0.0 fully transparent, 1.0 fully opaque, displayed as 0-100 in UI) - ``point_opacity``: Range 0.0 to 1.0 (0.0 fully transparent, 1.0 fully opaque, displayed as 0-100 in UI) +Encodings (Color, Size, Icons) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``encode_*`` methods to style nodes and edges based on columns (for example, color by entity type). +See the :doc:`Color encodings notebook ` for full examples. + Collections ~~~~~~~~~~~ -Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections (subsets) with optional encodings: +Collections define labeled subsets (nodes, edges, or subgraphs) using full GFQL and apply layered styling +that overrides base encodings. Use them to call out alerts or critical paths on top of your standard color +encodings, with priority-based overrides when subsets overlap. + +For a full walkthrough, see the :doc:`Collections tutorial notebook `. +For GFQL syntax, see :doc:`GFQL documentation `. +For schema details, see `Collections URL options `_. .. code-block:: python @@ -62,49 +74,6 @@ Use :meth:`graphistry.PlotterBase.PlotterBase.collections` to define collections ) g2.plot() -The collections list is JSON-minified and URL-encoded automatically. GFQL operations use the -Python AST helpers; see :doc:`GFQL documentation `. -For full schema details, see `Collections URL options `_. -For a full walkthrough, see the :doc:`Collections tutorial notebook `. -For color encoding basics, see the :doc:`Color encodings notebook `. - -Notes and validation -^^^^^^^^^^^^^^^^^^^^ - -- Order matters: earlier collections have higher priority and override later ones. -- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors. -- Helper constructors: ``graphistry.collection_set(...)`` and ``graphistry.collection_intersection(...)`` - return JSON-friendly dicts (AST inputs are wrapped into ``gfql_chain``) for ``collections=``. -- Intersections reference set IDs; provide ``id`` for any set used in an intersection. -- Omitting ``node_color`` or ``edge_color`` leaves encodings as passthrough. -- ``collections_global_node_color`` and ``collections_global_edge_color`` apply to nodes/edges - not in any collection (leading ``#`` is optional). -- Accepted inputs for ``expr`` include GFQL AST helpers, ``Chain`` objects, and wire-protocol dicts. -- Use ``validate='strict'`` to raise on invalid collections; the default ``autofix`` warns and - drops invalid entries. Use ``warn=False`` to silence warnings. -- If you already have an encoded collections string, pass ``encode=False``. When using - ``settings(url_params=...)`` directly, provide an encoded ``collections`` value. - -Wire protocol example -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - collections_wire = [ - { - "type": "set", - "name": "Wire Protocol Example", - "node_color": "#AA00AA", - "expr": { - "type": "gfql_chain", - "gfql": [ - {"type": "Node", "filter_dict": {"status": "purchased"}} - ] - } - } - ] - g.collections(collections=collections_wire) - Styling the Background and Foreground ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 25c7bc5657915b21c841a11851d88e623797fc72 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Tue, 13 Jan 2026 02:01:29 -0800 Subject: [PATCH 21/25] docs: trigger ci --- docs/source/visualization/layout/settings.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index 4abfb71eb7..c236891a94 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -3,6 +3,8 @@ Layout Settings & Visualization Embedding ========================================= +.. CI: trigger docs build + This guide shows how to embed and configure Graphistry visualizations using the PyGraphistry Python API. For users interested in using URL parameters for embedding in HTML, refer to the external documentation. Using PyGraphistry for Customization From 874f367a5f9fa60904ded54bad50268241aa3b1a Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 22 Apr 2026 20:25:09 -0700 Subject: [PATCH 22/25] docs: fix layout settings cross-reference for PDF build --- docs/source/cheatsheet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/cheatsheet.md b/docs/source/cheatsheet.md index a03abe9a59..67df59371c 100644 --- a/docs/source/cheatsheet.md +++ b/docs/source/cheatsheet.md @@ -561,8 +561,8 @@ g.encode_point_color('type', as_categorical=True, ``` For subset-based coloring and conditional styling across multiple encodings, use Collections -via `g.collections(...)` with GFQL AST helpers. See the -[layout settings](visualization/layout/settings.html) +via `g.collections(...)` with GFQL AST helpers. See +{doc}`Layout settings ` and the [Collections tutorial notebook](demos/more_examples/graphistry_features/collections.ipynb). For more in-depth examples, check out the tutorials on [colors](https://github.com/graphistry/pygraphistry/tree/master/demos/more_examples/graphistry_features/encodings-colors.ipynb). From 6731d37c28c9d5cf8299a8e9b1b7b43f0e218f67 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 22 Apr 2026 20:40:32 -0700 Subject: [PATCH 23/25] docs: retrigger readthedocs build From 93f5ea2ac520368c977c1665524b210289093ef7 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Thu, 23 Apr 2026 00:21:01 -0700 Subject: [PATCH 24/25] docs: fix collections doc review follow-ups --- demos/more_examples/graphistry_features/collections.ipynb | 4 ++-- docs/source/gfql/remote.rst | 2 +- docs/source/visualization/layout/settings.rst | 2 -- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/demos/more_examples/graphistry_features/collections.ipynb b/demos/more_examples/graphistry_features/collections.ipynb index b8e1055a1c..71864b3e06 100644 --- a/demos/more_examples/graphistry_features/collections.ipynb +++ b/demos/more_examples/graphistry_features/collections.ipynb @@ -95,7 +95,7 @@ "## Notes and validation\n", "\n", "- Order matters: earlier collections override later ones.\n", - "- Use collections for priority-based subsets and overlaps; use encode_* for simple column-driven colors.\n", + "- Use collections for priority-based subsets and overlaps; use `encode_*` for simple column-driven colors.\n", "- Helper constructors: `graphistry.collection_set(...)` and `graphistry.collection_intersection(...)` return JSON-friendly dicts (AST inputs wrap to `gfql_chain`).\n", "- Provide `id` for sets used by intersections.\n", "- Global colors apply to nodes/edges not in any collection; `#` is optional.\n", @@ -180,4 +180,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/docs/source/gfql/remote.rst b/docs/source/gfql/remote.rst index e81d6b9307..5b24d08e8c 100644 --- a/docs/source/gfql/remote.rst +++ b/docs/source/gfql/remote.rst @@ -24,7 +24,7 @@ Run chain remotely and fetch results (for example, ``g2.collections(...)``). The GFQL remote/upload APIs do not accept collections payloads yet. -Method :meth:`chain_remote ` runs chain remotely and fetched the computed graph +Method :meth:`chain_remote ` runs chain remotely and fetches the computed graph - **Chain / List[ASTObject]**: Native GFQL chain syntax (as above). - **Cypher string**: Compiled locally, sent as wire-protocol JSON. diff --git a/docs/source/visualization/layout/settings.rst b/docs/source/visualization/layout/settings.rst index c236891a94..4abfb71eb7 100644 --- a/docs/source/visualization/layout/settings.rst +++ b/docs/source/visualization/layout/settings.rst @@ -3,8 +3,6 @@ Layout Settings & Visualization Embedding ========================================= -.. CI: trigger docs build - This guide shows how to embed and configure Graphistry visualizations using the PyGraphistry Python API. For users interested in using URL parameters for embedding in HTML, refer to the external documentation. Using PyGraphistry for Customization From a9980d66e465da00869e6bcc498f421a5eacf5fa Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Thu, 23 Apr 2026 00:35:29 -0700 Subject: [PATCH 25/25] docs: retrigger readthedocs status