Add pullback cover set labels and partial cluster labels to Mapper ho…

…vertext, improve docs (#445)

* Add pullback set ID to mapper hovertext

* Add partial cluster label to Mapper hovertext

* Improve docs for plot_static_mapper_graph and plot_interactive_mapper_graph

* Fix tests after changes

* Slight wording improvement

* Further wording clarification

* Make wording on edges even clearer

gtda/mapper/tests/test_visualization.py

@@ -77,7 +77,7 @@ def _get_widget_by_trait(self, fig, key, val=None):
                 pass
 
     def _get_size_from_hovertext(self, s):
-        size_str = s.split("<br>")[1].split(": ")[1]
+        size_str = s.split("<br>")[3].split(": ")[1]
         return int(size_str)
 
     def test_cluster_sizes(self):

gtda/mapper/utils/_visualization.py

@@ -90,15 +90,18 @@ def _get_node_size(node_elements):
 
 
 def _get_node_text(
-        node_ids, num_node_elements, node_summary_statistics
+        node_ids, pullback_set_labels, partial_cluster_labels,
+        num_node_elements, node_summary_statistics
 ):
     return [
-        f"Node ID: {node_id}<br>Node size: {num_elements}"
-        f"<br>Summary statistic: {node_summary_statistic}"
-        for node_id, num_elements, node_summary_statistic in zip(
-            node_ids, num_node_elements, node_summary_statistics
-            )
-        ]
+        f"Node ID: {node_id}<br>Pullback set label: {pullback_set_label}<br>"
+        f"Partial cluster label: {partial_cluster_label}<br>Node size: "
+        f"{num_elements}<br>Summary statistic: {node_summary_statistic}"
+        for (node_id, pullback_set_label, partial_cluster_label, num_elements,
+             node_summary_statistic)
+        in zip(node_ids, pullback_set_labels, partial_cluster_labels,
+               num_node_elements, node_summary_statistics)
+    ]
 
 
 def _get_node_summary(data, node_elements, summary_statistic):
@@ -263,12 +266,15 @@ def _calculate_graph_data(
 
     # Generate hovertext
     node_ids = graph["node_metadata"]["node_id"]
+    pullback_set_ids = graph["node_metadata"]["pullback_set_label"]
+    partial_cluster_labels = graph["node_metadata"]["partial_cluster_label"]
     num_node_elements = map(len, graph["node_metadata"]["node_elements"])
     node_colors_round = map(
         partial(_round_to_n_sig_figs, n=n_sig_figs), node_colors_color_variable
     )
     plot_options["node_trace"]["hovertext"] = _get_node_text(
-        node_ids, num_node_elements, node_colors_round
+        node_ids, pullback_set_ids, partial_cluster_labels,
+        num_node_elements, node_colors_round
     )
 
     # Compute graph layout

gtda/mapper/visualization.py

@@ -26,12 +26,31 @@ def plot_static_mapper_graph(
         color_by_columns_dropdown=False, clone_pipeline=True, n_sig_figs=3,
         node_scale=12, plotly_params=None
 ):
-    """Plotting function for static Mapper graphs.
-
-    Nodes are colored according to `color_variable` and `node_color_statistic`.
-    By default, the hovertext on each node displays a globally unique ID for
-    the node, the number of data points associated with the node, and the
-    summary statistic which determines its color.
+    """Plot Mapper graphs without interactivity on pipeline parameters.
+
+    The output graph is a rendition of the :class:`igraph.Graph` object
+    computed by calling the :meth:`fit_transform` method of the
+    :class:`~gtda.mapper.pipeline.MapperPipeline` instance `pipeline` on the
+    input `data`. The graph's nodes correspond to subsets of elements (rows) in
+    `data`; these subsets are clusters in larger portions of `data` called
+    "pullback (cover) sets", which are computed by means of the `pipeline`'s
+    "filter function" and "cover" and correspond to the differently-colored
+    portions in `this diagram <../../../../_images/mapper_pipeline.svg>`_.
+    Two clusters from different pullback cover sets can overlap; if they do, an
+    edge between the corresponding nodes in the graph may be drawn.
+
+    Nodes are colored according to `color_variable` and `node_color_statistic`
+    and are sized according to the number of elements they represent. The
+    hovertext on each node displays, in this order:
+
+        - a globally unique ID for the node, which can be used to retrieve
+          node information from the :class:`igraph.Graph` object, see
+          :class:`~gtda.mapper.nerve.Nerve`;
+        - the label of the pullback (cover) set which the node's elements
+          form a cluster in;
+        - a label identifying the node as a cluster within that pullback set;
+        - the number of elements of `data` associated with the node;
+        - the value of the summary statistic which determines the node's color.
 
     Parameters
     ----------
@@ -267,14 +286,11 @@ def plot_interactive_mapper_graph(
         color_by_columns_dropdown=False, n_sig_figs=3, node_scale=12,
         plotly_params=None
 ):
-    """Plotting function for interactive Mapper graphs.
-
-    Provides functionality to interactively update parameters from the cover
-    and clustering steps defined in `pipeline`. Nodes are colored according to
-    `color_variable` and `node_color_statistic`. By default, the hovertext on
-    each node displays a globally unique ID for the node, the number of data
-    points associated with the node, and the summary statistic which determines
-    its color.
+    """Plot Mapper graphs with interactivity on pipeline parameters.
+
+    Extends `~gtda.mapper.visualization.plot_static_mapper_graph` by providing
+    functionality to interactively update parameters from the cover and
+    clustering steps defined in `pipeline`.
 
     Parameters
     ----------