Integrations¶

Scanpy / AnnData¶

infomap.tl.infomap(adata: Any, *, adjacency: Any = None, directed: bool = False, use_weights: bool = True, key_added: str = 'infomap', neighbors_key: str | None = None, obsp: str | None = None, copy: bool = False, args: str | None = None, **infomap_options: Any) → Any¶

Run Infomap on an AnnData observation graph.

This function follows Scanpy tl conventions: by default it reads adata.obsp["connectivities"], writes categorical module labels to adata.obs[key_added], and stores run metadata in adata.uns[key_added]. Scanpy itself is not imported.

Parameters:

adata (AnnData) – An AnnData-like object with .obs, .obsp, .uns, and .obs_names.
adjacency (sparse matrix, optional) – Square observation-by-observation adjacency matrix to use instead of reading one from adata.obsp. Mutually exclusive with neighbors_key and obsp.
directed (bool, optional) – Treat the adjacency as directed. Default False.
use_weights (bool, optional) – Use the adjacency values as link weights. If False, every nonzero entry is treated as weight 1. Default True.
key_added (str, optional) – Key under which module labels are written to adata.obs and run metadata to adata.uns. Default "infomap".
neighbors_key (str, optional) – Read the adjacency from the obsp key named by adata.uns[neighbors_key]["connectivities_key"]. Mutually exclusive with adjacency and obsp.
obsp (str, optional) – Read the adjacency from adata.obsp[obsp]. Default "connectivities". Mutually exclusive with adjacency and neighbors_key.
copy (bool, optional) – Operate on (and return) a copy of adata instead of modifying it in place. Default False.
args (str, optional) – Raw Infomap CLI arguments passed to Infomap.
**infomap_options – Keyword arguments passed to Infomap. By default, silent=True and no_file_output=True are used unless explicitly overridden.

Returns:

The annotated copy when copy=True, otherwise None and adata is modified in place. In both cases, adata.obs[key_added] holds the module labels as a categorical (string categories sorted by integer value) and adata.uns[key_added] holds a dict with the run params, the number of top modules n_modules, and the codelength.

Return type:

AnnData or None

GraphRAG¶

infomap.tl.graphrag.read_graphrag(entities, relationships, *, entity_id_col='id', entity_title_col='title', source_col='source', target_col='target', weight_col='weight', relationship_id_col='id', endpoint_col='title') → GraphRAGGraph¶

Read GraphRAG-style entity and relationship Parquet tables.

Assigns a 1-based Infomap node id to every entity (and to any relationship endpoint that does not appear in the entity table) and converts the relationships to source/target/weight arrays ready for infomap.Infomap.add_links().

Parameters:

entities (str, pathlib.Path, or pandas.DataFrame) – Entity table, or a path to a Parquet file containing it.
relationships (str, pathlib.Path, or pandas.DataFrame) – Relationship table, or a path to a Parquet file containing it.
entity_id_col (str, optional) – Entity table column with unique entity ids. Default "id".
entity_title_col (str, optional) – Entity table column with entity titles. Default "title".
source_col (str, optional) – Relationship table column with source endpoints. Default "source".
target_col (str, optional) – Relationship table column with target endpoints. Default "target".
weight_col (str or None, optional) – Relationship table column with link weights, or None for unweighted links. Default "weight".
relationship_id_col (str or None, optional) – Relationship table column with relationship ids. If missing or None, positional indices are used. Default "id".
endpoint_col (str, optional) – Which entity column the relationship endpoints reference: "title" (default, requires unique titles) or "id".

Returns:

The tables together with the link arrays and the mappings between Infomap node ids and entity ids/titles.

Return type:

GraphRAGGraph

infomap.tl.graphrag.run_graphrag_communities(*, input_dir, output_dir=None, args=None, entities_name='entities.parquet', relationships_name='relationships.parquet', entity_id_col='id', entity_title_col='title', source_col='source', target_col='target', weight_col='weight', relationship_id_col='id', endpoint_col='title', silent=True, seed=123, num_trials=5, **infomap_options) → GraphRAGRunResult¶

Read GraphRAG tables, run Infomap, and write community outputs.

End-to-end convenience wrapper around read_graphrag(), an Infomap run, and write_graphrag_communities().

Parameters:

