The stateful Infomap class¶

How-to

At a glance

The infomap.Infomap class is the stateful entry point: build a network with the add_* verbs, then call run() for an immutable Result. New code should prefer infomap.run() for one-shot use and Network for incremental construction; existing Infomap code keeps working essentially unchanged (see Removed accessors for the few exceptions).

When to use it¶

The functional infomap.run() and the Network builder cover most needs. Reach for the stateful Infomap class when you want to keep one configured object around and run it repeatedly, or when you are maintaining code written against the original API. Internally it composes a Network and an Options over the same engine boundary, so its building verbs and its results are identical to the functional path.

infomap.run() is the canonical entry point. It accepts any input – including a prebuilt Network or a stateful Infomap instance – so net.run(**kw) and im.run(**kw) are thin conveniences equivalent to infomap.run(net, **kw) / infomap.run(im, **kw). All three take the same keywords (the five common-tier options directly, everything else via options=) and return the same Result.

from infomap import Infomap

im = Infomap(seed=123, num_trials=10)
im.add_link(0, 1)
im.add_link(1, 2)
im.add_link(2, 0)

result = im.run()          # returns an immutable Result
print(result.codelength)
print(result.modules())

1.5849625007211494
{0: 1, 1: 1, 2: 1}

im.run() returns the same Result the functional API returns. The on-instance result accessors (im.get_modules(), im.codelength, im.nodes) still work and are backed by that result, but they are deprecated and leave in 3.0 – read the equivalently named members off the returned Result instead. Mind the shape shift: im.modules is a property, while result.modules() is a method. These accessors emit a silent-by-default PendingDeprecationWarning (surface it with -W); the migration table below maps each one across.

Migrating to the functional API¶

Each stateful pattern has a direct functional or Network equivalent:

Task	Stateful `Infomap`	Functional / `Network`
Run a graph	`im = Infomap(**opts); im.add_networkx_graph(g); im.run()`	`result = infomap.run(g, **opts)`
Build incrementally	`im.add_node(...)`, `im.add_link(...)`, then `im.run()`	`net = Network(); net.add_node(...); net.add_link(...)`, then `infomap.run(net)`
Reusable configuration	repeat the keyword arguments	`options = Options(**opts)`, then `infomap.run(g, options=options)`
Top-level modules	`im.get_modules()`	`result.modules()`
Iterate `(node_id, module_id)` pairs	`for k, v in im.modules:`	`for k, v in result.modules().items():`
Modules at level k	`im.get_modules(depth_level=k)`	`result.modules(depth=k)`
State-node modules	`im.get_modules(states=True)`	`result.modules(states=True)`
Per-node flow	`for n in im.nodes: n.data.flow`	`for n in result.nodes(states=True): n.flow` (`im.nodes` iterates state nodes; plain `result.nodes()` gives physical nodes, identical for first-order networks)
DataFrame	`im.to_dataframe([...])`	`result.to_dataframe([...])`
Scalar metrics	`im.codelength`, `im.num_top_modules`	`result.codelength`, `result.num_top_modules`
Graph-file export	`infomap.io.export.write_graphml(graph, im, path)`	`nx.write_graphml(result.to_networkx(), path)`

The two consistent shifts: building a network is a Network (or a direct infomap.run() call) rather than the stateful instance, and reading results goes through the immutable Result (see Reading the result).

Migrating deprecated keyword arguments¶

Advanced engine keywords still work on Infomap() and infomap.run() in 2.x, but they are pending-deprecated and leave those signatures in 3.0: passing one directly emits a (default-silent) PendingDeprecationWarning. Each falls into one of three groups, with a recommended replacement:

Deprecated keyword	Where it moves
Advanced tuning flags – `regularized`, `core_loop_limit`, `flow_model`, and the like	carry them on the `Options` object: `run(g, options=Options(regularized=True))`
Output-artifact flags – `no_file_output`, `tree`, `clu`, `out_name`	write from the `Result` instead: `result.write_tree(path)`, `result.write_clu(path)`, or `network.write_pajek(path)`
Console flags – `silent`, `verbosity_level`	use logging: `infomap.enable_log()` for the engine log, and `infomap.enable_log(logging.DEBUG)` to raise its verbosity

The options carrier accepts an Options instance or a plain mapping and works the same on Infomap(), Infomap.run(), Network.run(), and infomap.run() — for example im.run(options=Options(regularized=True)) gives the stateful builder the same carrier — and a bare keyword set to a non-default value overrides it. The common options (seed, num_trials, two_level, directed, markov_time) stay on every signature and are never deprecated.

Removed accessors¶

The redesign dropped a few camelCase passthroughs. Their replacements:

Removed	Use instead
`im.isBipartite()`	set `bipartite_start_id`; there is no separate status accessor
`im.setBipartiteStartId(n)`	`im.bipartite_start_id = n` (a property)
`im.haveMetaData()`	declare with `set_meta_data()`; read `meta_entropy`
`im.numMetaDataDimensions`	one metadata dimension is supported; there is no count accessor