Motifs

Graphlet definitions using Pržulj notation. See Motifs & Notation for background.

Motif class

motif

Motif: A subgraph defined by its adjacency matrix.

All properties (corner types, cardinalities) are derived automatically. Validation ensures the motif has a Hamiltonian cycle for CMA compatibility.

Motif

Bases: BaseModel

A motif (subgraph) defined by its adjacency matrix.

The motif's structural properties are derived automatically from the adjacency matrix. Corner types are assigned based on node degrees within the motif—nodes with identical degrees receive the same corner type.

Attributes:

Name	Type	Description
adjacency	AdjacencyMatrix	Square binary symmetric matrix defining the motif structure. Can be a nested list or numpy array.

Example

triangle = Motif(adjacency=[[0, 1, 1], ... [1, 0, 1], ... [1, 1, 0]]) triangle.num_nodes 3 triangle.corner_types [1, 1, 1] triangle.is_complete True

num_nodes property

num_nodes: int

Number of nodes in the motif.

num_edges property

num_edges: int

Number of edges in the motif.

degrees property

degrees: list[int]

Degree of each node within the motif.

corner_types property

corner_types: list[int]

Corner type for each node (derived from degree).

Nodes with the same degree within the motif receive the same type. Types are numbered starting from 1.

is_complete property

is_complete: bool

True if all nodes have the same degree (all corners equivalent).

cardinalities property

cardinalities: dict[int, int]

Maps corner type to its degree within the motif.

For a triangle, all corners have type 1 with cardinality 2 (each corner connects to 2 other nodes in the triangle).

type_counts property

type_counts: dict[int, int]

Maps corner type to how many nodes have that type.

edges_for

edges_for(
    nodes: NDArray[int_],
) -> tuple[list[int], list[int]]

Extract edges when this motif is instantiated with given nodes.

Maps the motif's abstract structure onto concrete node IDs. For each edge (i, j) in the motif adjacency, produces edge (nodes[i], nodes[j]).

Parameters:

Name	Type	Description	Default
nodes	NDArray[int_]	Array of node IDs, one per motif position. Length must equal num_nodes.	required

Returns:

Type	Description
tuple[list[int], list[int]]	Tuple of (sources, targets) lists for edges in this instance.

Example

triangle = Motif(adjacency=[[0,1,1], [1,0,1], [1,1,0]]) triangle.edges_for(np.array([10, 20, 30])) ([10, 10, 20], [20, 30, 30])

Registry

registry

Pre-defined motifs for network generation using Przulj notation.

These motifs are validated on import to ensure they satisfy the Hamiltonian cycle requirement for CMA compatibility.

Naming convention follows Przulj et al. (2004) graphlet enumeration: - G0-G29: Graphlets on 2-5 nodes - C6: 6-cycle (extension) - K6: Complete graph on 6 nodes (extension)

Reference

Przulj, N., Corneil, D. G., & Jurisica, I. (2004). Modeling interactome: scale-free or geometric? Bioinformatics, 20(18), 3508-3515.

BUILTINS module-attribute

BUILTINS: dict[str, Motif] = {
    "g0": G0,
    "g2": G2,
    "g5": G5,
    "g7": G7,
    "g8": G8,
    "g12": G12,
    "g14": G14,
    "g17": G17,
    "g29": G29,
    "c6": C6,
    "k6": K6,
}

get_motif

get_motif(name: str) -> Motif

Get a built-in motif by name.

Parameters:

Name	Type	Description	Default
name	str	Case-insensitive motif name using Przulj notation (G0, G2, G5, G7, G8, G12, G14, G17, G29, C6, K6).	required

Returns:

Type	Description
Motif	The corresponding Motif object.

Raises:

Type	Description
KeyError	If no motif with that name exists.

Example

triangle = get_motif("G2") triangle.num_nodes 3