Refactor notebook analysis components

Author: networmix

dev/generate_api_docs.py

@@ -61,9 +61,10 @@ def module_sort_key(module_name):
         elif len(parts) == 3 and parts[1] == "workflow":  # ngraph.workflow.xxx
             return (3, parts[2])
 
-        # Then transform modules
-        elif len(parts) == 3 and parts[1] == "transform":  # ngraph.transform.xxx
-            return (4, parts[2])
+        # Then transform modules (under workflow)
+        elif len(parts) == 4 and parts[1:3] == ["workflow", "transform"]:
+            # ngraph.workflow.transform.xxx
+            return (4, parts[3])
 
         # Everything else at the end
         else:

docs/reference/api-full.md

@@ -10,9 +10,9 @@ For a curated, example-driven API guide, see **[api.md](api.md)**.
 > - **[CLI Reference](cli.md)** - Command-line interface
 > - **[DSL Reference](dsl.md)** - YAML syntax guide
 
-**Generated from source code on:** June 19, 2025 at 00:16 UTC
+**Generated from source code on:** June 19, 2025 at 02:05 UTC
 
-**Modules auto-discovered:** 42
+**Modules auto-discovered:** 47
 
 ---
 
@@ -2077,47 +2077,78 @@ Attributes:
 
 ---
 
-## ngraph.workflow.notebook_analysis
+## ngraph.workflow.notebook_export
+
+Jupyter notebook export and generation functionality.
+
+### NotebookExport
+
+Export scenario results to a Jupyter notebook with external JSON data file.
+
+Creates a Jupyter notebook containing analysis code and visualizations,
+with results data stored in a separate JSON file. This separation improves
+performance and maintainability for large datasets.
+
+YAML Configuration:
+    ```yaml
+    workflow:
+      - step_type: NotebookExport
+        name: "export_analysis"              # Optional: Custom name for this step
+        notebook_path: "analysis.ipynb"      # Optional: Notebook output path (default: "results.ipynb")
+        json_path: "results.json"            # Optional: JSON data output path (default: "results.json")
+        allow_empty_results: false           # Optional: Allow notebook creation with no results
+    ```
+
+Attributes:
+    notebook_path: Destination notebook file path (default: "results.ipynb").
+    json_path: Destination JSON data file path (default: "results.json").
+    allow_empty_results: Whether to create a notebook when no results exist (default: False).
+                       If False, raises ValueError when results are empty.
+
+**Attributes:**
+
+- `name` (str)
+- `notebook_path` (str) = results.ipynb
+- `json_path` (str) = results.json
+- `allow_empty_results` (bool) = False
+
+**Methods:**
 
-Notebook analysis components for NetGraph workflow results.
+- `execute(self, scenario: "'Scenario'") -> 'None'`
+  - Execute the workflow step with automatic logging.
+- `run(self, scenario: "'Scenario'") -> 'None'`
+  - Create notebook and JSON files with the current scenario results.
+
+---
+
+## ngraph.workflow.notebook_serializer
 
-This module provides specialized analyzers for processing and visualizing network analysis
-results in Jupyter notebooks. Each component handles specific data types and provides
-both programmatic analysis and interactive display capabilities.
+Code serialization for notebook generation.
 
-Core Components:
-    NotebookAnalyzer: Abstract base class defining the analysis interface. All analyzers
-        implement analyze() for data processing and display_analysis() for notebook output.
-        Provides analyze_and_display() convenience method that chains analysis and display.
+### NotebookCodeSerializer
 
-    AnalysisContext: Immutable dataclass containing execution context (step name, results,
-        config) passed between analysis components for state management.
+Converts Python classes into notebook cells.
 
-Utility Components:
-    PackageManager: Handles runtime dependency verification and installation. Checks
-        for required packages (itables, matplotlib) using importlib, installs missing
-        packages via subprocess, and configures visualization environments (seaborn
-        styling, itables display options, matplotlib backends).
+**Methods:**
 
-    DataLoader: Provides robust JSON file loading with comprehensive error handling.
-        Validates file existence, JSON format correctness, and expected data structure.
-        Returns detailed status information including step counts and validation results.
+- `create_capacity_analysis_cell() -> nbformat.notebooknode.NotebookNode`
+  - Create capacity analysis cell.
+- `create_data_loading_cell(json_path: str) -> nbformat.notebooknode.NotebookNode`
+  - Create data loading cell.
+- `create_flow_analysis_cell() -> nbformat.notebooknode.NotebookNode`
+  - Create flow analysis cell.
+- `create_flow_availability_cells() -> List[nbformat.notebooknode.NotebookNode]`
+  - Create flow availability analysis cells (markdown header + code).
+- `create_setup_cell() -> nbformat.notebooknode.NotebookNode`
+  - Create setup cell.
+- `create_summary_cell() -> nbformat.notebooknode.NotebookNode`
+  - Create analysis summary cell.
 
-Data Analyzers:
-    CapacityMatrixAnalyzer: Processes capacity envelope data from network flow analysis.
-        Extracts flow path information (source->destination, bidirectional), parses
-        capacity values from various data structures, creates pivot tables for matrix
-        visualization, and calculates flow density statistics. Handles self-loop exclusion
-        and zero-flow inclusion for accurate network topology representation.
+---
 
