Deprecation policy

Infomap’s Python API follows a predictable deprecation contract so you can rely on it across releases. Nothing listed here leaves before 3.0; until then the old spelling keeps working. The reference docs mark each deprecated name with the release that deprecated it.

Signature tiers

The keyword arguments on Infomap and Infomap.run() are split into two tiers:

  • Common tier — the handful of options most runs touch (seed, num_trials, two_level, directed, markov_time). These stay on the Infomap signatures.

  • Advanced tier — the long tail of tuning and I/O options. From 2.15 they carry a versioned note on the Infomap signatures and leave those signatures in 3.0. Most are tuning options that stay available — only their entry point moves, marked .. versionchanged:: 2.15. Pass them through Options instead:

    import infomap

options = infomap.Options(regularized=True, flow_tolerance=1e-12)
result = infomap.run("network.net", options=options)

    The same Options object works with Network.run(). A few advanced options migrate elsewhere rather than to Options, and each keyword’s .. deprecated:: note states its own path:

    • The file-output options (no_file_output, tree, clu, out_name, …) move to the Result.write_* / Network.write_* methods.

    • silent and verbosity_level give way to logging (see Running Infomap).

    • num_threads replaces threads.

    • print_config_fingerprint is a CLI-only diagnostic with no library replacement.

Passing an advanced-tier keyword to Infomap or Infomap.run() emits a DeprecationWarning, shown by default when the calling code runs as a script (__main__, per PEP 565) and surfaced everywhere else by python -W or a warning-escalating tool. Routing the option through Options is the warning-free path, so existing code keeps running unchanged until 3.0.

Redesigned result access

The stateful accessors on Infomap (get_modules, codelength, num_top_modules, and friends) are .. deprecated:: 2.15 in favour of the immutable Result that run() and Infomap.run() return. Reading one from user code emits the same DeprecationWarning as the advanced-tier keywords. Read scalars as properties (result.codelength) and collections as methods (result.modules(), result.nodes(), result.tree()). See Reading the result.

The tree-level selector

From 2.16 the Result readers and write_clu select a level of the hierarchy with level (1 is the top, coarsest level; -1 the bottom):

result.modules(level=2)
result.to_dataframe(level=-1)
result.write_clu("bottom.clu", level=-1)

depth was the selector through 2.15, but the same word is TreeNode.depth, a node’s distance from the root, so result.nodes(depth=1) yielded nodes whose .depth is 2. depth and the older depth_level keep working as aliases through 2.x and emit the legacy tier’s DeprecationWarning; they leave in 3.0. On the same grounds Result.max_depth is a deprecated alias of Result.num_levels.

Compatibility aliases

  • On the graph constructors and finders, node_id and layer_id were the attribute names to read ids from, while node_ids on the matrix constructors was a sequence of labels – two unrelated parameters that read as singular and plural of one. From 2.16 the attribute names are node_id_attribute / layer_id_attribute (the *_attribute spelling meta_attribute already uses) and the label sequence is node_labels, on Network.from_networkx(), Network.from_igraph(), Network.from_scipy_sparse_matrix(), Network.from_edge_index(), find_communities() and find_igraph_communities(). The old spellings keep working, emit the legacy tier’s DeprecationWarning, and leave in 3.0.

  • annotate_networkx_graph and annotate_igraph_graph are the pre-2.16 spellings of infomap.io.export.annotate_networkx() and infomap.io.export.annotate_igraph() – the _graph suffix that to_networkx / from_networkx never carried. Same arguments; the long names emit the legacy tier’s DeprecationWarning and leave in 3.0.

  • include_self_links is a deprecated alias kept for backward compatibility. Infomap includes self-links by default. Pass no_self_links=True to exclude them. Passing include_self_links explicitly emits a FutureWarning – the louder tier, shown under every filter, because an argument you actually typed is being ignored.

  • pretty is a deprecated no-op — the API accepts it for backward compatibility but it has no effect. Passing it explicitly emits a FutureWarning, for the same reason as include_self_links.

Error base classes

infomap.merge.MergeError derives from InfomapError since 2.16, so except InfomapError catches shard-merge failures too; it derived from plain Exception before. except MergeError keeps working.

Through 2.x, InfomapError inherits RuntimeError, and NotRunError also keeps ValueError in its MRO. Pre-taxonomy except RuntimeError / except ValueError code therefore keeps working. These legacy bases detach in 3.0 — catch InfomapError (or a subclass) instead. See Errors.