Modularity + 3 visualization themes based on graph size

Author: dalager

Book1.xlsx

@@ -31,7 +31,7 @@ pip install -r requirements.txt
 ## Usage
 
 ```bash
-python graphbuilder.py <path_to_excel_file> [--verbose] [--no-visualize] [--keep-direction]
+python graphbuilder.py <path_to_excel_file> [--verbose] [--no-visualize] [--keep-direction] [--open-image]
 ```
 
 Depending on the size of the spreadsheet you might want to adjust the plot configuration in the code to to make the graph more readable (remove labels, decrease widths and sizes etc)
@@ -44,6 +44,8 @@ Depending on the size of the spreadsheet you might want to adjust the plot confi
 
 `--keep-direction` will keep the direction of the graph as it is in the excel file, otherwise it will be simplified to an undirected graph (slower)
 
+`--open-image` will open the generated image in the default image viewer (only on Windows)
+
 ## Sample output
 
 The following is the output of running the script on the provided `Book1.xlsx` file.

README.md

@@ -0,0 +1,61 @@
+from openpyxl.utils import get_column_letter, range_boundaries
+import re
+
+
+# Regex to detect cell references like A1, B2, or ranges like A1:B2
+CELL_REF_REGEX = r"('?[A-Za-z0-9_\-\[\] ]+'?![A-Z]{1,3}[0-9]+(:[A-Z]{1,3}[0-9]+)?)|([A-Z]{1,3}[0-9]+(:[A-Z]{1,3}[0-9]+)?)"  # noqa
+
+
+def expand_range(range_ref):
+    """
+    Expand a range reference (e.g., 'A1:A3') into a list of individual cell references.
+    """
+
+    # if there is a sheet name in the range reference, put it away for now
+    if "!" in range_ref:
+        sheet_name, range_ref = range_ref.split("!")
+    else:
+        sheet_name = None
+
+    min_col, min_row, max_col, max_row = range_boundaries(range_ref)
+    expanded_cells = []
+
+    # Loop over rows and columns in the range
+    for row in range(min_row, max_row + 1):
+        for col in range(min_col, max_col + 1):
+            # if sheetname is set
+            if sheet_name:
+                expanded_cells.append(f"{sheet_name}!{get_column_letter(col)}{row}")
+            else:
+                expanded_cells.append(f"{get_column_letter(col)}{row}")
+
+    return expanded_cells
+
+
+def extract_references(formula):
+    """
+    Extract all referenced cells and ranges from a formula using regular expressions.
+    This returns a list of both individual cells and range references.
+    """
+    formula = formula.replace("$", "")
+    matches = re.findall(CELL_REF_REGEX, formula)
+    references = [match[0] if match[0] else match[2] for match in matches]
+
+    # trim the extracted references
+    references = [ref.strip() for ref in references]
+
+    expanded_references = []
+    dependencies = {}
+
+    for ref in references:
+        if ":" in ref:  # it's a range like A1:A3
+            expanded_cells = expand_range(ref)
+            expanded_references.extend(expanded_cells)
+
+            # Store the range-to-cells relationship
+            for cell in expanded_cells:
+                dependencies[cell] = ref
+        else:  # single cell
+            expanded_references.append(ref)
+
+    return expanded_references, dependencies

excel_parser.py

