Igraph

---
name: igraph
description: >-
  Network/graph analysis with python-igraph: graph construction from edge-list DataFrames (Polars round-trip), centrality (degree, betweenness, closeness, eigenvector, PageRank), community detection (Leiden, Louvain, walktrap) with seed discipline, paths/components, bipartite construction and projection, static visualization (matplotlib backend). Use for relational data — collaboration, friendship, organizational, or co-occurrence networks. For geographic road-network routing use geopandas (OSMnx); for non-graph clustering use scikit-learn. R equivalent: igraph-r (use when execution language is R).
metadata:
  audience: research-coders
  domain: python-library
  library-version: "1.0.0 (python-igraph)"
  skill-last-updated: "2026-07-15"
---

# igraph Skill

python-igraph network analysis library for Python: constructing, analyzing, and visualizing graphs and networks. Covers graph construction from edge-list DataFrames with Polars round-trips, centrality measures (degree, betweenness, closeness, eigenvector, PageRank), community detection (Leiden, Louvain, walktrap) with mandatory seed discipline, shortest paths and connected components, bipartite graph construction and one-mode projection, node/edge attribute interop with tidy tables for downstream statistics, and static visualization via the matplotlib backend. Use when working with relational data — collaboration networks, friendship/social ties, organizational hierarchies, co-occurrence or co-authorship structures. For geographic road-network routing, use geopandas (OSMnx). For non-graph clustering or dimensionality reduction, use scikit-learn. ERGM and statistical/generative network models are out of scope (see Version Notes).

Comprehensive skill for network analysis with python-igraph. Use the decision trees below to find the right guidance, then load detailed reference files as needed.

## Version Notes

This skill targets **python-igraph 1.0.0** (released 2025-10-23).

- **Package vs. import name:** the PyPI package is `igraph` (`pip install igraph`), imported as `import igraph`. Historically the package was distributed as `python-igraph`; that name is now an alias. Do not confuse it with the unrelated `igraph` typo-squat or with `jgraph`.
- **Installation in DAAF:** `igraph==1.0.0` is pinned in the Dockerfile framework install block and is **pre-installed in the current image** (import verified against the live container 2026-07-16) — no installation needed. Runtime installs are blocked in DAAF (see CLAUDE.md § Runtime Package Installation); for any related extra, escalate to the user for a Dockerfile addition (user additions block) and rebuild.
- **Shared C core with R:** python-igraph and the R `igraph` package wrap the *same* C library, so algorithms and coded-value semantics match across the language pair. This is why the DAAF pair is `igraph` (Python) ↔ `igraph-r` (R) rather than pairing two unrelated engines — it eliminates cross-language semantic drift.
- **Plotting backend:** this skill uses the **matplotlib backend** (`igraph.plot(g, target=ax)`), which is already in the container. The default Cairo backend (`cairocffi`) is deliberately **not** installed — do not call plotting code paths that require it.
- **NetworkX relationship:** NetworkX is the documentation and teaching touchstone of the Python network-analysis ecosystem (broadest docs, near-universal course adoption) but is substantially slower at research scale. This skill uses python-igraph, not NetworkX; NetworkX is mentioned only as the ecosystem reference point.
- **Out of scope — deferred:** ERGM and other statistical/generative network models (exponential random graph models, stochastic block model *inference*, TERGM) are a distinct inferential method family with MCMC cost and model-degeneracy hazards. They are a **deferred future extension**, not part of this skill.

## What is python-igraph?

python-igraph provides a graph data structure and a large library of graph algorithms:

- **Graph object:** a `Graph` holds vertices (nodes) and edges, each optionally carrying named attributes. Directedness is a property of the whole graph (`directed=True/False`), set at construction.
- **Edge-list construction:** graphs are most naturally built from an edge list — a two-column table of (source, target) pairs — which maps cleanly to a Polars DataFrame. Vertex and edge attributes ride alongside as additional columns.
- **Algorithm coverage:** centrality (degree, betweenness, closeness, eigenvector, PageRank), community detection (Leiden, Louvain/multilevel, walktrap), shortest paths, connected components, and bipartite projection.
- **Attribute interop:** vertex/edge attributes round-trip to tidy tables, so graph-derived measures (e.g., per-node centrality) flow back into Polars for downstream regression or joins.
- **Static visualization:** `igraph.plot()` renders onto a matplotlib `Axes` with a chosen layout; force-directed layouts require a seed for reproducible figures.

## How to Use This Skill

### Reference File Structure

