docs: clarify collections usage

Author: lmeyerov

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"
    ]
   },
   {

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 <layout-settings>` and the
-:doc:`Collections tutorial notebook </demos/more_examples/graphistry_features/collections>`.
-Tip: order matters (earlier collections override later ones) and intersections require set IDs.
+See the :doc:`Collections tutorial notebook </demos/more_examples/graphistry_features/collections>` and
+:doc:`GFQL docs </gfql/index>` 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.
 

docs/source/gfql/spec/wire_protocol.md

@@ -376,6 +376,50 @@ null                // null
 
 **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 </demos/more_examples/graphistry_features/collections>`.
+
 ## Examples
 
 ### User 360 Query

docs/source/gfql/wire_protocol_examples.md

@@ -514,29 +514,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.

docs/source/visualization/index.rst

@@ -2,7 +2,7 @@ Visualize
 =============
 
 We recommend getting started with :ref:`10 Minutes to PyGraphistry <10min>`, :ref:`10 Minutes to Graphistry Visualization<10min-viz>`, and the :ref:`layout guide <layout-guide>`.
-For advanced, subset-based coloring, see :ref:`Layout settings <layout-settings>` and the
+For advanced, subset-based coloring, see the
 :doc:`Collections tutorial notebook </demos/more_examples/graphistry_features/collections>`.
 
 For static image export (documentation, reports), see the `static rendering tutorial <../demos/demos_databases_apis/graphviz/static_rendering.ipynb>`_.

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 </demos/more_examples/graphistry_features/encodings-colors>` 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 </demos/more_examples/graphistry_features/collections>`.
+For GFQL syntax, see :doc:`GFQL documentation </gfql/index>`.
+For schema details, see `Collections URL options <https://hub.graphistry.com/docs/api/1/rest/url/#url-collections>`_.
 
 .. 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 </gfql/index>`.
-For full schema details, see `Collections URL options <https://hub.graphistry.com/docs/api/1/rest/url/#url-collections>`_.
-For a full walkthrough, see the :doc:`Collections tutorial notebook </demos/more_examples/graphistry_features/collections>`.
-For color encoding basics, see the :doc:`Color encodings notebook </demos/more_examples/graphistry_features/encodings-colors>`.
-
-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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~