ndtools Package

The ndtools package provides utilities for loading, processing, and analysing network datasets. It consists of several modules, each serving a specific purpose in the network analysis workflow.

Package Overview

import ndtools
print(ndtools.__version__)  # 0.1.0

The package is organised into the following modules:

ndtools.io - Data loading and I/O utilities
ndtools.graphs - Graph construction and visualization
ndtools.fun_binary_graph - Evaluation of systems with binary-state components

IO Module

The io module provides functions for loading datasets and handling file I/O operations.

ndtools.io.load_json(path: Path) → Dict[str, Any][source]

ndtools.io.load_yaml(path: Path) → Any[source]

ndtools.io.dataset_paths(repo_root: Path, dataset: str, version: str = 'v1') → Tuple[Path, Path, Path][source]

Return (nodes.json, edges.json, probs.json) for a given dataset folder. Works with your existing layout:

repo_root/<dataset>/<version>/data/{nodes,edges,probs}.json

Example

dataset_paths(Path(‘.’), ‘toynet-11edges’, ‘v1’)

Key Functions

load_json(path): Load a JSON file and return its contents as a Python dictionary.
load_yaml(path): Load a YAML file and return its contents.
dataset_paths(repo_root, dataset, version): Get the file paths for a specific dataset’s nodes, edges, and probabilities files.

Example Usage

from ndtools.io import dataset_paths, load_json
from pathlib import Path

# Get dataset file paths
nodes_path, edges_path, probs_path = dataset_paths(
    Path('.'), 'toynet-11edges', 'v1'
)

# Load the data
nodes = load_json(nodes_path)
edges = load_json(edges_path)
probs = load_json(probs_path)

Graphs Module

The graphs module provides functions for constructing NetworkX graphs and visualizing networks.

ndtools.graphs.build_graph(nodes: Dict[str, Dict[str, Any]], edges: Dict[str, Dict[str, Any]], probs: Dict[str, Any] | None = None) → Graph[source]

ndtools.graphs.draw_graph_from_data(data_dir: str | Path, *, layout: str = 'spring', node_color: str = 'skyblue', node_size: int = 500, edge_color: str = 'gray', with_node_labels: bool = True, with_edge_labels: bool = False, title: str | None = None, layout_kwargs: Dict[str, Any] | None = None, output_name: str = 'graph.png') → Path[source]

Load nodes/edges from JSON files in data_dir, draw the graph, and save to the same dir.

Expects (preferred, current repo format):

nodes.json : {“n0”: {“x”: null, “y”: null, …}, …}
edges.json[{“id”: “e0”,”from”:”n0”,”to”:”n1”,…}, …]
or {“e0”:{“from”:”n0”,”to”:”n1”,…}, …}

Auto-chooses a layout if x/y are missing or null on any node.

ndtools.graphs.compute_edge_lengths(nodes_dict, edges_dict)[source]

Compute Euclidean length in km for each edge.: nodes_dict: {node_id: {“x”: float(km), “y”: float(km)}} edges_dict: {edge_id: {“from”: str, “to”: str, “directed”: bool}}

Returns:: float}
Return type:: {edge_id

Key Functions

build_graph(nodes, edges, probs): Construct a NetworkX graph from node, edge, and probability data.
draw_graph_from_data(data_dir, ...): Load data from files and create a visualization of the network.
compute_edge_lengths(nodes_dict, edges_dict): Calculate Euclidean distances for edges based on node coordinates.

Example Usage

from ndtools.graphs import build_graph, draw_graph_from_data
from ndtools.io import dataset_paths, load_json
from pathlib import Path

# Load data
nodes_path, edges_path, probs_path = dataset_paths(Path('.'), 'toynet-11edges', 'v1')
nodes = load_json(nodes_path)
edges = load_json(edges_path)
probs = load_json(probs_path)

# Build graph
G = build_graph(nodes, edges, probs)

# Visualize
output_path = draw_graph_from_data(
    "toynet-11edges/v1/data",
    layout="spring",
    with_node_labels=True,
    title="Toy Network"
)

Binary Graph Functions Module

The fun_binary_graph module provides functions for evaluating performance of system events, given binary states of components.

ndtools.fun_binary_graph.eval_global_conn_k(comps_state: Dict[str, int], G_base: Graph) → Tuple[int, str, None][source]

Build subgraph H from G_base according to component states:

If comps_state[node_id] == 0: remove all edges incident to that node.
Only include edges whose comps_state[eid] == 1.
Nodes remain present; connectivity is determined by remaining edges.

Returns:: (k_value, k_value, None)

ndtools.fun_binary_graph.eval_travel_time_to_nearest(comps_state: Dict[str, int], G_base: Graph, origin: str, destinations: Iterable[str], *, avg_speed: float = 60.0, target_max: float = 0.5, length_attr: str = 'length') → Tuple[float | None, str, Dict[str, Any]][source]

Key Functions

eval_global_conn_k(comps_state, G_base): Evaluate global vertex connectivity of a network under component failures.
eval_travel_time_to_nearest(comps_state, G_base, origin, destinations, ...): Evaluate travel time to the nearest destination under component failures.

Example Usage

from ndtools.fun_binary_graph import eval_global_conn_k
from ndtools.graphs import build_graph
from ndtools.io import dataset_paths, load_json
from pathlib import Path

# Load and build graph
nodes_path, edges_path, probs_path = dataset_paths(Path('.'), 'toynet-11edges', 'v1')
nodes = load_json(nodes_path)
edges = load_json(edges_path)
probs = load_json(probs_path)
G = build_graph(nodes, edges, probs)

# Define component states (1 = working, 0 = failed)
comps_state = {
    "n1": 1,  # Node n1 is working
    "n2": 1,  # Node n2 is working
    "e1": 0,  # Edge e1 has failed
    "e2": 1,  # Edge e2 is working
}

# Evaluate connectivity
k_value, status, _ = eval_global_conn_k(comps_state, G)
print(f"Connectivity: {k_value}, Status: {status}")

Dependencies

The ndtools package requires the following dependencies:

networkx (>=3.0): Graph analysis and manipulation
pyyaml (>=6.0): YAML file parsing
jsonschema (>=4.0): JSON schema validation

Optional dependencies:

matplotlib (>=3.0): For graph visualization functions

Installation

Install the package and its dependencies:

pip install -e .

Or install with optional visualization dependencies:

pip install -e ".[viz]"

Testing

Run the test suite to verify functionality:

pytest tests/

The test suite includes:

Unit tests for all major functions
Integration tests for complete workflows
Data validation tests

Performance Notes

Graph construction is optimized for large networks
Visualisation functions use efficient layout algorithms
System function evaluation supports both directed and undirected graphs
Memory usage scales linearly with network size