| File | Purpose | When to Read |
|------|---------|--------------|
| `quickstart.md` | Graph construction, edge-list ↔ Polars round-trip, I/O, inspection | Starting with igraph |
| `centrality.md` | Degree, betweenness, closeness, eigenvector, PageRank; directed modes; connectivity guardrail | Computing node importance |
| `community-detection.md` | Leiden, Louvain, walktrap; seed discipline; directed-graph handling | Finding clusters/communities |
| `paths-components.md` | Shortest paths, distances, diameter, connected components, reachability | Path and connectivity analysis |
| `bipartite.md` | Bipartite construction from two-column tables, one-mode projection | Two-mode (affiliation) networks |
| `visualization.md` | matplotlib-backend plotting, seeded layouts, styling | Making network figures |
| `dataframe-interop.md` | Node/edge attributes ↔ tidy tables for downstream stats | Moving results in/out of Polars |
| `gotchas.md` | Directed/weighted traps, seed omissions, disconnected-graph pitfalls | Debugging or reviewing |

### Reading Order

1. **New to igraph?** Start with `quickstart.md`, then `centrality.md`.
2. **Detecting communities?** Read `community-detection.md` (seed discipline is mandatory).
3. **Making figures?** Read `visualization.md` (relies on `quickstart.md` for construction).
4. **Feeding results into analysis?** Read `dataframe-interop.md`.
5. **Having issues?** Check `gotchas.md` first.

**The reference-file routing in this skill applies to advisory and brainstorming turns as much as implementation.** Recommending an approach, reviewing a plan, or answering a question that touches a routed topic calls for reading the routed reference file just as much as writing code does — the reference files carry curated caveats (directed-vs-undirected semantics, weight interpretation, seed discipline) that this overview and general knowledge lack.

## Related Skills

| Skill | Relationship |
|-------|-------------|
| **polars** | Edge lists, node/edge attribute tables, and graph-derived measures live in Polars DataFrames. Use polars for all tabular transformation before building a graph and after extracting results. |
| **data-scientist** | Methodology routing — when a network representation is appropriate, how to interpret centrality/community results, and the pitfalls (betweenness ≠ resilience; centrality ill-defined across components). Load alongside for research workflows. |
| **scikit-learn** | For clustering/dimensionality reduction on feature matrices *without* graph structure (k-means, PCA, UMAP), use scikit-learn — not community detection. |
| **geopandas** | For geographic road-network routing (OSMnx) and spatial contiguity graphs, use geopandas — not igraph. |
| **plotnine / plotly** | For non-network figures of graph-derived measures (centrality distributions, degree histograms), use plotnine or plotly. |

**Routing guidance:** igraph is for *relational* structure — entities connected by ties. If the data is a feature matrix and the goal is clustering by similarity, that is scikit-learn, not igraph. If the "network" is a road or spatial-adjacency graph tied to geography, that is geopandas (OSMnx). Community detection here means graph-topology community detection (Leiden/Louvain), not feature-space clustering.

## Quick Decision Trees

### "I need to build or inspect a graph"

```
Constructing / inspecting a graph?
├─ From a Polars edge-list DataFrame → ./references/quickstart.md
├─ With node and edge attributes → ./references/quickstart.md
├─ Directed vs. undirected choice → ./references/quickstart.md
├─ Read/write graph file (GraphML, edgelist) → ./references/quickstart.md
├─ Inspect vcount / ecount / degree summary → ./references/quickstart.md
└─ Convert directed → undirected → ./references/quickstart.md
```

### "I need to measure node importance (centrality)"

```
Centrality?
├─ Degree (in / out / all) → ./references/centrality.md
├─ Betweenness → ./references/centrality.md
├─ Closeness → ./references/centrality.md
├─ Eigenvector centrality → ./references/centrality.md
├─ PageRank → ./references/centrality.md
├─ Weighted centrality (explicit weights=) → ./references/centrality.md
└─ Check connectivity BEFORE closeness/betweenness → ./references/centrality.md
```

### "I need to find communities or clusters"

```
Community detection?
├─ Leiden → ./references/community-detection.md
├─ Louvain (multilevel) → ./references/community-detection.md
├─ Walktrap → ./references/community-detection.md
├─ Set a seed for reproducibility → ./references/community-detection.md
├─ Directed graph (convert to undirected) → ./references/community-detection.md
└─ Weighted community detection → ./references/community-detection.md
```

### "I need paths, distances, or components"

```
Paths / connectivity?
├─ Shortest path between two nodes → ./references/paths-components.md
├─ All-pairs distances → ./references/paths-components.md
├─ Diameter → ./references/paths-components.md
├─ Connected components (weak / strong) → ./references/paths-components.md
├─ Largest connected component (giant) → ./references/paths-components.md
└─ Reachability check → ./references/paths-components.md
```

### "I have a two-mode (bipartite) network"

```
Bipartite / affiliation network?
├─ Build bipartite graph from two-column table → ./references/bipartite.md
├─ Project to one mode → ./references/bipartite.md
├─ Weighted projection (shared-affiliation counts) → ./references/bipartite.md
└─ Verify bipartite structure → ./references/bipartite.md
```

### "I need to make a figure or move results into analysis"

```
Visualization / interop?
├─ Plot the network (matplotlib backend) → ./references/visualization.md
├─ Seeded reproducible layout → ./references/visualization.md
├─ Style by attribute (color/size) → ./references/visualization.md
├─ Extract per-node measures to a Polars frame → ./references/dataframe-interop.md
├─ Attach a Polars column as a node attribute → ./references/dataframe-interop.md
└─ Export edge list back to Polars → ./references/dataframe-interop.md
```

### "Something isn't working"

```
Having issues?
├─ Community detection errors on a directed graph → ./references/gotchas.md
├─ Non-reproducible layout or community results → ./references/gotchas.md
├─ Closeness/betweenness returns inf or nan → ./references/gotchas.md
├─ Weighted result looks backwards → ./references/gotchas.md
├─ Vertex names vs. indices confusion → ./references/gotchas.md
└─ General troubleshooting → ./references/gotchas.md
```

## File-First Execution in Research Workflows

**Important:** In data research pipelines (see `CLAUDE.md`), graph operations are executed through **script files**, not interactively. This ensures auditability and reproducibility.

**The pattern:**
1. Write graph analysis code to `scripts/stage{N}_{type}/{step}_{task-name}.py`
2. Execute via Bash with the automatic output-capture wrapper script
3. Validation results get embedded in scripts as comments
4. If failed, create a versioned copy for fixes

Closely read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the mandatory file-first execution protocol covering complete code-file writing, output capture, and file-versioning rules.

**See:**
- `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` — Script execution protocol and format with validation

The examples in reference files show igraph syntax. In research workflows, wrap them in scripts following the file-first pattern. Every stochastic example (community detection, force-directed layout) is preceded by `random.seed()` — preserve that discipline when adapting examples.

---

## Quick Reference

### Essential Imports

```python
import igraph as ig
import polars as pl
import random  # seed BEFORE any stochastic layout or community detection
```

### Core Operations

| Operation | Code |
|-----------|------|
| Build from edge tuples | `g = ig.Graph(edges=edge_tuples, directed=False)` |
| Build from Polars edge list | `g = ig.Graph.DataFrame(edges_pdf, directed=False)` (via pandas bridge — see quickstart) |
| Node / edge counts | `g.vcount()`, `g.ecount()` |
| Degree (directed) | `g.degree(mode="in")` / `"out"` / `"all"` |
| Betweenness | `g.betweenness(weights=g.es["weight"])` |
| Closeness | `g.closeness(weights=g.es["weight"])` |
| Eigenvector | `g.eigenvector_centrality(weights=g.es["weight"])` |
| PageRank | `g.pagerank(weights=g.es["weight"])` |
| To undirected | `g_u = g.as_undirected()` |
| Louvain (undirected) | `random.seed(0); part = g_u.community_multilevel(weights=g_u.es["weight"])` |
| Leiden (undirected) | `random.seed(0); part = g_u.community_leiden(objective_function="modularity")` |
| Walktrap | `random.seed(0); part = g_u.community_walktrap().as_clustering()` |
| Connected components | `comp = g.connected_components(mode="weak")` |
| Giant component | `giant = g.connected_components().giant()` |
| Shortest path | `g.get_shortest_paths(src, to=dst, weights=g.es["weight"])` |
| Bipartite projection | `proj1, proj2 = g.bipartite_projection()` |
| Plot (matplotlib) | `ig.plot(g, target=ax, layout=g.layout("fr"))` |

> **Weights are distances, not strengths.** In path-based measures (betweenness, closeness, shortest paths), a higher `weight` means a *longer* path. If your weights encode connection *strength*, invert them before passing. Always pass `weights=` explicitly in weighted examples (see gotchas).

### Directed-Graph Mode Cheat Sheet

| `mode=` | Meaning |
|---------|---------|
| `"in"` | Incoming edges only (indegree) |
| `"out"` | Outgoing edges only (outdegree) |
| `"all"` | Both directions combined |

## Topic Index

| Topic | Reference File |
|-------|---------------|
| Graph construction from edge list | `./references/quickstart.md` |
| Edge-list ↔ Polars round-trip | `./references/quickstart.md` |
| Node / edge attributes | `./references/quickstart.md` |
| Directed vs. undirected | `./references/quickstart.md` |
| Graph I/O (GraphML, edgelist) | `./references/quickstart.md` |
| Graph inspection | `./references/quickstart.md` |
| Degree centrality | `./references/centrality.md` |
| Betweenness centrality | `./references/centrality.md` |
| Closeness centrality | `./references/centrality.md` |
| Eigenvector centrality | `./references/centrality.md` |
| PageRank | `./references/centrality.md` |
| Weighted centrality | `./references/centrality.md` |
| Connectivity check before centrality | `./references/centrality.md` |
| Leiden community detection | `./references/community-detection.md` |
| Louvain / multilevel | `./references/community-detection.md` |
| Walktrap | `./references/community-detection.md` |
| Modularity | `./references/community-detection.md` |
| Seed discipline | `./references/community-detection.md` |
| Directed-graph community handling | `./references/community-detection.md` |
| Shortest paths | `./references/paths-components.md` |
| Distances / diameter | `./references/paths-components.md` |
| Connected components | `./references/paths-components.md` |
| Giant component | `./references/paths-components.md` |
| Reachability | `./references/paths-components.md` |
| Bipartite construction | `./references/bipartite.md` |
| One-mode projection | `./references/bipartite.md` |
| Weighted projection | `./references/bipartite.md` |
| Network plotting (matplotlib) | `./references/visualization.md` |
| Seeded layouts | `./references/visualization.md` |
| Styling by attribute | `./references/visualization.md` |
| Attributes → Polars frame | `./references/dataframe-interop.md` |
| Polars column → node attribute | `./references/dataframe-interop.md` |
| Edge-list export | `./references/dataframe-interop.md` |
| Directed/weighted traps | `./references/gotchas.md` |
| Non-reproducible results | `./references/gotchas.md` |
| inf/nan centrality on disconnected graphs | `./references/gotchas.md` |
| Vertex names vs. indices | `./references/gotchas.md` |

## Citation

python-igraph carries formal software attribution. When igraph is used as a
primary analytical tool (any centrality, community-detection, path, or bipartite
analysis central to the results), include the following in the report's
**Software & Tools** references. python-igraph's own `CITATION.cff` names the
2006 Csárdi & Nepusz article as the preferred citation; cite the 2023
cross-language paper as supplemental.

**Preferred citation (required):**

> Csárdi, G., & Nepusz, T. (2006). The igraph software package for complex network research. *InterJournal, Complex Systems*, 1695. https://igraph.org

**Supplemental citation (recommended for cross-language / reproducibility work):**

> Antonov, M., Csárdi, G., Horvát, S., Müller, K., Nepusz, T., Noom, D., Salmon, M., Traag, V., Foucault Welles, B., & Zanini, F. (2023). igraph enables fast and robust network analysis across programming languages. *arXiv preprint* arXiv:2311.10260. https://doi.org/10.48550/arXiv.2311.10260

**BibTeX:**

```bibtex
@Article{igraph2006,
  title   = {The igraph software package for complex network research},
  author  = {G{\'a}bor Cs{\'a}rdi and Tam{\'a}s Nepusz},
  journal = {InterJournal},
  volume  = {Complex Systems},
  pages   = {1695},
  year    = {2006},
  url     = {https://igraph.org},
}

@Article{igraph2023,
  title   = {igraph enables fast and robust network analysis across programming languages},
  author  = {Michael Antonov and G{\'a}bor Cs{\'a}rdi and Szabolcs Horv{\'a}t and
             Kirill M{\"u}ller and Tam{\'a}s Nepusz and Daniel Noom and Ma{\"e}lle Salmon and
             Vincent Traag and Brooke Foucault Welles and Fabio Zanini},
  journal = {arXiv preprint arXiv:2311.10260},
  year    = {2023},
  doi     = {10.48550/arXiv.2311.10260},
}
```

**License:** python-igraph is distributed under **GPL-2.0-or-later** (from its
`CITATION.cff`). This is a copyleft license; acknowledge it in the report's
software attribution alongside the citation.

**Cite when:** igraph produces centrality, community structure, paths, or
bipartite projections that inform the analysis or appear in figures/tables.
**Do not cite when:** igraph is used only for a throwaway structural check with no
bearing on reported results.

Pipeline agents must propagate these citations into the report's Software & Tools
section per `agent_reference/CITATION_REFERENCE.md` — the igraph registry entry
there is the canonical source for pipeline citation propagation and verification.
For method-specific citations (e.g., the Leiden algorithm), consult
`community-detection.md` and `agent_reference/CITATION_REFERENCE.md`.