Comment and refactor

Author: Erdem Sariyuce

src/graph_notebook/magics/graph_magic.py

@@ -3928,18 +3928,18 @@ def handle_opencypher_status(self, line, local_ns):
 
 
 
-    # degreeDistribution
-    # Shows the degree distribution of vertices in the graph
+    # %degreeDistribution. Takes traversalDirection, vertexLabels, edgeLabels parameters, and visualizes
+    # the degree distribution.
     # TODO: Error handling
-    
+
     @line_magic
     @needs_local_scope
     @display_exceptions
     @neptune_graph_only
     def degreeDistribution(self, line, local_ns: dict = None):
         parser = argparse.ArgumentParser()
 
-        # Get the vertexLabels and edgeLabels from graph summary
+        # Get the vertexLabels and edgeLabels from graph summary, to be shown in the widgets for selection.
         try:
             summary_res = self.client.statistics("propertygraph", True, "detailed", True)
             summary_res.raise_for_status()
@@ -3967,13 +3967,13 @@ def degreeDistribution(self, line, local_ns: dict = None):
                                  "we will default to using all the edge labels.")
 
 
-        # # Additional parameters for output control
+        # TODO: Additional parameter for saving the visualization?
         # parser.add_argument('--export-to', type=str, default='',
         #                     help='Export the degree distribution results to the provided file path.')
 
         args = parser.parse_args(line.split())
 
-        # put the command line specified option as the value, if any; o.w. 'both'
+        # Put the selection specified on the command line, if any; o.w. default is 'both'
         td_val = args.traversalDirection
         td_val = td_val.lower() if td_val else 'both' 
 
@@ -3985,6 +3985,8 @@ def degreeDistribution(self, line, local_ns: dict = None):
             value = td_val
         )
 
+        # Put the vertex label(s) specified on the command line, if any; o.w. default is all the vertex labels (denoted by [])
+        available_vertex_labels = sorted(available_vertex_labels)
         selected_vlabels = args.vertexLabels if args.vertexLabels else []
         vertex_labels_select = widgets.SelectMultiple(
             options=available_vertex_labels,
@@ -3994,6 +3996,8 @@ def degreeDistribution(self, line, local_ns: dict = None):
             value = selected_vlabels
         )
 
+        # Put the edge label(s) specified on the command line, if any; o.w. default is all the edge labels (denoted by [])
+        available_edge_labels = sorted(available_edge_labels)
         selected_elabels = args.edgeLabels if args.edgeLabels else []
         edge_labels_select = widgets.SelectMultiple(
             options=available_edge_labels,
@@ -4010,7 +4014,7 @@ def degreeDistribution(self, line, local_ns: dict = None):
         display(td_dropdown, vertex_labels_select, edge_labels_select, submit_button, output)
 
         def on_button_clicked(b):
-            # Get selected traversal direction
+            # Get the selected parameters
             td = td_dropdown.value
             vlabels = list(vertex_labels_select.value)
             elabels = list(edge_labels_select.value)
@@ -4022,10 +4026,12 @@ def on_button_clicked(b):
             with output:
                 res = self.callDD(td, vlabels, elabels, local_ns)
 
+                # Retrieve the distribution
                 pairs = np.array(res['results'][0]['output']['distribution'])
                 keys = pairs[:,0]
                 values = pairs[:,1]
 
+                # Retrieve some statistics
                 max_deg = res['results'][0]['output']['statistics']['maxDeg']
                 median_deg = res['results'][0]['output']['statistics']['p50']
                 mean_deg = res['results'][0]['output']['statistics']['mean']
@@ -4046,6 +4052,7 @@ def callDD (self, td, vlabels, elabels, local_ns):
             edge_str = ", ".join([f'"{e}"' for e in elabels])
             query_parts.append(f'edgeLabels: [{edge_str}]')
 
+        # Construct the query
         line = "CALL neptune.algo.degreeDistribution({" + ", ".join(query_parts) + "}) YIELD output RETURN output"
 
         # oc_rebuild_args = (f"{f'--store-to js --silent'}")
@@ -4064,25 +4071,27 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
             marker_size = 50
             alpha = 0.6
             plt.clf()
-            
-            # Use the provided unique_degrees and counts
+                        
             # Get zero degree count
             zero_idx = np.where(unique_degrees == 0)[0]
             zero_degree_count = counts[zero_idx[0]] if len(zero_idx) > 0 else 0
 
+            # Get non-zero degrees and counts
             mask = unique_degrees > 0
             filtered_degrees = unique_degrees[mask]
             filtered_counts = counts[mask]
 
-            # Handle case when all nodes have zero degree
+            # Obtain the minimum non-zero degree, unless it's all zero degrees
             if len(filtered_degrees) == 0:
                 min_deg = 0
             else:
                 min_deg = np.min(filtered_degrees)            
 
             n_bins = 1
-            if len(filtered_degrees) > 0:  # Only create histogram if there are non-zero degree nodes
+            # Create histogram only if there are non-zero degree nodes
+            if len(filtered_degrees) > 0:
                 if bin_type != 'Raw':
+                    # Arrange the bins for a given bin_width
                     if bin_type == 'Linear':
                         n_bins = max(1, int((max_deg - min_deg) / bin_width))
                         bins = np.linspace(min_deg, max_deg, n_bins + 1)
@@ -4099,9 +4108,9 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
                 else:
                     # For raw data, create bars at each unique degree
                     plt.bar(filtered_degrees, filtered_counts, alpha=alpha,
-                        label='Raw', color='#000080')
+                        label='Raw', color='#000000')
 
