Network

Network representation with sparse CSC incidence matrix.

class micropurc.network.NodeIndex(raw_ids, id_to_idx)[source]

Bases: object

Mapping between raw node IDs and internal 0..V-1 indices.

Variables:

  • raw_ids (numpy.ndarray) – Raw node IDs in internal-index order, shape (V,).

  • id_to_idx (dict[Any, int]) – Inverse mapping, raw ID to internal index.

Parameters:
raw_ids: ndarray
id_to_idx: dict[Any, int]
classmethod from_edges(tail_raw, head_raw)[source]

Build an index from every raw node ID appearing in the edges.

Internal indices follow the sorted order of the unique raw IDs.

Parameters:
Return type:

NodeIndex

map_array(arr)[source]

Map an array of raw node IDs to internal indices.

An ID outside the index raises KeyError naming the offending ID.

Parameters:

arr (ndarray)

Return type:

ndarray

class micropurc.network.Network(nodes, edges, Z, A, node_index=None, attribute_names=None)[source]

Bases: object

Directed network with sparse incidence and link attributes.

Variables:

  • nodes (numpy.ndarray) – Internal node indices (0..V-1), shape (V,).

  • edges (numpy.ndarray) – Directed edges in internal indices, shape (L, 2).

  • Z (numpy.ndarray) – Link attribute matrix, shape (L, K).

  • A (scipy.sparse._csc.csc_matrix) – Node-link incidence matrix, sparse CSC, shape (V, L). Convention: A[i, ell] = -1 (tail), A[j, ell] = +1 (head).

  • node_index (micropurc.network.NodeIndex | None) – Mapping between raw node IDs and internal indices, None for a network built without raw IDs.

  • attribute_names (list[str] | None) – Name of each column of Z, length K. Defaults to attr_0, attr_1, ... when not supplied. Model specifications reference attributes by these names.

  • tail – Tail node indices, shape (L,).

  • head – Head node indices, shape (L,).

Parameters:
nodes: ndarray
edges: ndarray
Z: ndarray
A: csc_matrix
node_index: NodeIndex | None = None
attribute_names: list[str] | None = None
attribute_index(name)[source]

Return the column index of Z holding the named attribute.

Parameters:

name (str)

Return type:

int

property tail: ndarray

Tail node of each link.

property head: ndarray

Head node of each link.

Number of links (rows of Z).

property num_nodes: int

Number of nodes (rows of A).

property num_attributes: int

Number of raw link attributes (columns of Z).

classmethod grid(rows, cols, K, **kwargs)[source]

Construct a rows x cols grid network with synthetic attributes.

Every grid neighbour pair contributes two directed links, one per direction.

Parameters:

  • rows (int) – Number of grid rows.

  • cols (int) – Number of grid columns.

  • K (int) – Number of synthetic attribute columns.

  • **kwargs (Any) – Only rng_seed is read, seeding the attribute draw (default 42).

Returns:

The grid network, with node IDs equal to their internal indices.

Raises:

ValueError – If rows or cols is not positive.

Return type:

Network

classmethod from_csv(csv_path, *, tail_col='init_node', head_col='term_node', attribute_cols=None)[source]

Construct a Network from a link CSV file, one row per directed link.

Parameters:

  • csv_path (str) – Path to the link file.

  • tail_col (str) – Column holding the raw tail node ID.

  • head_col (str) – Column holding the raw head node ID.

  • attribute_cols (list[str] | None) – Columns to load into Z. When omitted, every numeric column apart from tail_col and head_col is taken, in file order.

Returns:

The network, with raw node IDs reachable through node_index.

Raises:

ValueError – If a tail, head, or attribute column is absent, or if no attribute column is left to load.

Return type:

Network

classmethod from_dense(A_dense, edges, Z, node_index=None)[source]

Construct a network from a dense node-link incidence matrix.

A_dense is converted to CSC and its row count fixes the node set.

Parameters:
Return type:

Network