-    FlowAnalyzer: Processes maximum flow calculation results. Extracts flow paths and
-        values from workflow step data, computes flow statistics (min/max/avg/total),
-        and generates comparative visualizations across multiple analysis steps using
-        matplotlib bar charts.
+## ngraph.workflow.analysis.base
 
-    SummaryAnalyzer: Aggregates results across all workflow steps. Categorizes steps
-        by analysis type (capacity envelopes, flow calculations, other), provides
-        high-level metrics for workflow completion status and data distribution.
+Base classes for notebook analysis components.
 
 ### AnalysisContext
 
@@ -2129,27 +2160,57 @@ Context information for analysis execution.
 - `results` (Dict)
 - `config` (Dict)
 
-### CapacityMatrixAnalyzer
+### NotebookAnalyzer
 
-Analyzes capacity envelope data and creates matrices.
+Base class for notebook analysis components.
 
 **Methods:**
 
 - `analyze(self, results: Dict[str, Any], **kwargs) -> Dict[str, Any]`
-  - Analyze capacity envelopes and create matrix visualization.
+  - Perform the analysis and return results.
 - `analyze_and_display(self, results: Dict[str, Any], **kwargs) -> None`
   - Analyze results and display them in notebook format.
-- `analyze_and_display_all_steps(self, results: Dict[str, Any]) -> None`
-  - Analyze and display capacity matrices for all relevant steps.
-- `analyze_and_display_flow_availability(self, results: Dict[str, Any], step_name: str) -> None`
-  - Analyze and display flow availability distribution with CDF visualization.
-- `analyze_flow_availability(self, results: Dict[str, Any], **kwargs) -> Dict[str, Any]`
-  - Analyze total flow samples to create flow availability distribution (CDF).
 - `display_analysis(self, analysis: Dict[str, Any], **kwargs) -> None`
-  - Display capacity matrix analysis results.
+  - Display analysis results in notebook format.
 - `get_description(self) -> str`
   - Get a description of what this analyzer does.
 
+---
+
+## ngraph.workflow.analysis.capacity_matrix
+
+Capacity envelope analysis utilities.
+
+This module contains `CapacityMatrixAnalyzer`, responsible for processing capacity
+envelope results, computing comprehensive statistics, and generating notebook-friendly
+visualizations.
+
+### CapacityMatrixAnalyzer
+
+Analyzes capacity envelope data and creates matrices.
+
+**Methods:**
+
+- `analyze(self, results: 'Dict[str, Any]', **kwargs) -> 'Dict[str, Any]'`
+  - Analyze capacity envelopes and create matrix visualisation.
+- `analyze_and_display(self, results: Dict[str, Any], **kwargs) -> None`
+  - Analyze results and display them in notebook format.
+- `analyze_and_display_all_steps(self, results: 'Dict[str, Any]') -> 'None'`
+  - Run analyse/display on every step containing *capacity_envelopes*.
+- `analyze_and_display_flow_availability(self, results: 'Dict[str, Any]', step_name: 'str') -> 'None'`
+- `analyze_flow_availability(self, results: 'Dict[str, Any]', **kwargs) -> 'Dict[str, Any]'`
+  - Create CDF/availability distribution for *total_capacity_samples*.
+- `display_analysis(self, analysis: 'Dict[str, Any]', **kwargs) -> 'None'`
+  - Pretty-print *analysis* to the notebook/stdout.
+- `get_description(self) -> 'str'`
+  - Get a description of what this analyzer does.
+
+---
+
+## ngraph.workflow.analysis.data_loader
+
+Data loading utilities for notebook analysis.
+
 ### DataLoader
 
 Handles loading and validation of analysis results.
@@ -2159,6 +2220,12 @@ Handles loading and validation of analysis results.
 - `load_results(json_path: Union[str, pathlib._local.Path]) -> Dict[str, Any]`
   - Load results from JSON file with comprehensive error handling.
 
+---
+
+## ngraph.workflow.analysis.flow_analyzer
+
+Flow analysis for notebook results.
+
 ### FlowAnalyzer
 
 Analyzes maximum flow results.
@@ -2176,20 +2243,11 @@ Analyzes maximum flow results.
 - `get_description(self) -> str`
   - Get a description of what this analyzer does.
 
-### NotebookAnalyzer
+---
 
-Base class for notebook analysis components.
+## ngraph.workflow.analysis.package_manager
 
-**Methods:**
-
-- `analyze(self, results: Dict[str, Any], **kwargs) -> Dict[str, Any]`
-  - Perform the analysis and return results.
-- `analyze_and_display(self, results: Dict[str, Any], **kwargs) -> None`
-  - Analyze results and display them in notebook format.
-- `display_analysis(self, analysis: Dict[str, Any], **kwargs) -> None`
-  - Display analysis results in notebook format.
-- `get_description(self) -> str`
-  - Get a description of what this analyzer does.
+Package management for notebook analysis components.
 
 ### PackageManager
 
