WIP

Mats-SX · Mats-SX · commit f96391e56e36 · 2025-09-25T11:46:26.000+02:00
diff --git a/graphdatascience/procedure_surface/api/centrality/betweenness_endpoints.py b/graphdatascience/procedure_surface/api/centrality/betweenness_endpoints.py
@@ -7,10 +7,12 @@
 
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.catalog.graph_api import GraphV2
+
 from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
 
 
 class BetweennessEndpoints(ABC):
+
     @abstractmethod
     def mutate(
         self,
diff --git a/graphdatascience/procedure_surface/api/centrality/pagerank_endpoints.py b/graphdatascience/procedure_surface/api/centrality/pagerank_endpoints.py
@@ -7,10 +7,12 @@
 
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.catalog.graph_api import GraphV2
+
 from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
 
 
 class PageRankEndpoints(ABC):
+
     @abstractmethod
     def mutate(
         self,
diff --git a/graphdatascience/procedure_surface/api/community/k1coloring_endpoints.py b/graphdatascience/procedure_surface/api/community/k1coloring_endpoints.py
@@ -11,9 +11,6 @@
 
 
 class K1ColoringEndpoints(ABC):
-    """
-    Abstract base class defining the API for the K-1 Coloring algorithm.
-    """
 
     @abstractmethod
     def mutate(
@@ -31,37 +28,43 @@ def mutate(
         job_id: Optional[Any] = None,
     ) -> K1ColoringMutateResult:
         """
-        Executes the K-1 Coloring algorithm and writes the results to the in-memory graph as node properties.
+        Runs the K-1 Coloring algorithm and stores the results in the graph catalog as a new node property.
+
+        The K-1 Coloring algorithm assigns a color to every node in the graph, trying to optimize for two objectives: 
+        to make sure that every neighbor of a given node has a different color than the node itself, and to use as few colors as possible.
+        Note that the graph coloring problem is proven to be NP-complete, which makes it intractable on anything but trivial graph sizes.
+        For that reason the implemented algorithm is a greedy algorithm that is neither guaranteed to produce an optimal solution nor always produce a correct result where no two neighboring nodes have different colors.
+        However, the precision can be controlled by the number of iterations this algorithm runs.
 
         Parameters
         ----------
         G : GraphV2
             The graph to run the algorithm on
         mutate_property : str
-            The property name to store the color for each node
+            Name of the node property to store the results in.
         batch_size : Optional[int], default=None
             The batch size for processing
         max_iterations : Optional[int], default=None
-            The maximum number of iterations of K-1 Coloring to run
+            Maximum number of iterations to run.
         relationship_types : Optional[List[str]], default=None
-            The relationships types used to select relationships for this algorithm run
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
         node_labels : Optional[List[str]], default=None
-            The node labels used to select nodes for this algorithm run
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
         sudo : Optional[bool], default=None
-            Override memory estimation limits
+            Disable the memory guard.
         log_progress : Optional[bool], default=None
-            Whether to log progress
+            Display progress logging.
         username : Optional[str], default=None
-            The username to attribute the procedure run to
+            As an administrator, run the algorithm as a different user, to access also their graphs.
         concurrency : Optional[Any], default=None
-            The number of concurrent threads
+            Number of CPU threads to use.
         job_id : Optional[Any], default=None
-            An identifier for the job
+            Identifier for the computation.
 
         Returns
         -------
         K1ColoringMutateResult
-            Algorithm metrics and statistics
+            Algorithm metrics and statistics including node coloring results
         """
         pass
 
diff --git a/graphdatascience/procedure_surface/api/community/kcore_endpoints.py b/graphdatascience/procedure_surface/api/community/kcore_endpoints.py
@@ -29,33 +29,38 @@ def mutate(
         job_id: Optional[Any] = None,
     ) -> KCoreMutateResult:
         """
-        Executes the K-Core algorithm and writes the results to the in-memory graph as node properties.
+        Runs the K-Core Decomposition algorithm and stores the results in the graph catalog as a new node property.
+
+        The K-core decomposition constitutes a process that separates the nodes in a graph into groups based on the degree sequence and topology of the graph.
+        The term `i-core` refers to a maximal subgraph of the original graph such that each node in this subgraph has degree at least `i`.
+        Each node is associated with a core value which denotes the largest value `i` such that the node belongs to the `i-core`.
+        Standard algorithms for K-Core Decomposition iteratively remove the node of lowest degree until the graph becomes empty.
 
         Parameters
         ----------
         G : GraphV2
             The graph to run the algorithm on
         mutate_property : str
-            The property name to store the core value for each node
+            Name of the node property to store the results in.
         relationship_types : Optional[List[str]], default=None
-            The relationships types used to select relationships for this algorithm run
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
         node_labels : Optional[List[str]], default=None
-            The node labels used to select nodes for this algorithm run
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
         sudo : Optional[bool], default=None
-            Override memory estimation limits
+            Disable the memory guard.
         log_progress : Optional[bool], default=None
-            Whether to log progress
+            Display progress logging.
         username : Optional[str], default=None
-            The username to attribute the procedure run to
+            As an administrator, run the algorithm as a different user, to access also their graphs.
         concurrency : Optional[Any], default=None
-            The number of concurrent threads
-        job_id : Optional[Any], default=None
-            An identifier for the job
+            Number of CPU threads to use.
+        job_id : Optional[Any] = None
+            Identifier for the computation.
 
         Returns
         -------
         KCoreMutateResult
-            Algorithm metrics and statistics
+            Algorithm metrics and statistics including core decomposition results
         """
         pass
 
diff --git a/graphdatascience/procedure_surface/api/community/louvain_endpoints.py b/graphdatascience/procedure_surface/api/community/louvain_endpoints.py
@@ -36,47 +36,51 @@ def mutate(
         relationship_weight_property: Optional[str] = None,
     ) -> LouvainMutateResult:
         """
-        Executes the Louvain algorithm and writes the results to the in-memory graph as node properties.
+        Runs the Louvain algorithm and stores the results in the graph catalog as a new node property.
+
+        The Louvain method is an algorithm to detect communities in large networks.
+        It maximizes a modularity score for each community, where the modularity quantifies the quality of an assignment of nodes to communities by evaluating how much more densely connected the nodes within a community are, compared to how connected they would be in a random network.
+        The Louvain algorithm is a hierarchical clustering algorithm that recursively merges communities into a single node and executes the modularity clustering on the condensed graphs.
 
         Parameters
         ----------
         G : GraphV2
             The graph to run the algorithm on
         mutate_property : str
-            The property name to store the community ID for each node
+            Name of the node property to store the results in.
         tolerance : Optional[float], default=None
-            The tolerance value for the algorithm convergence
+            Minimum change in scores between iterations.
         max_levels : Optional[int], default=None
             The maximum number of levels in the hierarchy
         include_intermediate_communities : Optional[bool], default=None
-            Whether to include intermediate community assignments
+            Whether to include intermediate communities
         max_iterations : Optional[int], default=None
-            The maximum number of iterations per level
+            Maximum number of iterations to run.
         relationship_types : Optional[List[str]], default=None
-            The relationships types used to select relationships for this algorithm run
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
         node_labels : Optional[List[str]], default=None
-            The node labels used to select nodes for this algorithm run
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
         sudo : Optional[bool], default=None
-            Override memory estimation limits
+            Disable the memory guard.
         log_progress : Optional[bool], default=None
-            Whether to log progress
+            Display progress logging.
         username : Optional[str], default=None
-            The username to attribute the procedure run to
+            As an administrator, run the algorithm as a different user, to access also their graphs.
         concurrency : Optional[Any], default=None
-            The number of concurrent threads
+            Number of CPU threads to use.
         job_id : Optional[Any], default=None
-            An identifier for the job
+            Identifier for the computation.
         seed_property : Optional[str], default=None
-            Defines node properties that are used as initial community identifiers
+            The property name that contains seed values
         consecutive_ids : Optional[bool], default=None
-            Flag to decide whether community identifiers are mapped into a consecutive id space
+            Whether to use consecutive IDs
         relationship_weight_property : Optional[str], default=None
-            The property name that contains weight
+            Name of the property to be used as weights.
 
         Returns
         -------
         LouvainMutateResult
-            Algorithm metrics and statistics
+            Algorithm metrics and statistics including community detection results
         """
         pass
 
diff --git a/graphdatascience/procedure_surface/api/community/scc_endpoints.py b/graphdatascience/procedure_surface/api/community/scc_endpoints.py
@@ -30,35 +30,39 @@ def mutate(
         consecutive_ids: Optional[bool] = None,
     ) -> SccMutateResult:
         """
-        Executes the SCC algorithm and writes the results to the in-memory graph as node properties.
+        Runs the Strongly Connected Components algorithm and stores the results in the graph catalog as a new node property.
+
+        The Strongly Connected Components (SCC) algorithm finds maximal sets of connected nodes in a directed graph.
+        A set is considered a strongly connected component if there is a directed path between each pair of nodes within the set.
+        It is often used early in a graph analysis process to help get an idea of how the graph is structured.
 
         Parameters
         ----------
         G : GraphV2
             The graph to run the algorithm on
         mutate_property : str
-            The property name to store the component ID for each node
+            Name of the node property to store the results in.
         relationship_types : Optional[List[str]], default=None
-            The relationships types used to select relationships for this algorithm run
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
         node_labels : Optional[List[str]], default=None
-            The node labels used to select nodes for this algorithm run
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
         sudo : Optional[bool], default=None
-            Override memory estimation limits
+            Disable the memory guard.
         log_progress : Optional[bool], default=None
-            Whether to log progress
+            Display progress logging.
         username : Optional[str], default=None
-            The username to attribute the procedure run to
+            As an administrator, run the algorithm as a different user, to access also their graphs.
         concurrency : Optional[Any], default=None
-            The number of concurrent threads
+            Number of CPU threads to use.
         job_id : Optional[Any], default=None
-            An identifier for the job
+            Identifier for the computation.
         consecutive_ids : Optional[bool], default=None
-            Flag to decide whether component identifiers are mapped into a consecutive id space
+            Whether to use consecutive IDs for components
 
         Returns
         -------
         SccMutateResult
-            Algorithm metrics and statistics
+            Algorithm metrics and statistics including strongly connected components results
         """
         pass
 
diff --git a/graphdatascience/procedure_surface/api/community/wcc_endpoints.py b/graphdatascience/procedure_surface/api/community/wcc_endpoints.py
@@ -33,41 +33,45 @@ def mutate(
         relationship_weight_property: Optional[str] = None,
     ) -> WccMutateResult:
         """
-        Executes the WCC algorithm and writes the results to the in-memory graph as node properties.
+        Runs the Weakly Connected Components algorithm and stores the results in the graph catalog as a new node property.
+
+        The Weakly Connected Components (WCC) algorithm finds sets of connected nodes in directed and undirected graphs where two nodes are connected if there exists a path between them.
+        In contrast to Strongly Connected Components (SCC), the direction of relationships on the path between two nodes is not considered.
+        WCC is often used early in an analysis to understand the structure of a graph, enabling running other algorithms independently on an identified cluster.
 
         Parameters
         ----------
         G : GraphV2
             The graph to run the algorithm on
         mutate_property : str
-            The property name to store the component ID for each node
+            Name of the node property to store the results in.
         threshold : Optional[float], default=None
             The minimum required weight to consider a relationship during traversal
         relationship_types : Optional[List[str]], default=None
-            The relationships types used to select relationships for this algorithm run
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
         node_labels : Optional[List[str]], default=None
-            The node labels used to select nodes for this algorithm run
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
         sudo : Optional[bool], default=None
-            Override memory estimation limits
+            Disable the memory guard.
         log_progress : Optional[bool], default=None
-            Whether to log progress
+            Display progress logging.
         username : Optional[str], default=None
-            The username to attribute the procedure run to
+            As an administrator, run the algorithm as a different user, to access also their graphs.
         concurrency : Optional[Any], default=None
-            The number of concurrent threads
+            Number of CPU threads to use.
         job_id : Optional[Any], default=None
-            An identifier for the job
+            Identifier for the computation.
         seed_property : Optional[str], default=None
-            Defines node properties that are used as initial component identifiers
+            The property name that contains seed values
         consecutive_ids : Optional[bool], default=None
-            Flag to decide whether component identifiers are mapped into a consecutive id space
+            Whether to use consecutive IDs for components
         relationship_weight_property : Optional[str], default=None
-            The property name that contains weight
+            Name of the property to be used as weights.
 
         Returns
         -------
         WccMutateResult
-            Algorithm metrics and statistics
+            Algorithm metrics and statistics including weakly connected components results
         """
         pass
 
