Infomap network clustering
Description
Constructor for an Infomap network clustering instance. Mirrors the
Python Infomap class in shape, with named arguments for every CLI
flag and active bindings for read-only properties.
R6 class encapsulating an Infomap clustering session. Most users
should call the Infomap() wrapper rather than constructing this
class directly. The generator is exported for subclassing and
method introspection.
Usage
Infomap(args = NULL, opts = NULL, ...)
Infomap(args = NULL, opts = NULL, ...)
Arguments
Details
Build a network by calling add_node() / add_link() (or pass an
existing igraph object to add_igraph()), then run with run().
Inspect results via the active bindings (codelength, modules,
num_top_modules, ...) or use as.data.frame() for a tidy
node-level frame.
Returned objects have R6 class "Infomap"; the underlying
R6ClassGenerator is also exported as InfomapClass for advanced use
(subclassing, method introspection).
Methods are grouped here as input (build the network), run
(optimise the partition), igraph integration, results (read out
module assignments and node attributes), and writers (export to
.tree / .clu / etc).
Value
An object of R6 class "Infomap".
Active bindings
swig-
The underlying SWIG-generated InfomapWrapper handle.
network-
The underlying Network reference.
codelength-
Total (hierarchical) codelength.
codelengths-
Codelength of each trial.
num_top_modules-
Number of top modules in the tree.
num_non_trivial_top_modules-
Number of non-trivial top modules.
num_levels-
Number of levels in the tree.
max_tree_depth-
Maximum depth of the tree.
num_leaf_nodes-
Number of leaf nodes in the tree.
num_nodes-
Number of nodes (state nodes for higher-order networks).
num_physical_nodes-
Number of physical nodes.
num_links-
Number of links.
have_memory-
TRUE if this is a state/multilayer network.
index_codelength-
Index codelength (top-level part of the codelength).
module_codelength-
Module codelength (within-module part).
hierarchical_codelength-
Hierarchical codelength.
one_level_codelength-
One-level codelength baseline.
relative_codelength_savings-
Relative codelength savings.
entropy_rate-
Entropy rate of the network.
max_entropy-
Maximum possible entropy.
bipartite_start_id-
Get or set the bipartite start id.
modules-
Top-level module assignment per node (named integer vector).
multilevel_modules-
List of integer paths for each node
through the module hierarchy.
nodes-
Per-state-node attributes (state id, physical id,
module, flow, optional layer id).
physical_nodes-
Per-physical-node attributes (state nodes
merged within a module).
links-
Per-link source, target, weight and flow as a
data.frame.
flow_links-
Per-link source, target and flow as a
data.frame.
names-
Named character vector of all assigned node names.
Methods
Public methods
Method new()
Create a new Infomap instance.
Usage
InfomapClass$new(args = NULL, opts = NULL, ...)
Arguments
Method read_file()
Read network data from file.
Usage
InfomapClass$read_file(filename, accumulate = TRUE)
Arguments
filename-
Path to a network file (.net, .txt, .tree, etc.).
accumulate-
If TRUE (default), accumulate to existing nodes/links.
Method add_node()
Add a node.
Usage
InfomapClass$add_node(node_id, name = NULL, teleportation_weight = NULL)
Arguments
node_id-
Integer node id.
name-
Optional node name.
teleportation_weight-
Optional teleportation weight.
Method add_nodes()
Add many nodes at once.
Usage
InfomapClass$add_nodes(nodes)
Arguments
nodes-
A list of integer node ids, or a list of vectors of the form
c(node_id, name, teleportation_weight) (last two optional), or a
named list/vector mapping node_id to name or to
c(name, teleportation_weight).
Method add_state_node()
Add a state node.
Usage
InfomapClass$add_state_node(state_id, node_id)
Arguments
state_id-
Integer state node id.
node_id-
Integer physical node id.
Method add_state_nodes()
Add many state nodes at once.
Usage
InfomapClass$add_state_nodes(state_nodes)
Arguments
state_nodes-
A list of c(state_id, node_id) vectors, or a
named list/vector mapping state_id to node_id.
Method set_name()
Set the name of a node.
Usage
InfomapClass$set_name(node_id, name)
Arguments
node_id-
Integer node id.
name-
Node name (character). NULL clears the name.
Method set_names()
Set names for several nodes at once.
Usage
InfomapClass$set_names(mapping)
Arguments
mapping-
A list of c(node_id, name) vectors, or a named
list/vector mapping node_id to name.
Method add_link()
Add a link.
Usage
InfomapClass$add_link(source_id, target_id, weight = 1)
Arguments
source_id-
Source node id.
target_id-
Target node id.
weight-
Link weight.
Method add_links()
Add many links at once.
Usage
InfomapClass$add_links(links)
Arguments
links-
A list of vectors of the form c(source, target, weight)
(weight optional), or a 2- or 3-column matrix / data.frame whose
first two columns are integer/numeric node ids and (optionally)
third column is numeric weight.
Method remove_link()
Remove a link.
Usage
InfomapClass$remove_link(source_id, target_id)
Arguments
source_id-
Source node id.
target_id-
Target node id.
Method remove_links()
Remove many links at once.
Usage
InfomapClass$remove_links(links)
Arguments
links-
A list of c(source, target) vectors.
Method add_multilayer_link()
Add a multilayer link.
Usage
InfomapClass$add_multilayer_link(
source_multilayer_node,
target_multilayer_node,
weight = 1
)
Arguments
source_multilayer_node-
A c(layer_id, node_id) vector or
the result of multilayer_node().
target_multilayer_node-
A c(layer_id, node_id) vector or
the result of multilayer_node().
weight-
Link weight.
Method add_multilayer_intra_link()
Add an intra-layer link in a multilayer network.
Usage
InfomapClass$add_multilayer_intra_link(
layer_id,
source_node_id,
target_node_id,
weight = 1
)
Arguments
layer_id-
Integer layer id.
source_node_id-
Source node id.
target_node_id-
Target node id.
weight-
Link weight.
Method add_multilayer_intra_links()
Add many intra-layer links in a multilayer network.
Usage
InfomapClass$add_multilayer_intra_links(links)
Arguments
links-
A list of vectors of the form
c(layer, source_node, target_node, weight) (weight optional), or
a 3- or 4-column matrix / data.frame.
Method add_multilayer_inter_link()
Add an inter-layer link in a multilayer network.
Usage
InfomapClass$add_multilayer_inter_link(
source_layer_id,
node_id,
target_layer_id,
weight = 1
)
Arguments
source_layer_id-
Source layer id.
node_id-
Physical node id (same in both layers).
target_layer_id-
Target layer id.
weight-
Link weight.
Method add_multilayer_inter_links()
Add many inter-layer links in a multilayer network.
Usage
InfomapClass$add_multilayer_inter_links(links)
Arguments
links-
A list of vectors of the form
c(source_layer, node, target_layer, weight) (weight optional), or
a 3- or 4-column matrix / data.frame.
Method add_multilayer_links()
Add many multilayer links at once.
Usage
InfomapClass$add_multilayer_links(links)
Arguments
links-
A list whose entries are
list(source_multilayer_node, target_multilayer_node, weight)
(weight optional), or a 4- or 5-column matrix / data.frame of
source_layer, source_node, target_layer, target_node, and
optional weight.
Method set_meta_data()
Set meta data for a node.
Usage
InfomapClass$set_meta_data(node_id, meta_category)
Arguments
node_id-
Integer node id.
meta_category-
Integer meta category.
Method run()
Run Infomap.
Usage
InfomapClass$run(args = NULL, opts = NULL, ...)
Arguments
args-
Optional raw CLI argument string for this run only.
opts-
Optional infomap_options() result for this run only.
...-
Named option overrides for this run only.
Method get_bipartite_start_id()
Get the bipartite start id (the node id where the second node type starts).
Usage
InfomapClass$get_bipartite_start_id()
Method set_bipartite_start_id()
Set the bipartite start id.
Usage
InfomapClass$set_bipartite_start_id(start_id)
Arguments
start_id-
Integer node id where the second node type starts.
Method print()
Print a short summary.
Usage
Arguments
Method add_igraph()
Import an igraph graph.
Usage
InfomapClass$add_igraph(
g,
weight = "weight",
phys_id = "phys_id",
layer_id = "layer_id",
multilayer_inter_intra_format = TRUE
)
Arguments
g-
An igraph graph.
weight-
Edge attribute to use as link weight. Use NULL to use
"weight" when present, or FALSE to ignore edge weights.
phys_id-
Vertex attribute holding physical node ids
(state-node case).
layer_id-
Vertex attribute holding layer ids
(multilayer case).
multilayer_inter_intra_format-
If TRUE, intra/inter
format is used; diagonal links (different layer AND different
physical node) trigger an error. Set to FALSE to allow
add_multilayer_link() for arbitrary (layer, node) pairs.
Details
Translated from interfaces/python/src/infomap/_networkx.py.
Node id convention. Infomap result accessors report the numeric
node ids used to build the network. For links added directly with
add_link() or add_links(), those user-supplied ids are preserved.
add_igraph() uses R igraph's 1-indexed vertex ids as state ids.
Plain graph results therefore use those ids directly. State and
multilayer graphs may use separate physical ids from phys_id; if
those ids are labels, they are mapped to stable internal integers and
returned as attr(mapping, "phys_id"). If the original igraph had
vertex names (V(g)$name), the returned mapping recovers them.
If the graph is directed, run() will inject --directed
unless the user has already chosen a flow model via opts or
raw args.
Returns
Invisibly returns a named character vector mapping igraph
vertex ids to the original igraph vertex names (or stringified
vertex ids when V(g)$name is absent). For state or multilayer
networks with non-numeric phys_id labels, the returned vector has
a "phys_id" attribute mapping internal physical ids to original
labels. Useful for joining Infomap results back to the original graph.
Method as_communities()
Convert the Infomap partition to an igraph
communities object (from igraph::make_clusters()),
compatible with modularity(), membership(), plot().
Usage
InfomapClass$as_communities(g)
Arguments
g-
The same igraph graph passed to add_igraph().
Method get_modules()
Get module assignment per leaf node.
Usage
InfomapClass$get_modules(depth_level = 1L, states = FALSE)
Arguments
depth_level-
Tree depth used for the module id. 1 gives
top-level modules, -1 the bottom level.
states-
If TRUE, return one entry per state node (for
higher-order networks); otherwise one per physical node.
Returns
A named integer vector mapping node id (or state id) to
module id.
Method get_multilevel_modules()
Get the full module path for each leaf node.
Usage
InfomapClass$get_multilevel_modules(states = FALSE)
Arguments
states-
If TRUE, use state ids for higher-order networks.
Returns
A named list mapping node id (or state id) to an integer
vector of module ids per level.
Method get_nodes()
Get per-leaf-node attributes (state id, physical id,
module id, flow, optional layer id).
Usage
InfomapClass$get_nodes(depth_level = 1L, states = FALSE)
Arguments
depth_level-
Tree depth used for the module id.
states-
If TRUE, return one row per state node.
Returns
A list of integer/numeric vectors.
Method get_links()
Get per-link weights and flow.
Usage
Details
For ordinary networks added with add_link() or add_links(),
source and target are the user-supplied node ids. For state
and multilayer networks they are state ids. Before run(),
weight reflects the input weights and flow reflects the core
link-flow values currently stored by Infomap, usually zero.
Returns
A data.frame with columns source, target, weight,
and flow.
Method get_name()
Look up a node's name.
Usage
InfomapClass$get_name(node_id, default = NULL)
Arguments
node_id-
Integer node id.
default-
Value returned when the node has no name.
Returns
Character (or default).
Method get_names()
Get all assigned node names.
Usage
Returns
A named character vector mapping node id to name.
Method write_clu()
Write the partition as a .clu file.
Usage
InfomapClass$write_clu(filename, states = FALSE, depth_level = 1L)
Arguments
filename-
Output path.
states-
Whether to write state ids (default FALSE).
depth_level-
Tree depth used for the module id.
Method write_tree()
Write the partition as a .tree file.
Usage
InfomapClass$write_tree(filename, states = FALSE)
Arguments
filename-
Output path.
states-
Whether to include state ids.
Method write_flow_tree()
Write the partition as a .ftree (flow-tree) file.
Usage
InfomapClass$write_flow_tree(filename, states = FALSE)
Arguments
filename-
Output path.
states-
Whether to include state ids.
Method write_newick()
Write the partition as a Newick .nwk file.
Usage
InfomapClass$write_newick(filename, states = FALSE)
Arguments
filename-
Output path.
states-
Whether to include state ids.
Method write_json()
Write the partition as a JSON file.
Usage
InfomapClass$write_json(filename, states = FALSE)
Arguments
filename-
Output path.
states-
Whether to include state ids.
Method write_csv()
Write the partition as a CSV file.
Usage
InfomapClass$write_csv(filename, states = FALSE)
Arguments
filename-
Output path.
states-
Whether to include state ids.
Method write_pajek()
Write the input network in Pajek .net format.
Usage
InfomapClass$write_pajek(filename, flow = FALSE)
Arguments
filename-
Output path.
flow-
Whether to write computed flow values per link.
Method write_state_network()
Write the state network.
Usage
InfomapClass$write_state_network(filename)
Arguments
Method write()
Dispatch on file extension to the appropriate
writer (.tree, .ftree, .nwk, .clu, .json, .csv,
.net).
Usage
InfomapClass$write(filename, ...)
Arguments
filename-
Output path. Extension chooses the writer.
...-
Forwarded to the chosen writer.
Examples
# Two triangles joined by a bridge.
im <- Infomap(silent = TRUE, num_trials = 5)
im$add_links(list(c(1, 2), c(1, 3), c(2, 3),
c(3, 4),
c(4, 5), c(4, 6), c(5, 6)))
im$run()
im$num_top_modules
im$codelength
im$modules
im <- Infomap(silent = TRUE, num_trials = 5)
im$add_links(list(c(1, 2), c(1, 3), c(2, 3),
c(3, 4),
c(4, 5), c(4, 6), c(5, 6)))
im$run()
im$num_top_modules
im$codelength
im$modules