input_dir (str or pathlib.Path) – Directory containing the entity and relationship Parquet files.
output_dir (str or pathlib.Path, optional) – Where to write infomap_nodes.parquet, communities.parquet, and the run summary infomap_run.json. If None, nothing is written and only the in-memory result is returned.
args (str, optional) – Raw Infomap CLI arguments passed to Infomap.
entities_name (str, optional) – Entity file name inside input_dir. Default "entities.parquet".
relationships_name (str, optional) – Relationship file name inside input_dir. Default "relationships.parquet".
entity_id_col (str, optional) – Column names passed to read_graphrag().
entity_title_col (str, optional) – Column names passed to read_graphrag().
source_col (str, optional) – Column names passed to read_graphrag().
target_col (str, optional) – Column names passed to read_graphrag().
weight_col (str, optional) – Column names passed to read_graphrag(); see there for details.
relationship_id_col (str, optional) – Column names passed to read_graphrag(); see there for details.
endpoint_col (str, optional) – Column names passed to read_graphrag(); see there for details.
silent (bool, optional) – Suppress Infomap console output. Default True.
seed (int, optional) – Random number generator seed. Default 123.
num_trials (int, optional) – Number of independent trials; the best solution is kept. Default 5.
**infomap_options – Additional keyword arguments passed to Infomap.

Returns:

The Infomap instance, the parsed graph, the output directory, and the nodes/communities tables.

Return type:

GraphRAGRunResult

Raises:

TypeError – If options= is passed; use args= for raw CLI arguments.
ValueError – If summary_json is passed; it is managed through output_dir.

infomap.tl.graphrag.write_graphrag_communities(im, *, graph: GraphRAGGraph, output)¶

Write GraphRAG-compatible community tables from a finished run.

Parameters:

im (Infomap) – An Infomap instance that has been run on the links of graph.
graph (GraphRAGGraph) – The graph returned by read_graphrag() for the same network.
output (str or pathlib.Path) – Output directory, or a .parquet path for the communities table (its parent directory is then used for the nodes table). Writes infomap_nodes.parquet and communities.parquet.

Returns:

The (nodes, communities) tables that were written.

Return type:

tuple of (pandas.DataFrame, pandas.DataFrame)

Raises:

ValueError – If output is None.

class infomap.tl.graphrag.GraphRAGGraph(entities: Any, relationships: Any, sources: Any, targets: Any, weights: Any | None, entity_id_to_node_id: dict[Any, int], node_id_to_entity_id: dict[int, Any], node_id_to_entity_title: dict[int, Any], endpoint_to_node_id: dict[Any, int], entity_title_to_node_id: dict[Any, int], relationship_ids: list[Any], entity_id_col: str)¶

GraphRAG-style tables converted to Infomap node ids.

The mapping fields are advanced plumbing for callers that need to join Infomap node ids back to the original GraphRAG entity and relationship tables.

class infomap.tl.graphrag.GraphRAGRunResult(infomap: Any, graph: GraphRAGGraph, output_dir: Path | None, nodes: Any, communities: Any)¶: Result object returned by run_graphrag_communities().

Distributed trials¶

infomap.merge.merge_trial_results(patterns: Sequence[str], out_name: str, formats: Sequence[str] = ('tree', 'clu'), require_complete: bool = False) → MergeSummary¶

Merge distributed Infomap trial-results shards into final output.

Parameters:

patterns (sequence of str) – Shard result file paths or glob patterns (each may be comma-separated).
out_name (str) – Output basename; <out_name>.tree / <out_name>.clu are written.
formats (sequence of str, optional) – Which output formats to write. Only tree and clu are supported (the merge has no network, so link-bearing formats cannot be produced).
require_complete (bool, optional) – If True, raise when any global trial index in [0, max] is missing. Default False.

Returns:

Summary with the winning trial index, codelength, the resolved winner tree path, the number of shards/trials, any missing indices, and the list of outputs written.

Return type:

MergeSummary

class infomap.merge.MergeSummary¶

Summary returned by merge_trial_results().

codelength: float¶: Codelength of the winning trial.

missing: List[int]¶: Global trial indices missing from [0, max_index], if any.

num_shards: int¶: Number of shard result files merged.

num_trials: int¶: Number of distinct global trial indices covered by the shards.

outputs: List[str]¶: Paths of the output files written.

trial: int¶: Global index of the winning trial (lowest codelength, ties broken by lowest index).

winner_tree: str¶: Resolved path to the winning trial’s .tree file.

exception infomap.merge.MergeError¶: Raised when shard files are missing, inconsistent, or unmergeable.