@@ -0,0 +1,115 @@
+import matplotlib.cm as cm
+import matplotlib.patches as mpatches
+import networkx as nx
+import matplotlib.pyplot as plt
+import sys
+
+small_graph_settings = {
+    "node_size": 50,
+    "edge_color": "black",
+    "with_labels": True,
+    "font_size": 7,
+    "linewidths": 0.8,
+    "alpha": 0.8,
+    "width": 0.2,
+}
+
+medium_graph_settings = {
+    "node_size": 30,
+    "edge_color": "gray",
+    "with_labels": True,
+    "font_size": 10,
+    "linewidths": 0.1,
+    "alpha": 0.4,
+    "width": 0.2,
+}
+
+large_graph_settings = {
+    "node_size": 5,
+    "edge_color": "gray",
+    "with_labels": False,
+    "font_size": 12,
+    "linewidths": 0.5,
+    "alpha": 0.2,
+    "width": 0.2,
+}
+
+
+def get_graph_default_settings(graph_size):
+    """
+    Set the default settings for the graph visualization based on the number of nodes.
+    """
+
+    if graph_size < 200:
+        settings = small_graph_settings
+        fig_size = 10
+    elif graph_size < 500:
+        settings = medium_graph_settings
+        fig_size = 20
+    else:
+        settings = large_graph_settings
+        fig_size = 20
+
+    return settings, fig_size
+
+
+# Function to get colors and generate legend for sheets
+def get_node_colors_and_legend(graph):
+    sheets = {data.get("sheet", "Sheet1") for _, data in graph.nodes(data=True)}
+    color_map = cm.get_cmap("tab20c", len(sheets))
+
+    # Map sheet names to colors
+    sheet_to_color = {sheet: color_map(i) for i, sheet in enumerate(sheets)}
+
+    # Assign colors to nodes based on their sheet
+    node_colors = [
+        sheet_to_color[data.get("sheet", "Sheet1")]
+        for _, data in graph.nodes(data=True)
+    ]
+
+    # Create patches for the legend
+    legend_patches = [
+        mpatches.Patch(color=color, label=sheet)
+        for sheet, color in sheet_to_color.items()
+    ]
+
+    return node_colors, legend_patches
+
+
+def visualize_dependency_graph(graph, file_path):
+    """
+    Render the dependency graph using matplotlib and networkx.
+    """
+
+    if "--keep-direction" not in sys.argv:
+        # Convert the graph to an undirected graph
+        graph = graph.to_undirected()
+
+    # Set the default settings for the graph visualization based on the number of nodes
+    graph_settings, fig_size = get_graph_default_settings(len(graph.nodes))
+
+    plt.figure(figsize=(fig_size, fig_size))
+    node_colors = [hash(graph.nodes[node]["sheet"]) % 256 for node in graph.nodes]
+    pos = nx.spring_layout(graph)  # layout for nodes
+
+    # add legends for the colors
+    node_colors, legend_patches = get_node_colors_and_legend(graph)
+
+    nx.draw(
+        graph,
+        pos,
+        node_color=node_colors,
+        **graph_settings,
+    )
+
+    plt.legend(handles=legend_patches, title="Sheets", loc="upper left")
+
+    filename = f"images/{file_path}.png"
+    plt.savefig(filename)
+    print(f"Graph visualization saved to {filename}")
+
+    # open the image file in windows
+    if sys.platform == "win32" and "--open-image" in sys.argv:
+        import os
+
+        os.system(f"start {filename}")

graph_visualizer.py

@@ -2,15 +2,13 @@
 This script extracts formulas from an Excel file and builds a dependency graph.
 """
 
-from collections import Counter
-import re
 from openpyxl import load_workbook
+from collections import Counter
 import networkx as nx
-import matplotlib.pyplot as plt
+import re
 import sys
-
-# Regex to detect cell references like A1, B2, or ranges like A1:B2
-CELL_REF_REGEX = r"('?[A-Za-z0-9_\-\[\] ]+'?![A-Z]{1,3}[0-9]+(:[A-Z]{1,3}[0-9]+)?)|([A-Z]{1,3}[0-9]+(:[A-Z]{1,3}[0-9]+)?)"  # noqa
+from graph_visualizer import visualize_dependency_graph
+from excel_parser import extract_references
 
 # dictionary that stores the uniqe functions used in the formulas
 # the key will be the funciton name and the value will be the number of times it was used
@@ -28,10 +26,14 @@ def log(msg):
 
 
 def stat_functions(cellvalue):
+    """
+    Extract the functions used in the formula and store them in a dictionary.
+    This will be used to print the most used functions in the formulas.
+    """
+
     # functions used in the formula
     cellfuncs = re.findall(r"[A-Z]+\(", cellvalue)
     log(f"  Functions used: {functions_dict}")
-    # add the functions to the dictionary
     for function in cellfuncs:
         # remove the "(" from the function name
         function = function[:-1]
@@ -63,28 +65,50 @@ def extract_formulas_and_build_dependencies(file_path):
                 if isinstance(cell.value, str) and cell.value.startswith("="):
                     stat_functions(cell.value)
 
-                    # The formula is found in this cell
                     cell_name = f"{sheet_name}!{cell.coordinate}"
                     log(f"Formula in {cell_name}: {cell.value}")
 
-                    # Extract all referenced cells from the formula
-                    referenced_cells = extract_references(cell.value)
-                    refs = []
+                    graph.add_node(cell_name, sheet=sheet_name)
+
+                    # Extract all referenced cells and ranges from the formula
+                    referenced_cells, range_dependencies = extract_references(
+                        cell.value
+                    )
 
                     # Add the cell and its dependencies to the graph
                     for ref_cell in referenced_cells:
                         if "!" not in ref_cell:
-                            # No sheet specified in the assume current sheet
+                            # No sheet specified, assume current sheet
                             refc = f"{sheet_name}!{ref_cell}"
                         else:
                             refc = ref_cell
 
-                        # Add node to refs if not already in refs
-                        if refc not in refs:
-                            log(f"  Depends on: {refc}")
-                            refs.append(refc)
-                            graph.add_edge(cell_name, refc)
+                        log(f"  Depends on: {refc}")
+                        graph.add_node(refc, sheet=sheet_name)
+                        graph.add_edge(cell_name, refc)
+
+                    # Add dependencies for ranges
+                    for single_cell, range_ref in range_dependencies.items():
+                        if "!" not in range_ref:
+                            range_ref = f"{sheet_name}!{range_ref}"
+                            range_sheet = sheet_name
+                        else:
+                            range_ref = range_ref
+                            range_sheet = range_ref.split("!")[0]
+
+                        if "!" not in single_cell:
+                            single_cell = f"{sheet_name}!{single_cell}"
+                            cell_sheet = sheet_name
+                        else:
+                            single_cell = single_cell
+                            cell_sheet = single_cell.split("!")[0]
+
+                        # this is the single cell that points to the range it belongs to
+                        graph.add_node(f"{single_cell}", sheet=cell_sheet)  # noqa
+                        graph.add_node(f"{range_ref}", sheet=range_sheet)
 
+                        # Then add the edge between the single cell and the range
+                        graph.add_edge(f"{single_cell}", f"{range_ref}")
     return graph
 
 
@@ -127,51 +151,6 @@ def print_summary(graph, functionsdict):
         print(f"{function.ljust(strpadsize, ' ')}{str(count).rjust(numpadsize, ' ')}")
 
 
-def extract_references(formula):
-    """
-    Extract all referenced cells from a formula using regular expressions.
-    This returns a list of cells that are mentioned directly (e.g., A1, B2),
-    but doesn't handle ranges or external sheets' references.
-    """
-    formula = formula.replace("$", "")
-    matches = re.findall(CELL_REF_REGEX, formula)
-    references = [match[0] if match[0] else match[2] for match in matches]
-
-    # trim the extracted references
-    references = [ref.strip() for ref in references]
-
-    return references
-
-
-def visualize_dependency_graph(graph, file_path):
-    """
-    Render the dependency graph using matplotlib and networkx.
-    """
-
-    if "--keep-direction" not in sys.argv:
-        # Convert the graph to an undirected graph
-        graph = graph.to_undirected()
-
-    pos = nx.spring_layout(graph)  # layout for nodes
-    plt.figure(figsize=(10, 10))
-    nx.draw(
-        graph,
-        pos,
-        with_labels=True,
-        node_color="black",
-        edge_color="gray",
-        linewidths=3.5,
-        alpha=0.8,
-        width=1,
-        # font_weight="bold",
-        node_size=20,
-    )
-
-    filename = f"images/{file_path}.png"
-    plt.savefig(filename)
-    print(f"Graph visualization saved to {filename}")
-
-
 if __name__ == "__main__":
     path_to_excel = "Book1.xlsx"