API Reference

This page provides detailed API documentation for all functions and classes in the ndtools package.

IO Module

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

ndtools.io.load_yaml(path: Path) → Any

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

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’)

Graphs Module

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

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

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)

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

Binary Graph Functions Module

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

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]]

Function Details

Data Loading Functions

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

ndtools.io.load_yaml(path: Path) → Any

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

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’)

Graph Construction Functions

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

ndtools.graphs.compute_edge_lengths(nodes_dict, edges_dict)

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

Visualization Functions

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

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.

System Function Evaluation

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

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]]

Helper Functions

ndtools.fun_binary_graph._pairwise(seq: List[str])

ndtools.fun_binary_graph._edge_ids_on_path(G: Graph, node_path: List[str] | None) → List[Any | None] | None

Return [eid1, eid2, …] along the node_path; None if no path or eid missing.

ndtools.fun_binary_graph._node_edge_chain(G: Graph, node_path: List[str] | None) → List[Any] | None

[‘n1’,’n3’,’n6’] -> [‘n1’, eid(n1,n3), ‘n3’, eid(n3,n6), ‘n6’] (uses ‘eid’, falls back to ‘u->v’).

Data Types

The package uses several common data types:

ndtools.typing.Dict[str, Any]

Dictionary mapping string keys to any values, commonly used for node and edge attributes.

ndtools.typing.Tuple[Path, Path, Path]

Tuple of three Path objects representing nodes, edges, and probabilities file paths.

ndtools.typing.Optional[Dict, str, Any]

Optional dictionary, commonly used for probability data which may be None.

Error Handling

The package defines several custom exceptions:

exception ndtools.exceptions.ValidationError

Raised when data validation fails against JSON schemas.

exception ndtools.exceptions.FileNotFoundError

Raised when required dataset files are not found.

exception ndtools.exceptions.GraphConstructionError

Raised when graph construction fails due to invalid data.

Configuration

The package can be configured through environment variables:

NDTOOLS_CACHE_DIR

Directory for caching loaded datasets (default: ~/.ndtools/cache).

NDTOOLS_LOG_LEVEL

Logging level for the package (default: INFO).

NDTOOLS_MAX_WORKERS

Maximum number of worker processes for parallel operations (default: 4).

Examples

Basic Usage

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

# Load a dataset
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)

Advanced Usage

from ndtools.fun_binary_graph import eval_global_conn_k
from ndtools.graphs import draw_graph_from_data
import networkx as nx

# Evaluate system performance
comps_state = {"e1": 1, "e2": 0, "n1": 1}
k_val, status, _ = eval_global_conn_k(comps_state, G, target_k=2)

# Visualize with custom layout
draw_graph_from_data(
    "dataset/v1/data",
    layout="kamada_kawai",
    layout_kwargs={"weight": "length"},
    with_edge_labels=True
)

Performance Tips

• Use dataset_paths() to get file paths instead of hardcoding them

• Load data once and reuse the graph object for multiple analyses

• Use appropriate layout algorithms for visualization (spring for small graphs, kamada_kawai for larger ones)

• Enable parallel processing for system function evaluation on large networks