-            # Plot degree 0 separately
+            # Plot zero degree node count separately
             if zero_degree_count > 0:
                 plt.bar(0, zero_degree_count, color='red', 
                     label='Isolated', alpha=alpha, width=0.2)
@@ -4121,7 +4130,7 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
 
             plt.gca().set_ylim(top=y_max)
 
-            # Add vertical dashed lines for min and max degree if enabled
+            # Add vertical dashed lines for min and max degree, if enabled
             if show_mindeg and min_deg > 0:
                 plt.axvline(x=min_deg, color='darkgreen', linestyle='--', linewidth=2, label=f'Min non-zero degree: {min_deg}')
 
@@ -4155,19 +4164,22 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
 
         max_count = np.max(counts)
 
-        # Create widgets (same as before)
+        # Scale widget, four options
         scale_widget = widgets.Dropdown(
             options=['Linear-Linear', 'Log-Log', 'Log(x)-Linear(y)', 'Linear(x)-Log(y)'],
             value='Linear-Linear',
             description='Scale:'
         )
 
+        # Binning widget, three options
         bin_widget = widgets.Dropdown(
             options=['Raw', 'Linear', 'Logarithmic'],
             value='Linear',
             description='Binning:'
         )
 
+        # Bin width widget, integer options in [1, 1+(max_deg/2)] interval 
+        # TODO: if logarithmic binning, a much smaller range makes more sense 
         bin_width_widget = widgets.IntSlider(
             value=1,
             min=1,
@@ -4178,28 +4190,27 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
                     'For log binning: multiplicative factor')
         )
 
+        # Upper limit for y-axis range, enables zooming (lower limit is always zero)
         y_max_widget = widgets.IntSlider(
-            value=max_count,
+            value=max_count * 1.1,
             min=1,
             max=max_count * 1.1,
             step=1,
             description='y-max:',
         )
 
-        # Add x-axis range slider
-        x_range_widget = widgets.FloatRangeSlider(
-            value=[min_deg, (max_deg * 1.1) + 5],
+        # Range slider for x-axis, enables zooming
+        x_range_widget = widgets.FloatRangeSlider(            
             min=0,
             max=max_deg * 1.1 + 5,
+            value=[min, max],
             step=1,
             description='x-axis range:',
             disabled=False,
             continuous_update=True,
             readout=True,
             readout_format='.0f',
         )
-        # Create output widget for statistics
-        stats_output = widgets.Output()
 
         # Toggle switches for min/max degree lines
         show_mindeg_widget = widgets.Checkbox(
@@ -4214,7 +4225,10 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
             disabled=False
         )
 
-        # Create the interactive plot
+        # Output widget for statistics
+        stats_output = widgets.Output()
+
+        # Interactive plot
         interactive_plot = widgets.interactive(
             update_plot,
             scale_type=scale_widget,
@@ -4226,7 +4240,7 @@ def update_plot(scale_type, bin_type, bin_width, y_max, x_range, show_mindeg, sh
             show_maxdeg=show_maxdeg_widget
         )
 
-        # Create a vertical box layout
+        # Vertical box layout
         vbox = widgets.VBox([interactive_plot, stats_output])
 
         # Display the interactive plot and stats