@@ -2202,6 +2260,12 @@ Manages package installation and imports for notebooks.
 - `setup_environment() -> Dict[str, Any]`
   - Set up the complete notebook environment.
 
+---
+
+## ngraph.workflow.analysis.summary
+
+Summary analysis for notebook results.
+
 ### SummaryAnalyzer
 
 Provides summary analysis of all results.
@@ -2221,76 +2285,7 @@ Provides summary analysis of all results.
 
 ---
 
-## ngraph.workflow.notebook_export
-
-Jupyter notebook export and generation functionality.
-
-### NotebookExport
-
-Export scenario results to a Jupyter notebook with external JSON data file.
-
-Creates a Jupyter notebook containing analysis code and visualizations,
-with results data stored in a separate JSON file. This separation improves
-performance and maintainability for large datasets.
-
-YAML Configuration:
-    ```yaml
-    workflow:
-      - step_type: NotebookExport
-        name: "export_analysis"              # Optional: Custom name for this step
-        notebook_path: "analysis.ipynb"      # Optional: Notebook output path (default: "results.ipynb")
-        json_path: "results.json"            # Optional: JSON data output path (default: "results.json")
-        allow_empty_results: false           # Optional: Allow notebook creation with no results
-    ```
-
-Attributes:
-    notebook_path: Destination notebook file path (default: "results.ipynb").
-    json_path: Destination JSON data file path (default: "results.json").
-    allow_empty_results: Whether to create a notebook when no results exist (default: False).
-                       If False, raises ValueError when results are empty.
-
-**Attributes:**
-
-- `name` (str)
-- `notebook_path` (str) = results.ipynb
-- `json_path` (str) = results.json
-- `allow_empty_results` (bool) = False
-
-**Methods:**
-
-- `execute(self, scenario: "'Scenario'") -> 'None'`
-  - Execute the workflow step with automatic logging.
-- `run(self, scenario: "'Scenario'") -> 'None'`
-  - Create notebook and JSON files with the current scenario results.
-
----
-
-## ngraph.workflow.notebook_serializer
-
-Code serialization for notebook generation.
-
-### NotebookCodeSerializer
-
-Converts Python classes into notebook cells.
-
-**Methods:**
-
-- `create_capacity_analysis_cell() -> nbformat.notebooknode.NotebookNode`
-  - Create capacity analysis cell.
-- `create_data_loading_cell(json_path: str) -> nbformat.notebooknode.NotebookNode`
-  - Create data loading cell.
-- `create_flow_analysis_cell() -> nbformat.notebooknode.NotebookNode`
-  - Create flow analysis cell.
-- `create_flow_availability_cells() -> List[nbformat.notebooknode.NotebookNode]`
-  - Create flow availability analysis cells (markdown header + code).
-- `create_setup_cell() -> nbformat.notebooknode.NotebookNode`
-  - Create setup cell.
-- `create_summary_cell() -> nbformat.notebooknode.NotebookNode`
-  - Create analysis summary cell.
-
----
-
-## ngraph.transform.base
+## ngraph.workflow.transform.base
 
 Base classes for network transformations.
 
@@ -2317,7 +2312,7 @@ Attributes:
 
 **Methods:**
 
-- `apply(self, scenario: 'Scenario') -> 'None'`
+- `apply(self, scenario: "'Scenario'") -> 'None'`
   - Modify *scenario.network* in-place.
 - `create(step_type: 'str', **kwargs: 'Any') -> 'Self'`
   - Instantiate a registered transform by *step_type*.
@@ -2335,7 +2330,7 @@ Raises:
 
 ---
 
-## ngraph.transform.distribute_external
+## ngraph.workflow.transform.distribute_external
 
 Network transformation for distributing external connectivity.
 
@@ -2371,14 +2366,14 @@ Args:
 
 **Methods:**
 
-- `apply(self, scenario: ngraph.scenario.Scenario) -> None`
+- `apply(self, scenario: 'Scenario') -> None`
   - Modify *scenario.network* in-place.
 - `create(step_type: 'str', **kwargs: 'Any') -> 'Self'`
   - Instantiate a registered transform by *step_type*.
 
 ---
 
-## ngraph.transform.enable_nodes
+## ngraph.workflow.transform.enable_nodes
 
 Network transformation for enabling/disabling nodes.
 
@@ -2408,7 +2403,7 @@ Args:
 
 **Methods:**
 
-- `apply(self, scenario: 'Scenario') -> 'None'`
+- `apply(self, scenario: "'Scenario'") -> 'None'`
   - Modify *scenario.network* in-place.
 - `create(step_type: 'str', **kwargs: 'Any') -> 'Self'`
   - Instantiate a registered transform by *step_type*.

ngraph/__init__.py

@@ -7,14 +7,13 @@
 
 from __future__ import annotations
 
-from . import cli, config, logging, transform
+from . import cli, config, logging
 from .results_artifacts import CapacityEnvelope, PlacementResultSet, TrafficMatrixSet
 
 __all__ = [
     "cli",
     "config",
     "logging",
-    "transform",
     "CapacityEnvelope",
     "PlacementResultSet",
     "TrafficMatrixSet",