infomap module¶
- class infomap.Infomap(args=None, **kwargs)¶
Bases:
infomap.InfomapWrapper
This class is a thin wrapper around Infomap C++ compiled with SWIG.
Examples
Create an instance and add nodes and links:
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> 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:
>>> from infomap import Infomap >>> im = Infomap(silent=True, num_trials=10) >>> im.read_file("ninetriangles.net") >>> im.run() >>> tol = 1e-4 >>> abs(im.codelength - 3.4622731375264144) < tol True
For more examples, see the examples directory.
- __init__(args=None, **kwargs)¶
Create a new Infomap instance.
- Parameters
args (str, optional) – String of Infomap arguments.
- Keyword Arguments
cluster_data (str, optional) – Provide an initial two-level (clu format) or multi-layer (tree format) solution.
no_infomap (bool, optional) – Don’t run the optimizer. Useful to calculate codelength of provided cluster data or to print non-modular statistics.
skip_adjust_bipartite_flow (bool, optional) – Skip distributing all flow from the bipartite nodes to the primary nodes.
bipartite_teleportation (bool, optional) – Teleport like the bipartite flow instead of two-step (unipartite) teleportation.
weight_threshold (float, optional) – Limit the number of links to read from the network. Ignore links with less weight than the threshold.
include_self_links (bool, optional) – Include links with the same source and target node. DEPRECATED. Include self links by default now, exclude with no_self_links.
no_self_links (bool, optional) – Exclude self links in the input network.
node_limit (int, optional) – Limit the number of nodes to read from the network. Ignore links connected to ignored nodes.
matchable_multilayer_ids (int, optional) – Construct state ids from node and layer ids that are consistent across networks for the same max number of layers. Set to at least the largest layer id among networks to match.
assign_to_neighbouring_module (bool, optional) – Assign nodes without module assignments (from
cluster_data
) to the module assignment of a neighbouring node if possible.meta_data (str, optional) – Provide meta data (clu format) that should be encoded.
meta_data_rate (float, optional) – Metadata encoding rate. Default is to encode each step.
meta_data_unweighted (bool, optional) – Don’t weight meta data by node flow.
tree (bool, optional) – Write a tree file with the modular hierarchy. Automatically enabled if no other output is specified.
ftree (bool, optional) – Write a ftree file with the modular hierarchy including aggregated links between (nested) modules.
clu (bool, optional) – Write a clu file with the top cluster ids for each node.
verbosity_level (int, optional) – Verbose output on the console.
silent (bool, optional) – No output on the console.
out_name (str, optional) – Name for the output files, e.g.
"[output_directory]/[out-name].tree"
no_file_output (bool, optional) – Don’t write output to file.
clu_level (int, optional) – For clu output, print modules at specified depth from root. Use
-1
for bottom level modules.output (list(str), optional) – List of output formats. Options: clu, tree, ftree, newick, json, csv, network, states.
hide_bipartite_nodes (bool, optional) – Project bipartite solution to unipartite.
two_level (bool, optional) – Optimize a two-level partition of the network. Default (
false
) is multi-level.flow_model (str, optional) – Specify flow model. Options: undirected, directed, undirdir, outdirdir, rawdir.
directed (bool, optional) – Assume directed links. Shorthand for
flow_model="directed"
.recorded_teleportation (bool, optional) – If teleportation is used to calculate the flow, also record it when minimizing codelength. Default False.
use_node_weights_as_flow (bool, optional) – Use node weights (from api or after names in Pajek format) as flow, normalized to sum to 1.
to_nodes (bool, optional) – Teleport to nodes instead of to links, assuming uniform node weights if no such input data.
teleportation_probability (float, optional) – Probability of teleporting to a random node or link.
regularized (bool, optional) – Effectively add a fully connected Bayesian prior network to not overfit due to missing links. Implies recorded teleportation.
regularization_strength (float, optional) – Adjust relative strength of Bayesian prior network with this multiplier.
entropy_corrected (bool, optional) – Correct for negative entropy bias in small samples (many modules).
entropy_correction_strength (float, optional) – Increase or decrease the default entropy correction with this multiplier.
markov_time (float, optional) – Scales link flow to change the cost of moving between modules. Higher values results in fewer modules.
preferred_number_of_modules (int, optional) – Penalize solutions the more they differ from this number.
multilayer_relax_rate (float, optional) – Probability to relax the constraint to move only in the current layer.
multilayer_relax_limit (int, optional) – Number of neighboring layers in each direction to relax to. If negative, relax to any layer.
multilayer_relax_limit_up (int, optional) – Number of neighboring layers with higher id to relax to. If negative, relax to any layer.
multilayer_relax_limit_down (int, optional) – Number of neighboring layers with lower id to relax to. If negative, relax to any layer.
multilayer_relax_by_jsd (bool, optional) – Relax proportional to the out-link similarity measured by the Jensen-Shannon divergence.
seed (int, optional) – A seed (integer) to the random number generator for reproducible results.
num_trials (int, optional) – Number of outer-most loops to run before picking the best solution.
core_loop_limit (int, optional) – Limit the number of loops that tries to move each node into the best possible module.
core_level_limit (int, optional) – Limit the number of times the core loops are reapplied on existing modular network to search bigger structures.
tune_iteration_limit (int, optional) – Limit the number of main iterations in the two-level partition algorithm. 0 means no limit.
core_loop_codelength_threshold (float, optional) – Minimum codelength threshold for accepting a new solution in core loop.
tune_iteration_relative_threshold (float, optional) – Set codelength improvement threshold of each new tune iteration to
f
times the initial two-level codelength.fast_hierarchical_solution (int, optional) – Find top modules fast. Use
2
to keep all fast levels. Use3
to skip recursive part.prefer_modular_solution (bool, optional) – Prefer modular solutions even if they are worse than putting all nodes in one module.
inner_parallelization (bool, optional) – Parallelize the inner-most loop for greater speed. This may give some accuracy tradeoff.
- add_link(source_id, target_id, weight=1.0)¶
Add a link.
Notes
If the source or target nodes does not exist, they will be created.
See also
- Parameters
source_id (int) –
target_id (int) –
weight (float, optional) –
- add_links(links)¶
Add several links.
Examples
>>> from infomap import Infomap >>> im = Infomap() >>> links = ( ... (1, 2), ... (1, 3) ... ) >>> im.add_links(links)
See also
- Parameters
links (iterable of tuples) – Iterable of tuples of int of the form
(source_id, target_id, [weight])
- add_multilayer_inter_link(source_layer_id, node_id, target_layer_id, weight=1.0)¶
Add a inter-layer link.
Adds a link between two layers in a multilayer network. The link is specified through a shared physical node, but that jump will not be recorded so Infomap will spread out this link to the next possible steps for the random walker in the target layer.
Notes
This multilayer format requires a directed network, so if the directed flag is not present, it will add all links also in their opposite direction to transform the undirected input to directed. If no inter-layer links are added, Infomap will simulate these by relaxing the random walker’s constraint to its current layer. The final state network will be generated on run, which will clear the temporary data structure that holds the provided inter-layer links.
Examples
>>> from infomap import Infomap >>> im = Infomap() >>> im.add_multilayer_inter_link(1, 1, 2) >>> im.add_multilayer_inter_link(1, 2, 2) >>> im.add_multilayer_inter_link(2, 1, 1) >>> im.add_multilayer_inter_link(2, 3, 1)
Notes
This multilayer format requires a directed network, so if the directed flag is not present, it will add all links also in their opposite direction to transform the undirected input to directed.
- Parameters
source_layer_id (int) –
node_id (int) –
target_layer_id (int) –
weight (float, optional) –
- add_multilayer_intra_link(layer_id, source_node_id, target_node_id, weight=1.0)¶
Add a intra-layer link.
Adds a link within a layer in a multilayer network.
Examples
>>> from infomap import Infomap >>> im = Infomap() >>> im.add_multilayer_intra_link(1, 1, 2) >>> im.add_multilayer_intra_link(1, 2, 3) >>> im.add_multilayer_intra_link(2, 1, 3) >>> im.add_multilayer_intra_link(2, 3, 4)
Notes
This multilayer format requires a directed network, so if the directed flag is not present, it will add all links also in their opposite direction to transform the undirected input to directed. If no inter-layer links are added, Infomap will simulate those by relaxing the random walker’s constraint to its current layer. The final state network will be generated on run, which will clear the temporary data structure that holds the provided intra-layer links.
- Parameters
layer_id (int) –
source_node_id (int) –
target_node_id (int) –
weight (float, optional) –
- add_multilayer_link(source_multilayer_node, target_multilayer_node, weight=1.0)¶
Add a multilayer link.
Adds a link between layers in a multilayer network.
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)
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)
Notes
This is the full multilayer format that supports both undirected and directed links. Infomap will not make any changes to the 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) –
- add_multilayer_links(links)¶
Add several multilayer links.
Examples
>>> from infomap import Infomap >>> im = Infomap() >>> links = ( ... ((0, 1), (1, 2)), ... ((0, 3), (1, 2)) ... ) >>> im.add_multilayer_links(links)
See also
- Parameters
links (iterable of tuples) – Iterable of tuples of the form
(source_node, target_node, [weight])
- add_networkx_graph(g, weight='weight')¶
Add NetworkX graph
Examples
>>> import networkx as nx >>> from infomap import Infomap >>> G = nx.Graph([("a", "b"), ("a", "c")]) >>> im = Infomap(silent=True) >>> mapping = im.add_networkx_graph(G) >>> mapping {0: 'a', 1: 'b', 2: 'c'} >>> im.run() >>> for node in im.nodes: ... print(node.node_id, node.module_id, node.flow, mapping[node.node_id]) 0 1 0.5 a 1 1 0.25 b 2 1 0.25 c
Notes
Transforms non-int labels to unique int ids. Assumes that all nodes are of the same type. If node type is string, they are added as names to Infomap. If the NetworkX graph is directed (
nx.DiGraph
), and no flow model has been specified in the constructor, this method sets thedirected
flag toTrue
.- Parameters
g (nx.Graph) – A NetworkX graph
weight (str, optional) – Key to lookup link weight in edge data if present. Default
"weight"
.
- Returns
Dict with the node ids as keys and labels as values.
- Return type
dict
- add_node(node_id, name=None, teleportation_weight=None)¶
Add a node.
- Parameters
node_id (int) –
name (str, optional) –
teleportation_weight (float, optional) – Used for teleporting between layers in multilayer networks.
- add_nodes(nodes)¶
Add nodes.
See also
Examples
Add nodes
>>> from infomap import Infomap >>> im = Infomap() >>> im.add_nodes(range(4))
Add named nodes
>>> from infomap import Infomap >>> im = Infomap() >>> nodes = ( ... (1, "Node 1"), ... (2, "Node 2"), ... (3, "Node 3") ... ) >>> im.add_nodes(nodes) >>> im.names {1: 'Node 1', 2: 'Node 2', 3: 'Node 3'}
Add named nodes with teleportation weights
>>> from infomap import Infomap >>> im = Infomap() >>> nodes = ( ... (1, "Node 1", 0.5), ... (2, "Node 2", 0.2), ... (3, "Node 3", 0.8) ... ) >>> im.add_nodes(nodes) >>> im.names {1: 'Node 1', 2: 'Node 2', 3: 'Node 3'}
Add named nodes using dict
>>> from infomap import Infomap >>> im = Infomap() >>> nodes = { ... 1: "Node 1", ... 2: "Node 2", ... 3: "Node 3" ... } >>> im.add_nodes(nodes) >>> im.names {1: 'Node 1', 2: 'Node 2', 3: 'Node 3'}
Add named nodes with teleporation weights using dict
>>> from infomap import Infomap >>> im = Infomap() >>> nodes = { ... 1: ("Node 1", 0.5), ... 2: ("Node 2", 0.2), ... 3: ("Node 3", 0.8) ... } >>> im.add_nodes(nodes) >>> im.names {1: 'Node 1', 2: 'Node 2', 3: 'Node 3'}
- Parameters
nodes (iterable of tuples or iterable of int or dict of int: str or dict of int: tuple of (str, float)) – 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 state nodes.
See also
Examples
With tuples
>>> from infomap import Infomap >>> im = Infomap() >>> states = ( ... (1, 1), ... (2, 1), ... (3, 2) ... ) >>> im.add_state_nodes(states)
With dict
>>> from infomap import Infomap >>> im = Infomap() >>> states = { ... 1: 1, ... 2: 1, ... 3: 2 ... } >>> im.add_state_nodes(states)
- Parameters
state_nodes (iterable of tuples or dict of int: int) – Iterable of tuples of the form
(state_id, node_id)
or dict of the form{state_id: node_id}
.
- property bipartite_start_id¶
Get or set the bipartite start id.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True, num_trials=10) >>> 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() >>> tol = 1e-4 >>> abs(im.codelength - 0.9182958340544896) < tol True
- 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.
See also
- Returns
The codelength
- Return type
float
- property codelengths¶
Get the total (hierarchical) codelength for each trial.
See also
- Returns
The codelengths for each trial
- Return type
tuple of float
- property effective_num_leaf_modules¶
The flow weighted effective number of leaf modules.
Measured as the perplexity of the module flow distribution.
- Returns
The effective number of top modules
- Return type
float
- property effective_num_top_modules¶
The flow weighted effective number of top modules.
Measured as the perplexity of the module flow distribution.
- Returns
The effective number of top modules
- Return type
float
- property flow_links¶
A view of the currently assigned links and their flow.
The sources and targets are state ids when we have a state or multilayer network.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("twotriangles.net") >>> im.run() >>> for link in im.flow_links: ... print(link) (1, 2, 0.14285714285714285) (1, 3, 0.14285714285714285) (2, 3, 0.14285714285714285) (3, 4, 0.14285714285714285) (4, 5, 0.14285714285714285) (4, 6, 0.14285714285714285) (5, 6, 0.14285714285714285)
See also
- Returns
An iterator of source, target, flow tuples.
- Return type
tuple of int, int, float
- get_dataframe(columns=['path', 'flow', 'name', 'node_id'])¶
Get a Pandas DataFrame with the selected columns.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("twotriangles.net") >>> im.run() >>> im.get_dataframe() path flow name node_id 0 (1, 1) 0.214286 C 3 1 (1, 2) 0.142857 A 1 2 (1, 3) 0.142857 B 2 3 (2, 1) 0.214286 D 4 4 (2, 2) 0.142857 E 5 5 (2, 3) 0.142857 F 6 >>> im.get_dataframe(columns=["node_id", "module_id"]) node_id module_id 0 3 1 1 1 1 2 2 1 3 4 2 4 5 2 5 6 2
- Parameters
columns (list(str)) – A list of columns that should be extracted from each node. Must be available as an attribute of
InfoNode
,InfomapLeafIterator
(for state nodes), orInfomapLeafIteratorPhysical
. One exception to this is"name"
which is looked up internally. Default["path", "flow", "name", "node_id"]
.- Raises
ImportError – If the pandas package is not available.
AttributeError – If a column name is not available as an
InfoNode
attribute.
- Returns
A DataFrame containing the selected columns.
- Return type
pandas.DataFrame
- get_effective_num_modules(depth_level=1)¶
The flow weighted effective number of modules.
Measured as the perplexity of the module flow distribution.
- Parameters
depth_level (int, optional) – The module level returned by
iterator.depth
. Set to1
(default) to return the top modules (coarsest level). Set to2
for second coarsest level etc. Set to-1
to return the bottom level modules (finest level).- Returns
The effective number of modules
- Return type
float
- get_links(data='weight')¶
A view of the currently assigned links and their weights or flow.
The sources and targets are state ids when we have a state or multilayer network.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("twotriangles.net") >>> im.run() >>> for link in im.get_links(): ... print(link) (1, 2, 1.0) (1, 3, 1.0) (2, 3, 1.0) (3, 4, 1.0) (4, 5, 1.0) (4, 6, 1.0) (5, 6, 1.0) >>> for link in im.get_links(data="flow"): ... print(link) (1, 2, 0.14285714285714285) (1, 3, 0.14285714285714285) (2, 3, 0.14285714285714285) (3, 4, 0.14285714285714285) (4, 5, 0.14285714285714285) (4, 6, 0.14285714285714285) (5, 6, 0.14285714285714285)
See also
- Parameters
data (str) – The kind of data to return, one of
"weight"
or"flow"
. Default"weight"
.- Returns
An iterator of source, target, weight/flow tuples.
- Return type
tuple of int, int, float
- get_modules(depth_level=1, states=False)¶
Get a dict with node ids as keys and module ids as values for a given depth in the hierarchical tree.
Level Root 0 ┌─┐ ┌─────────┴─┴────────┐ │ │ │ │ │ │ Path │ Module Path │ Module 1 1 ┌┼┐ 1 2 ┌┼┐ 2 ┌───┴─┴───┐ ┌───┴─┴───┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ 2 1 ┌┼┐ 1 2 ┌┼┐ 2 1 ┌┼┐ 3 2 ┌┼┐ 3 ┌───┴─┴───┐ └─┴────┐ └─┘ └─┘ │ │ │ │ │ │ ▲ ▲ │ │ │ └────┬────┘ │ │ │ │ 3 1 ┌┼┐ 2 ┌┼┐ 1 ┌┼┐ └─┘ └─┘ └─┘ ◄─── Leaf-nodes
Path to the left of the nodes. Depth dependent module ids to the right. The five leaf-nodes are network-nodes. All other tree-nodes are modules.
For example:
The left-most node on level 3 has path 1:1:1 and belong to module 1 on level 1.
The right-most node on level 2 has path 2:2 and belong to module 2 on level 1 which is renamed to module 3 on level 2 as we have more modules in total on this level.
Assuming the nodes are labelled 1-5 from left to right, then the first three nodes are in module 1, and the last two nodes are in module 2:
> im.get_modules(depth_level=1) {1: 1, 2: 1, 3: 1, 4: 2, 5: 2}
However, at level 2, the first two nodes are in module 1, the third node in module 2, and the last two nodes are in module 3:
> im.get_modules(depth_level=2) {1: 1, 2: 1, 3: 2, 4: 3, 5: 3}
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("twotriangles.net") >>> im.run() >>> im.get_modules() {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 2}
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("states.net") >>> im.run() >>> im.get_modules(states=True) {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 2}
Notes
In a higher-order network, a physical node (defined by
node_id
) may partially exist in multiple modules. However, thenode_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, useget_modules(states=True)
.- Parameters
depth_level (int, optional) – The level in the hierarchical tree. Set to
1
(default) to return the top modules (coarsest level). Set to2
for second coarsest level etc. Set to-1
to return the bottom level modules (finest level). Default1
.states (bool, optional) – For higher-order networks, if
states
is True, it will return state node ids. Otherwise it will return physical node ids, merging state nodes with samenode_id
if they are in the same module. Note that the same physical node may end up on different paths in the tree. Defaultfalse
.
- Returns
Dict with node ids as keys and module ids as values.
- Return type
dict of int
- get_multilevel_modules(states=False)¶
Get a dict with node ids as keys and a tuple of module ids as values. Each position in the tuple corresponds to a depth in the hierarchical tree, with the first level being the top level.
See also
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("ninetriangles.net") >>> im.run() >>> for node, modules in im.get_multilevel_modules().items(): ... print(node, modules) 1 (6, 8) 2 (6, 8) 3 (6, 8) 4 (2, 4) 5 (2, 4) 6 (2, 4) 7 (3, 5) 8 (3, 5) 9 (3, 5) 10 (4, 6) 11 (4, 6) 12 (4, 6) 13 (7, 9) 14 (7, 9) 15 (7, 9) 16 (5, 7) 17 (5, 7) 18 (5, 7) 19 (1, 1) 20 (1, 1) 21 (1, 1) 22 (1, 2) 23 (1, 2) 24 (1, 2) 25 (1, 3) 26 (1, 3) 27 (1, 3)
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("states.net") >>> im.run() >>> for node, modules in im.get_multilevel_modules(states=True).items(): ... print(node, modules) 1 (1,) 2 (1,) 3 (1,) 4 (2,) 5 (2,) 6 (2,)
Notes
In a higher-order network, a physical node (defined by
node_id
) may partially exist in multiple modules. However, thenode_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, useget_multilevel_modules(states=True)
.- Parameters
states (bool, optional) – For higher-order networks, if
states
is True, it will return state node ids. Otherwise it will return physical node ids, merging state nodes with samenode_id
if they are in the same module. Note that the same physical node may end up on different paths in the tree. Defaultfalse
.- Returns
Dict with node ids as keys and tuple 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.- Parameters
node_id (int) –
default (str, optional) – The return value if the node name is missing, default
None
- Returns
The node name if it exists, else the
default
.- Return type
str
- get_names()¶
Get all node names.
- 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 nodes in the hierarchical tree, iterating depth first from the root.
- Parameters
depth_level (int, optional) – The module level returned by
iterator.module_id
. Set to1
(default) to return the top modules (coarsest level). Set to2
for second coarsest level etc. Set to-1
to return the bottom level modules (finest level). Default1
.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 samenode_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 onphysical_tree
. Defaultfalse
.
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 constraint on the random walker. This enables overlapping modules, where state nodes with the samenode_id
end up in different modules. However, the state nodes with the samenode_id
within each module are only visible as one (partial) physical node (ifstates = False
).- Returns
An iterator over each node in the tree, depth first from the root
- Return type
- get_tree(depth_level=1, states=False)¶
A view of the hierarchical tree, iterating over the modules as well as the leaf-nodes.
- Parameters
depth_level (int, optional) – The module level returned by
iterator.module_id
. Set to1
(default) to return the top modules (coarsest level). Set to2
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 samenode_id
if they are in the same module. Note that the same physical node may end up on different paths in the tree. Defaultfalse
.
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 constraint on the random walker. This enables overlapping modules, where state nodes with the samenode_id
end up in different modules. However, the state nodes with the samenode_id
within each module are only visible as one (partial) physical node (ifstates = False
).- Returns
An iterator over each node in the tree, depth first from the root
- Return type
- property index_codelength¶
Get the two-level index codelength.
See also
- 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.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> 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(no_infomap=True) >>> tol = 1e-4 >>> abs(im.codelength - 3.4056390622295662) < tol True
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.
See also
- Returns
An iterator over each leaf module in the tree, depth first from the root
- Return type
- property links¶
A view of the currently assigned links and their weights.
The sources and targets are state ids when we have a state or multilayer network.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True) >>> im.read_file("twotriangles.net") >>> im.run() >>> for link in im.links: ... print(link) (1, 2, 1.0) (1, 3, 1.0) (2, 3, 1.0) (3, 4, 1.0) (4, 5, 1.0) (4, 6, 1.0) (5, 6, 1.0)
See also
- Returns
An iterator of source, target, weight tuples.
- Return type
tuple of int, int, float
- 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
- Returns
The meta codelength
- Return type
float
- property meta_entropy¶
Get the meta entropy (unweighted by meta data rate).
See also
- 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.
See also
- Returns
The module codelength
- Return type
float
- property modules¶
A view of the top-level modules, mapping
node_id
tomodule_id
.Notes
In a higher-order network, a physical node (defined by
node_id
) may partially exist in multiple modules. However, thenode_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, useget_modules(states=True)
.Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True, num_trials=5) >>> im.read_file("twotriangles.net") >>> im.run() >>> for node_id, module_id in im.modules: ... print(node_id, module_id) ... 1 1 2 1 3 1 4 2 5 2 6 2
See also
- Yields
tuple of int, int – An iterator of
(node_id, module_id)
pairs.
- property multilevel_modules¶
A view of the multilevel modules, mapping
node_id
to a tuple ofmodule_id
.Notes
In a higher-order network, a physical node (defined by
node_id
) may partially exist in multiple modules. However, thenode_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, useget_multilevel_modules(states=True)
.See also
- Yields
tuple of (int, tuple of int) – An iterator of
(node_id, (module_ids...)
pairs.
- property names¶
Get all node names.
Short-hand for
get_names
.- 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 nodes¶
A view of the nodes in the hierarchical tree, iterating depth first from the root.
Convinience method for
get_nodes(depth_level=1, states=True)
.See also
- Returns
An iterator over each leaf node in the tree, depth first from the root
- Return type
- property num_leaf_modules¶
Get the number of leaf modules in the tree
- Returns
The number of leaf modules
- Return type
int
- property num_levels¶
Get the max depth of the hierarchical tree. Alias of
max_depth
.See also
- Returns
The max depth
- Return type
int
- property num_links¶
The number of links.
- Returns
The number of links
- Return type
int
- property num_nodes¶
The number of state nodes if we have a higher order network, or the number of physical nodes.
See also
- Returns
The number of nodes
- 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_physical_nodes¶
The number of physical nodes.
See also
- Returns
The number of nodes
- 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
- Returns
The one-level codelength
- Return type
float
- property physical_nodes¶
A view of the nodes in the hierarchical tree, iterating depth first from the root. All state nodes with the same
node_id
are merged to one physical node.Convinience method for
get_nodes(depth_level=1, states=False)
.See also
- Returns
An iterator over each physical leaf node in the tree, depth first from the root
- Return type
- property physical_tree¶
A view of the hierarchical tree, iterating over the modules as well as the leaf-nodes. All state nodes with the same
node_id
are merged to one physical node.Convinience method for
get_tree(depth_level=1, states=False)
.See also
- Returns
An iterator over each physical node in the tree, depth first from the root
- Return type
- 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 thecodelength
andL_1
theone_level_codelength
.See also
- Returns
The relative codelength savings
- Return type
float
- remove_link(source_id, target_id)¶
Remove a link.
Notes
Removing links will not remove nodes if they become disconnected.
See also
- Parameters
source_id (int) –
target_id (int) –
- remove_links(links)¶
Remove several links.
Examples
>>> from infomap import Infomap >>> im = Infomap() >>> links = ( ... (1, 2), ... (1, 3) ... ) >>> im.add_links(links) >>> im.remove_links(links) >>> im.num_links 0
See also
- Parameters
links (iterable of tuples) – Iterable of tuples of the form
(source_id, target_id)
- run(args=None, initial_partition=None, **kwargs)¶
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
).
- Keyword Arguments
tree (bool, optional) – Write a tree file with the modular hierarchy. Automatically enabled if no other output is specified.
ftree (bool, optional) – Write a ftree file with the modular hierarchy including aggregated links between (nested) modules.
clu (bool, optional) – Write a clu file with the top cluster ids for each node.
verbosity_level (int, optional) – Verbose output on the console.
silent (bool, optional) – No output on the console.
out_name (str, optional) – Name for the output files, e.g.
"[output_directory]/[out-name].tree"
no_file_output (bool, optional) – Don’t write output to file.
clu_level (int, optional) – For clu output, print modules at specified depth from root. Use
-1
for bottom level modules.output (list(str), optional) – List of output formats. Options: clu, tree, ftree, newick, json, csv, network, states.
hide_bipartite_nodes (bool, optional) – Project bipartite solution to unipartite.
two_level (bool, optional) – Optimize a two-level partition of the network. Default (
false
) is multi-level.flow_model (str, optional) – Specify flow model. Options: undirected, directed, undirdir, outdirdir, rawdir.
directed (bool, optional) – Assume directed links. Shorthand for
flow_model="directed"
.use_node_weights_as_flow (bool, optional) – Use node weights (from api or after names in Pajek format) as flow, normalized to sum to 1.
to_nodes (bool, optional) – Teleport to nodes instead of to links, assuming uniform node weights if no such input data.
teleportation_probability (float, optional) – Probability of teleporting to a random node or link.
regularized (bool, optional) – Effectively add a fully connected Bayesian prior network to not overfit due to missing links. Implies recorded teleportation.
regularization_strength (float, optional) – Adjust relative strength of Bayesian prior network with this multiplier.
entropy_corrected (bool, optional) – Correct for negative entropy bias in small samples (many modules).
entropy_correction_strength (float, optional) – Increase or decrease the default entropy correction with this multiplier.
markov_time (float, optional) – Scales link flow to change the cost of moving between modules. Higher values results in fewer modules.
preferred_number_of_modules (int, optional) – Penalize solutions the more they differ from this number.
multilayer_relax_rate (float, optional) – Probability to relax the constraint to move only in the current layer.
multilayer_relax_limit (int, optional) – Number of neighboring layers in each direction to relax to. If negative, relax to any layer.
multilayer_relax_limit_up (int, optional) – Number of neighboring layers with higher id to relax to. If negative, relax to any layer.
multilayer_relax_limit_down (int, optional) – Number of neighboring layers with lower id to relax to. If negative, relax to any layer.
multilayer_relax_by_jsd (bool, optional) – Relax proportional to the out-link similarity measured by the Jensen-Shannon divergence.
seed (int, optional) – A seed (integer) to the random number generator for reproducible results.
num_trials (int, optional) – Number of outer-most loops to run before picking the best solution.
core_loop_limit (int, optional) – Limit the number of loops that tries to move each node into the best possible module.
core_level_limit (int, optional) – Limit the number of times the core loops are reapplied on existing modular network to search bigger structures.
tune_iteration_limit (int, optional) – Limit the number of main iterations in the two-level partition algorithm. 0 means no limit.
core_loop_codelength_threshold (float, optional) – Minimum codelength threshold for accepting a new solution in core loop.
tune_iteration_relative_threshold (float, optional) – Set codelength improvement threshold of each new tune iteration to
f
times the initial two-level codelength.fast_hierarchical_solution (int, optional) – Find top modules fast. Use
2
to keep all fast levels. Use3
to skip recursive part.prefer_modular_solution (bool, optional) – Prefer modular solutions even if they are worse than putting all nodes in one module.
inner_parallelization (bool, optional) – Parallelize the inner-most loop for greater speed. This may give some accuracy tradeoff.
See also
- set_meta_data(node_id, meta_category)¶
Set meta data to a node.
Examples
>>> from infomap import Infomap >>> im = Infomap(silent=True, num_trials=10) >>> im.add_links(( ... (1, 2), (1, 3), (2, 3), ... (3, 4), ... (4, 5), (4, 6), (5, 6) ... )) >>> im.set_meta_data(1, 0) >>> im.set_meta_data(2, 0) >>> im.set_meta_data(3, 1) >>> im.set_meta_data(4, 1) >>> im.set_meta_data(5, 0) >>> im.set_meta_data(6, 0) >>> im.run(meta_data_rate=0) >>> im.num_top_modules 2 >>> im.run(meta_data_rate=2) >>> im.num_top_modules 3
- 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.
Examples
With tuples
>>> from infomap import Infomap >>> im = Infomap() >>> names = ( ... (1, "Node 1"), ... (2, "Node 2") ... ) >>> im.set_names(names) >>> im.names {1: 'Node 1', 2: 'Node 2'}
With dict
>>> from infomap import Infomap >>> im = Infomap() >>> names = { ... 1: "Node 1", ... 2: "Node 2" ... } >>> im.set_names(names) >>> im.names {1: 'Node 1', 2: 'Node 2'}
- Parameters
names (iterable of tuples or dict of int: str) – Iterable of tuples on the form
(node_id, name)
or dict of the form{node_id: name}
.
- property tree¶
A view of the hierarchical tree, iterating over the modules as well as the leaf-nodes.
Convinience method for
get_tree(depth_level=1, states=True)
.See also
- Returns
An iterator over each node in the tree, depth first from the root
- Return type
- write(filename, *args, **kwargs)¶
Write results to file.
- Raises
NotImplementedError – If the file format is not supported.
- Parameters
filename (str) – The filename.
- write_clu(filename, states=False, depth_level=1)¶
Write result to a clu file.
See also
- 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_csv(filename, states=False)¶
Write result to a CSV file.
See also
- Parameters
filename (str) –
states (bool, optional) – If the state nodes should be included. Default
False
.
- write_flow_tree(filename, states=False)¶
Write result to a ftree file.
See also
- Parameters
filename (str) –
states (bool, optional) – If the state nodes should be included. Default
False
.
- write_json(filename, states=False)¶
Write result to a JSON file.
See also
- Parameters
filename (str) –
states (bool, optional) – If the state nodes should be included. Default
False
.
- write_newick(filename, states=False)¶
Write result to a Newick file.
See also
- Parameters
filename (str) –
states (bool, optional) – If the state nodes should be included. Default
False
.
- write_pajek(filename, flow=False)¶
Write network to a Pajek file.
See also
- Parameters
filename (str) –
flow (bool, optional) – If the flow should be included. Default
False
.
- write_state_network(filename)¶
Write internal state network to file.
See also
- Parameters
filename (str) –
- write_tree(filename, states=False)¶
Write result to a tree file.
See also
- 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 modular_centrality¶
Get the modular centrality of the node.
- Returns
The modular centrality
- Return type
float
- 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 modular_centrality¶
Get the modular centrality of the node.
- Returns
The modular centrality
- Return type
float
- 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 modular_centrality¶
Get the modular centrality of the node.
- Returns
The modular centrality
- Return type
float
- 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 modular_centrality¶
Get the modular centrality of the node.
- Returns
The modular centrality
- Return type
float
- 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 modular_centrality¶
Get the modular centrality of the node.
- Returns
The modular centrality
- Return type
float
- 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