Result

Result is the immutable snapshot returned by infomap.run() and Infomap.run(). Scalar metrics are properties; node and tree collections are methods with defaults (modules(depth=1), nodes(), to_dataframe()).

class infomap.Result(engine: Infomap, *, generation: int)

Immutable snapshot of an Infomap run.

Returned by Infomap.run() (and the functional infomap.run()) and used to back the legacy on-instance accessors. Holds eager O(1) scalars; tree-derived metrics (the effective_num_* modules) and node/tree/dataframe data are materialized lazily and guarded against the engine being re-run.

Read scalars as properties and collections as methods (with defaults):

Examples

Run Infomap and read the partition off the Result:

>>> from infomap import Infomap
>>> im = Infomap(silent=True)
>>> im.add_links(((1, 2), (1, 3), (2, 3), (4, 5), (4, 6), (5, 6), (3, 4)))
>>> result = im.run()
>>> result.num_top_modules
2
>>> for node_id, module_id in sorted(result.modules().items()):
...     print(node_id, module_id)
1 1
2 1
3 1
4 2
5 2
6 2

Per-node views via nodes() (a physical-node default; pass states=True for state nodes):

>>> for node in sorted(result.nodes(), key=lambda n: n.node_id):
...     print(node.node_id, node.module_id, f"{node.flow:.4f}")
1 1 0.1429
2 1 0.1429
3 1 0.2143
4 2 0.2143
5 2 0.1429
6 2 0.1429

A Result is a snapshot, not a live handle: re-running the same Infomap rebuilds the C++ result tree, so node-level access on the old Result raises. Eager scalars (codelength, num_top_modules, …) stay valid.

effective_num_modules(depth: int = 1) → float

The flow-weighted effective number of modules at depth.

Measured as the perplexity of the module flow distribution. Equivalent to the legacy Infomap.get_effective_num_modules(depth).

Parameters:

depth (int, optional) – The module level. 1 (default) is the top (coarsest) level; -1 the bottom (leaf-module) level.

leaf_modules()

A view of the leaf modules (bottom modules containing leaf nodes), depth first from the root.

Equivalent to the legacy Infomap.leaf_modules iterator.

Returns:

Yields each leaf module (the live InfomapLeafModuleIterator positions). The iterator is generation-guarded: consuming it after the bound engine re-runs raises instead of walking a rebuilt tree.

Return type:

generator

links(data: str = 'weight')

A view of the partitioned links and their weights or flow.

Equivalent to the legacy Infomap.get_links(data). The sources and targets are state ids for a state or multilayer network.

Parameters:

data (str, optional) – The kind of value to return, one of "weight" or "flow". Default "weight".

Returns:

(source, target, weight_or_flow) tuples. The generator is generation-guarded like tree(): consuming it after the bound engine re-runs raises instead of reading the rebuilt engine.

Return type:

generator of (int, int, float)

modules(depth: int = 1, *, states: bool = False) → dict

Map node_id (or state_id when states) to module_id.

Equivalent to the legacy Infomap.get_modules(depth, states): for a higher-order (multilayer/memory) network, requesting physical-node modules without states is ambiguous and raises, mirroring the C++ getModules guard.

multilevel_modules(*, states: bool = False) → dict

Map node_id (or state_id when states) to a tuple of module_id, one per level from the top down.

Equivalent to the legacy Infomap.get_multilevel_modules(states).

nodes(depth: int = 1, *, states: bool = False)

Iterate leaf TreeNode views, depth first from the root.

to_dataframe(columns: Sequence[str] | None = None, *, states: bool = False, level: int = 1, index: str | bool | None = None, sort: bool | str | Sequence[str] = False, depth_level: int | None = None) → Any

A pandas DataFrame of the leaf nodes.

Byte-identical to the legacy Infomap.to_dataframe. Default columns ("node_id", "module_id", "flow", "path", "name"); "community" is an alias for "module_id"; "name" is resolved via the physical node name map (falling back to the integer node_id). The opt-in "state_name" column resolves the per-state-node name for a higher-order network (falling back to the physical name, then node_id); see state_names.

