Repository: networkx/networkx

Issue:
Review ISMAGS methods
Related to discussion in #4761 

Some of the methods of the [ISMAGS class](https://github.com/networkx/networkx/blob/d70b314b37168f0ea7c5b0d7f9ff61d73232747b/networkx/algorithms/isomorphism/ismags.py#L227) are poorly documented; for example, methods like [`analyze_symmetry`](https://github.com/networkx/networkx/blob/d70b314b37168f0ea7c5b0d7f9ff61d73232747b/networkx/algorithms/isomorphism/ismags.py#L579-L593) are missing a detailed parameter description in the docstring. There is also some question (see #4761) as to whether this particular method was ever intended to be public in the first place.

At the very least, the documentation for `analyze_symmetry` in particular (and some of the other methods) should be improved to explain the parameters in the signature more clearly. 


Discussion:
Oops :) Sorry about that.
I'll leave it up to you whether it's valuable to keep `analyze_symmetry` public.
Either way, the docstring as-is is indeed wrong/insufficient.

Maybe:
```
def analyze_symmetry(self, graph, node_partitions, edge_colors):
    """    
    Find a minimal set of permutations and corresponding co-sets that    
    describe the symmetry of `graph`, given the node and edge equalities
    given by `node_partitions` and `edge_colors`, respectively.

    Parameters
    ----------
    graph: networkx.Graph
        The graph whose symmetry should be analyzed
    node_partitions: list[set]
        A list of sets containing node keys. Node keys in the same set are
        considered equivalent. Every node keys in `graph` should be in exactly
        one of the sets. If all nodes are equivalent, this should be `[set(graph.nodes)]`
        See also: :func:`make_partitions`.
    edge_colors: dict[collections.abc.Hashable, collections.abc.Hashable]
        A dict mapping every edge in `graph` as tuple of node keys (e.g. `(n1, n2)`)
        to a "color" (usually an integer). Edges with the same color are considered
        equivalent. If all edges are equivalent, this should be `{e: 0 for e in graph.edges}`.
        See also: :func:`partition_to_color`.

    Returns    
    -------    
    set[frozenset]     
        The found permutations. This is a set of frozensets of pairs of node     
        keys which can be exchanged without changing :attr:`subgraph`. 
    dict[collections.abc.Hashable, set[collections.abc.Hashable]]            
        The found co-sets. The co-sets is a dictionary of {node key:
        set of node keys}. Every key-value pair describes which `values`  
        can be interchanged without changing nodes less than `key`.       
    """
```
?

It may also be an idea to simplify this a little bit by making it accept edge_partitions instead of edge_colors, but again, I'll leave that up to you.
Unfortunately I don't have the time to open a PR for this :(
I also found a bug in my ISMAGS implementation (with fix), but I'll open a separate issue (#4915) for that.

Resolving patch:
diff --git a/networkx/algorithms/isomorphism/ismags.py b/networkx/algorithms/isomorphism/ismags.py
--- a/networkx/algorithms/isomorphism/ismags.py
+++ b/networkx/algorithms/isomorphism/ismags.py
@@ -579,17 +579,34 @@ def largest_common_subgraph(self, symmetry=True):
     def analyze_symmetry(self, graph, node_partitions, edge_colors):
         """
         Find a minimal set of permutations and corresponding co-sets that
-        describe the symmetry of :attr:`subgraph`.
+        describe the symmetry of `graph`, given the node and edge equalities
+        given by `node_partitions` and `edge_colors`, respectively.
+
+        Parameters
+        ----------
+        graph : networkx.Graph
+            The graph whose symmetry should be analyzed.
+        node_partitions : list of sets
+            A list of sets containining node keys. Node keys in the same set
+            are considered equivalent. Every node key in `graph` should be in
+            exactly one of the sets. If all nodes are equivalent, this should
+            be ``[set(graph.nodes)]``.
+        edge_colors : dict mapping edges to their colors
+            A dict mapping every edge in `graph` to its corresponding color.
+            Edges with the same color are considered equivalent. If all edges
+            are equivalent, this should be ``{e: 0 for e in graph.edges}``.
+
 
         Returns
         -------
         set[frozenset]
-            The found permutations. This is a set of frozenset of pairs of node
+            The found permutations. This is a set of frozensets of pairs of node
             keys which can be exchanged without changing :attr:`subgraph`.
         dict[collections.abc.Hashable, set[collections.abc.Hashable]]
-            The found co-sets. The co-sets is a dictionary of {node key:
-            set of node keys}. Every key-value pair describes which `values`
-            can be interchanged without changing nodes less than `key`.
+            The found co-sets. The co-sets is a dictionary of
+            ``{node key: set of node keys}``.
+            Every key-value pair describes which ``values`` can be interchanged
+            without changing nodes less than ``key``.
         """
         if self._symmetry_cache is not None:
             key = hash(


Test patch: