infomap module

class infomap.Infomap(args=None)

Bases: infomap.InfomapWrapper

This class is a thin wrapper around Infomap C++ compiled with SWIG.

Examples

Create an instance and add nodes and links:

>>> import infomap
>>> im = infomap.Infomap()
>>> im.add_node(1)
>>> im.add_node(2)
>>> im.add_link(1, 2)
>>> im.run()
>>> im.codelength
1.0

Create an instance and read a network file:

>>> import infomap
>>> im = infomap.Infomap()
>>> im.read_file("ninetriangles.net")
>>> im.run("-N5")
>>> im.codelength
3.4841898804052187

For more examples, see the examples directory.

__init__(args=None)

Create a new Infomap instance.

Parameters

args (str, optional) – Space delimited parameter list (see Infomap documentation).

Add a link.

Notes

If the source or target nodes does not exist, they will be created.

See also

remove_link

Parameters
  • source_id (int) –

  • target_id (int) –

  • weight (float, optional) –

Add several links.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> links = (
...     (1, 2),
...     (1, 3)
... )
>>> im.add_links(links)
None

See also

add_link, remove_link

Parameters

links (iterable of tuples) – Iterable of tuples of int of the form (source_id, target_id, [weight])

Add a multilayer link.

Adds a link between layers in a multilayer network.

Parameters
  • source_multilayer_node (tuple of int, or MultilayerNode) – If passed a tuple, it should be of the format (layer_id, node_id).

  • target_multilayer_node (tuple of int, or MultilayerNode) – If passed a tuple, it should be of the format (layer_id, node_id).

  • weight (float, optional) –

Examples

Usage with tuples:

>>> from infomap import Infomap
>>> im = Infomap()
>>> source_multilayer_node = (0, 1) # layer_id, node_id
>>> target_multilayer_node = (1, 2) # layer_id, node_id
>>> im.add_multilayer_link(source_multilayer_node, target_multilayer_node)
None

Usage with MultilayerNode

>>> from infomap import Infomap, MultilayerNode
>>> im = Infomap()
>>> source_multilayer_node = MultilayerNode(layer_id=0, node_id=1)
>>> target_multilayer_node = MultilayerNode(layer_id=1, node_id=2)
>>> im.add_multilayer_link(source_multilayer_node, target_multilayer_node)
None

Add several multilayer links.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> links = (
...     ((0, 1), (1, 2)),
...     ((0, 3), (1, 2))
... )
>>> im.add_multilayer_links(links)
None
Parameters

links (iterable of tuples) – Iterable of tuples of the form (source_node, target_node, [weight])

add_node(node_id, name=None, teleportation_weight=None)

Add a node.

See also

set_name, add_nodes

Parameters
  • node_id (int) –

  • name (str, optional) –

  • teleportation_weight (float, optional) – Used for teleporting between layers in multilayer networks.

add_nodes(nodes)

Add several nodes.

See also

add_node

Examples

Add nodes

>>> from infomap import Infomap
>>> im = Infomap()
>>> im.add_nodes(range(4))
None

Add named nodes

>>> from infomap import Infomap
>>> im = Infomap()
>>> nodes = (
...     (1, "Node 1"),
...     (2, "Node 2"),
...     (3, "Node 3")
... )
>>> im.add_nodes(nodes)
None
Parameters

nodes (iterable of tuples or iterable of int) – Iterable of tuples on the form (node_id, [name], [teleportation_weight])

add_state_node(state_id, node_id)

Add a state node.

Notes

If a physical node with id node_id does not exist, it will be created. If you want to name the physical node, use set_name.

Parameters
  • state_id (int) –

  • node_id (int) – Id of the physical node the state node should be added to.

add_state_nodes(state_nodes)

Add several state nodes.

See also

add_state_node

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> states = (
...     (1, 1),
...     (2, 1),
...     (3, 2)
... )
>>> im.add_state_nodes(states)
None
Parameters

state_nodes (iterable of tuples) – Iterable of tuples of the form (state_id, node_id)

property bipartite_start_id

Get or set the bipartite start id.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> im.add_node(1, "Left 1")
>>> im.add_node(2, "Left 2")
>>> im.bipartite_start_id = 3
>>> im.add_node(3, "Right 3")
>>> im.add_node(4, "Right 4")
>>> im.add_link(1, 3)
>>> im.add_link(1, 4)
>>> im.add_link(2, 4)
>>> im.run()
None
Parameters

start_id (int) – The node id where the second node type starts.

Returns

The node id where the second node type starts.

Return type

int

property codelength

Get the total (hierarchical) codelength.

Returns

The codelength

Return type

float

property codelengths

Get the total (hierarchical) codelength for each trial.

See also

codelength

Returns

The codelengths for each trial

Return type

tuple of float

get_modules(depth_level=1, states=False)

Get the modules for a given depth in the hierarchical tree.

Parameters
  • depth_level (int, optional) – The level in the hierarchical tree. Set to 1 (default) to return the top modules (coarsest level), set to 2 for second coarsest level etc. Set to -1 to return the bottom level modules (finest level).

  • states (bool, optional) – For higher-order networks, if states is True, it will iterate over state nodes, otherwise it will iterate over physical nodes, merging state nodes with same node_id if they are in the same module. Note that the same physical node may end up on different paths in the tree. See notes on physical_tree.

Returns

Dict with node ids as keys and module ids as values.

Return type

dict of int

get_multilevel_modules(states=False)

Get all the modules.

Parameters

states (bool, optional) – For higher-order networks, if states is True, it will iterate over state nodes, otherwise it will iterate over physical nodes, merging state nodes with same node_id if they are in the same module. Note that the same physical node may end up on different paths in the tree. See notes on physical_tree.

Returns

Dict with node ids as keys and list of module ids as values.

Return type

dict of list of int

get_name(node_id, default=None)

Get the name of a node.

Notes

If the node name is an empty string, the default will be returned.

See also

set_name, names

Parameters
  • node_id (int) –

  • default (any) – The return value if the node name is missing.

Returns

The node name if it exists, else the default which is None

Return type

string or any

get_names()

Get all node names.

See also

names, get_name

Returns

A dict with node ids as keys and node names as values.

Return type

dict of string

get_nodes(depth_level=1, states=False)

A view of the tree

Parameters
  • depth_level (int, optional) – The module level returned by iterator.module_id. Set to 1 (default) to return the top modules (coarsest level), set to 2 for second coarsest level etc. Set to -1 to return the bottom level modules (finest level).

  • states (bool, optional) – For higher-order networks, if states is True, it will iterate over state nodes, otherwise it will iterate over physical nodes, merging state nodes with same node_id if they are in the same module. Note that the same physical node may end up on different paths in the tree. See notes on physical_tree.

Notes

For higher-order networks, each node is represented by a set of state nodes with the same node_id, where each state node represents a different memory constraining the random walker. This enables overlapping modules, where state nodes with the same node_id end up in different modules. However, the state nodes with the same node_id within each module are only visible as one (partial) physical node (if states = False).

Returns

An iterator over each node in the tree, depth first from the root

Return type

InfomapIterator or InfomapIteratorPhysical

get_tree(depth_level=1, states=False)

A view of the tree

Parameters
  • depth_level (int, optional) – The module level returned by iterator.module_id. Set to 1 (default) to return the top modules (coarsest level), set to 2 for second coarsest level etc. Set to -1 to return the bottom level modules (finest level).

  • states (bool, optional) – For higher-order networks, if states is True, it will iterate over state nodes, otherwise it will iterate over physical nodes, merging state nodes with same node_id if they are in the same module. Note that the same physical node may end up on different paths in the tree. See notes on physical_tree.

Notes

For higher-order networks, each node is represented by a set of state nodes with the same node_id, where each state node represents a different memory constraining the random walker. This enables overlapping modules, where state nodes with the same node_id end up in different modules. However, the state nodes with the same node_id within each module are only visible as one (partial) physical node (if states = False).

Returns

An iterator over each node in the tree, depth first from the root

Return type

InfomapIterator or InfomapIteratorPhysical

property index_codelength

Get the two-level index codelength.

Returns

The two-level index codelength

Return type

float

property initial_partition

Get or set the initial partition.

This is a initial configuration of nodes into modules where Infomap will start the optimizer.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> im.add_node(1)
>>> im.add_node(2)
>>> im.add_node(3)
>>> im.add_node(4)
>>> im.add_link(1, 2)
>>> im.add_link(1, 3)
>>> im.add_link(2, 3)
>>> im.add_link(2, 4)
>>> im.initial_partition = {
...     1: 0,
...     2: 0,
...     3: 1,
...     4: 1
... }
>>> im.run()
None

Notes

The initial partition is saved between runs. If you want to use an initial partition for one run only, use run(initial_partition=partition).

Parameters

module_ids (dict of int, or None) – Dict with node ids as keys and module ids as values.

Returns

Dict with node ids as keys and module ids as values.

Return type

dict of int

property leaf_modules

A view of the leaf modules, i.e. the bottom modules containing leaf nodes.

Returns

An iterator over each leaf module in the tree, depth first from the root

Return type

InfomapLeafModuleIterator

property max_depth

Get the max depth of the hierarchical tree.

Returns

The max depth

Return type

int

property meta_codelength

Get the meta codelength.

This is the meta entropy times the meta data rate.

See also

meta_entropy

Returns

The meta codelength

Return type

float

property meta_entropy

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

See also

meta_codelength

Returns

The meta entropy

Return type

float

property module_codelength

Get the total codelength of the modules.

The module codelength is defined such that codelength = index_codelength + module_codelength

For a hierarchical solution, the module codelength is the sum of codelengths for each top module.

Returns

The module codelength

Return type

float

property modules

A view of the (top-level) modules, mapping node_id to module_id.

Notes

In a higher-order network, a physical node (defined by node_id) may partially exist in multiple modules. However, the node_id can not exist multiple times as a key in the node-to-module map, so only one occurrence of a physical node will be retrieved. To get all states, use get_modules(states=True).

See also

get_modules

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> im.read_file("ninetriangles.net")
>>> im.run("-N5")
>>> for node_id, module_id in im.modules:
...     print(node_id, module_id)
...
1 1
2 1
3 1
4 1
5 1
6 1
7 1
8 1
9 1
10 2
11 2
12 2
13 2
14 2
15 2
16 2
17 2
18 2
19 0
20 0
21 0
22 0
23 0
24 0
25 0
26 0
27 0

See also

get_modules

Yields

tuple of int, int – An iterator of node_id, module_id pairs.

property names

Get all node names.

Short-hand for get_names.

See also

get_names, get_name

Returns

A dict with node ids as keys and node names as values.

Return type

dict of string

property network

Get the internal network.

property no_infomap

Set wether the optimizer should run or not.

Parameters

no_infomap (bool) –

property nodes

A view of the leaf nodes with the top level module ids

Returns

An iterator over each leaf node in the tree, depth first from the root

Return type

InfomapLeafIterator

property num_leaf_modules

Get the number of leaf modules in the tree

Returns

The number of leaf modules

Return type

int

property num_non_trivial_top_modules

Get the number of non-trivial top modules in the tree

A trivial module is a module with either one or all nodes within.

Returns

The number of non-trivial top modules

Return type

int

property num_top_modules

Get the number of top modules in the tree

Returns

The number of top modules

Return type

int

property one_level_codelength

Get the one-level codelength.

See also

codelength

Returns

The one-level codelength

Return type

float

property physical_nodes

A view of the physical leaf nodes with the top level module ids

Returns

An iterator over each physical leaf node in the tree, depth first from the root

Return type

InfomapLeafIteratorPhysical

property physical_tree

A view of the tree where that state nodes of the same node_id are merged to one physical node

Returns

An iterator over each physical node in the tree, depth first from the root

Return type

InfomapIteratorPhysical

read_file(filename, accumulate=True)

Read network data from file.

Parameters
  • filename (str) –

  • accumulate (bool, optional) – If the network data should be accumulated to already added nodes and links (default True).

property relative_codelength_savings

Get the relative codelength savings.

This is defined as the reduction in codelength relative to the non-modular one-level solution:

S_L = 1 - L / L_1

where L is the codelength and L_1 the one_level_codelength.

Returns

The relative codelength savings

Return type

float

Remove a link.

Notes

Removing links will not remove nodes if they become disconnected.

See also

add_link

Parameters
  • source_id (int) –

  • target_id (int) –

Remove several links.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> links = (
...     (1, 2),
...     (1, 3)
... )
>>> im.remove_links(links)
None

See also

remove_link

Parameters

links (iterable of tuples) – Iterable of tuples of the form (source_id, target_id)

run(args=None, initial_partition=None)

Run Infomap.

Parameters
  • args (str, optional) – Space delimited parameter list (see Infomap documentation).

  • initial_partition (dict, optional) – Initial partition to start optimizer from (see initial_partition).

set_meta_data(node_id, meta_category)

Set meta data to a node.

Parameters
  • node_id (int) –

  • meta_category (int) –

set_name(node_id, name)

Set the name of a node.

Parameters
  • node_id (int) –

  • name (str) –

set_names(names)

Set names to several nodes at once.

Example

>>> from infomap import Infomap
>>> im = Infomap()
>>> names = (
...     (1, "Node 1"),
...     (2, "Node 2")
... )
>>> im.set_names(names)
None

See also

set_name

Parameters

names (iterable of tuples) – Iterable of tuples on the form (node_id, name).

property tree

A view of the tree

Returns

An iterator over each node in the tree, depth first from the root

Return type

InfomapIterator

write_clu(filename, states=False, depth_level=1)

Write result to a clu file.

Parameters
  • filename (str) –

  • states (bool, optional) – If the state nodes should be included (default False).

  • depth_level (int, optional) – The depth in the hierarchical tree to write.

write_flow_tree(filename, states=False)

Write result to a ftree file.

See also

write_clu, write_tree

Parameters
  • filename (str) –

  • states (bool, optional) – If the state nodes should be included (default False).

write_tree(filename, states=False)

Write result to a tree file.

Parameters
  • filename (str) –

  • states (bool, optional) – If the state nodes should be included (default False).

class infomap.MultilayerNode(layer_id, node_id)

Bases: tuple

layer_id

Alias for field number 0

node_id

Alias for field number 1

class infomap.InfoNode(*args)
property child_degree

The number of children.

Returns

Number of children

Return type

int

property flow

Get the flow of the node.

Returns

The flow

Return type

float

get_meta_data(dimension=0)

Get meta data on a specific dimension.

Parameters

dimension (int) – The dimension (default 0)

Returns

The meta data

Return type

int

property is_leaf

True if the node has no children.

Returns

Is leaf node

Return type

bool

property is_leaf_module

True if the node has children but no grandchildren.

Returns

Is leaf module

Return type

bool

property is_root

True if the node has no parent.

Returns

Is root

Return type

bool

property layer_id

Get the layer id of a multilayer node.

Returns

The layer id

Return type

int

property meta_data

Meta data (on first dimension if more).

Returns

The meta data

Return type

int

property node_id

Get the physical node id.

Returns

The node id

Return type

int

property state_id

Get the state id of the node.

Returns

The state id

Return type

int

class infomap.InfomapIterator(*args)
property child_index

Get the child index.

Returns

The child index

Return type

int

property depth

Get the depth.

Returns

The depth

Return type

int

property module_id

Get the module id of the node.

Returns

The module id

Return type

int

property path

Get the path to the node in the tree.

Returns

The path

Return type

tuple of ints

class infomap.InfomapLeafModuleIterator(*args)
property child_index

Get the child index.

Returns

The child index

Return type

int

property depth

Get the depth.

Returns

The depth

Return type

int

property module_id

Get the module id of the node.

Returns

The module id

Return type

int

property path

Get the path to the node in the tree.

Returns

The path

Return type

tuple of ints

class infomap.InfomapLeafIterator(*args)
property child_index

Get the child index.

Returns

The child index

Return type

int

property depth

Get the depth.

Returns

The depth

Return type

int

property module_id

Get the module id of the node.

Returns

The module id

Return type

int

property path

Get the path to the node in the tree.

Returns

The path

Return type

tuple of ints

class infomap.InfomapIteratorPhysical(*args)
property child_index

Get the child index.

Returns

The child index

Return type

int

property depth

Get the depth.

Returns

The depth

Return type

int

property module_id

Get the module id of the node.

Returns

The module id

Return type

int

property path

Get the path to the node in the tree.

Returns

The path

Return type

tuple of ints

class infomap.InfomapLeafIteratorPhysical(*args)
property child_index

Get the child index.

Returns

The child index

Return type

int

property depth

Get the depth.

Returns

The depth

Return type

int

property module_id

Get the module id of the node.

Returns

The module id

Return type

int

property path

Get the path to the node in the tree.

Returns

The path

Return type

tuple of ints