tree(depth: int = 1, *, states: bool = False)

A view of the hierarchical tree, iterating over the modules as well as the leaf nodes, depth first from the root.

Equivalent to the legacy Infomap.get_tree(depth, states). For a higher-order (multilayer/memory) network the physical tree is used unless states is requested, mirroring the legacy semantics.

Parameters:

• depth (int, optional) – The module level reported by iterator.module_id. 1 (default) is the top (coarsest) level; -1 the bottom (finest).

• states (bool, optional) – Iterate over state nodes when True, physical nodes when False (the default).

Returns:

Yields each node in the tree (the live InfomapIterator / InfomapIteratorPhysical positions), depth first from the root. The iterator is generation-guarded: consuming it after the bound engine re-runs raises instead of walking a rebuilt C++ tree.

Return type:

generator

property codelength: float

The total (hierarchical) codelength.

property codelengths: tuple

The total (hierarchical) codelength for each trial.

property effective_num_leaf_modules: float

The flow-weighted effective number of leaf modules.

Measured as the perplexity of the leaf-module flow distribution. Computed lazily on first access (see effective_num_modules()).

property effective_num_top_modules: float

The flow-weighted effective number of top modules.

Measured as the perplexity of the top-module flow distribution. Computed lazily on first access (see effective_num_modules()).

property elapsed_time: float

The elapsed run time in seconds.

property entropy_rate: float

The entropy rate of the network.

property have_memory: bool

True for multilayer and memory networks.

property index_codelength: float

The two-level index codelength.

property max_depth: int

Alias of num_levels.

property meta_codelength: float

The meta codelength (meta entropy times meta data rate).

property meta_entropy: float

The meta entropy (unweighted by the meta data rate).

property module_codelength: float

The total codelength of the modules.

property names: dict

All node names, as {node_id: name}.

property num_leaf_modules: int

The number of leaf modules (bottom modules containing leaf nodes).

property num_levels: int

The max depth of the hierarchical tree.

property num_links: int

The number of links.

property num_nodes: int

The number of (state) nodes.

property num_non_trivial_top_modules: int

The number of non-trivial top modules (size not 1 or all).

property num_top_modules: int

The number of top modules in the tree.

property one_level_codelength: float

The one-level codelength.

property relative_codelength_savings: float

The relative codelength savings 1 - L / L_1.

property state_names: dict

All state-node names, as {state_id: name}.

Populated for higher-order (state/memory) networks whose *States section names the state nodes; empty otherwise. Physical node names are available separately via names.

TreeNode is the lightweight, immutable per-node view yielded by Result.nodes().

class infomap.TreeNode(*, node_id: int, state_id: int, module_id: int, flow: float, depth: int, layer_id: int, child_index: int, modular_centrality: float, path: tuple, name: Any, state_name: Any)

A lightweight, immutable view over a single leaf node of a Result.

Yielded by Result.nodes(). A plain Python object: attribute access reads from the snapshot data the Result already materialized, without touching the underlying C++ engine, so it stays valid after a re-run.

node_id

The physical node id.

Type:

int

state_id

The state node id. Equals node_id for first-order networks.

Type:

int

module_id

The module id at the depth level the nodes were requested for.

Type:

int

flow

The node flow (the fraction of flow the node receives).

Type:

float

depth

The depth of the node in the tree (number of levels below the root; equals len(path)).

Type:

int

layer_id

The layer id for multilayer networks, otherwise 0.

Type:

int

child_index

The zero-based index of the node among its parent module’s children.

Type:

int

modular_centrality

A flow-based centrality score of the node within its parent module.

Type:

float

path

The tree path from the root as a tuple of one-based child indices (the colon-separated path in tree output files).

Type:

tuple of int

name

The physical node name, or node_id if the node is unnamed.

Type:

str or int

state_name

The state-node name for higher-order networks, falling back to name when no state name is set.

Type:

str or int