🧅 LaNet-vi

Large-scale network visualization using k-core decomposition

LaNet-vi is a Python package for visualizing large-scale networks through hierarchical decomposition algorithms. It reveals network structure by identifying the k-core hierarchy - from peripheral nodes to densely connected cores.

🧅 What is K-Core Decomposition?

K-core decomposition identifies hierarchical layers in networks where each k-core is a maximal subgraph with all nodes having at least k neighbors. This creates an "onion-like" structure revealing:

• Core nodes (high k): Densely connected, central, resilient
• Peripheral nodes (low k): Loosely connected, on the edges
• Intermediate layers: Transitional connectivity

Perfect for analyzing social networks, internet topology, biological networks, and collaboration graphs.

📖 Learn more about k-core concepts →

✨ Features

• 🧅 K-core, k-dense, and d-core decomposition algorithms
• 🎯 Circular hierarchical layout with smooth rings and gradient edge coloring
• ⚡ High-performance rendering for networks with millions of nodes
• 📂 Flexible I/O supporting compressed formats (gzip, bz2)
• 🕸️ Community detection with Louvain and modularity algorithms
• 🐍 Python API and CLI with full configurability
• 📊 Publication-ready visualizations with auto-scaling legends

📦 Installation

# Using uv (recommended)
uv pip install lanet-vi

# Or with pip
pip install lanet-vi

🚀 Quick Start

Command Line

# Visualize a network
lanet-vi visualize --input network.txt --output viz.png

# With custom settings
lanet-vi visualize --input network.txt \
  --width 2400 --height 2400 \
  --background black \
  --output viz.png

# Generate configuration template
lanet-vi config my_config.yaml

Python API

import networkx as nx
from lanet_vi import Network, LaNetConfig, DecompositionType

# Load network
G = nx.karate_club_graph()

# Decompose and visualize
config = LaNetConfig()
net = Network(G, config)
net.decompose(DecompositionType.KCORES)
net.visualize("output.png")

🌐 Example: Internet Topology

from lanet_vi.io.readers import read_caida_snapshot
from lanet_vi import Network, LaNetConfig

# Download and visualize CAIDA AS-relationships data
graph, _ = read_caida_snapshot(
    "https://publicdata.caida.org/datasets/as-relationships/serial-1/20251001.as-rel.txt.bz2"
)

config = LaNetConfig()  # Uses optimized defaults
net = Network(graph, config)
net.decompose()
net.visualize("internet_topology.png")

See example output: examples/outputs/caida_as_relationships_kcores.png

The visualization reveals the Internet's hierarchical structure with Tier-1 providers in the center and stub networks at the periphery.

🖼️ Example Visualizations

CAIDA AS-Relationships Network, 20251001 snapshot (78,370 nodes): K-cores (left) vs K-denses (right)

The visualizations reveal the hierarchical structure of the Internet, with densely connected core networks (red/orange) at the center and peripheral networks (blue/purple) at the edges. K-cores use degree-based decomposition while k-denses use triangle-based decomposition, highlighting different structural properties.

📄 Input Format

Edge list (space or tab separated):

# Comments start with #
0 1
1 2
2 0

Weighted networks:

0 1 2.5
1 2 3.0

Supports .txt, .txt.gz, .txt.bz2 formats.

⚙️ Common Options

Decomposition:

• --decomp [kcores|kdenses|dcores]: Decomposition algorithm (default: kcores)
• --weighted: Graph has edge weights (strength-based k-cores; see --granularity, --strength-intervals, --maximum-strength)
• --directed: Graph is directed (required for dcores)

Visualization:

• --width, --height: Image dimensions (default: 2400x2400)
• --background [black|white]: Background color (default: black)
• --epsilon FLOAT: Ring thickness as a fraction of its radius (default: 0.18)
• --edges-percent FLOAT: Percentage of edges to show (default: 0.5)
• --opacity FLOAT: Edge opacity (default: 0.2)

Output:

• --output PATH: Visualization file (PNG, PDF, SVG)
• --cores-file PATH: Export decomposition data (CSV or JSON)

Full CLI reference: See docs/usage.md

🔧 Configuration

Generate a template:

lanet-vi config my_config.yaml

Example configuration:

visualization:
  background: black
  width: 2400
  height: 2400
  epsilon: 0.18
  edges_percent: 0.5
  opacity: 0.2

layout:
  seed: 0

decomposition:
  decomp_type: kcores

Use it:

lanet-vi visualize --input network.txt --config my_config.yaml

📖 Documentation

• K-Core Concepts - Understanding k-core decomposition
• Visualization Guide - How the plots work (colors, sizing, layout)
• Usage Guide - Detailed Python API and CLI examples
• Examples - Working examples with real datasets

🔬 Advanced Features

Community Detection

lanet-vi visualize --input network.txt \
  --detect-communities \
  --draw-community-boundaries \
  --output communities.png

Random Graph Generation

lanet-vi generate --output test.txt \
  --model barabasi-albert \
  --nodes 1000 --edges 3

D-Cores (Directed Networks)

lanet-vi visualize --input citations.txt \
  --directed --decomp dcores \
  --output dcores.png

⚡ Performance Tips

Large networks (>100K nodes):

config.visualization.edges_percent = 0.1  # Show 10% of edges
config.visualization.opacity = 0.2
config.visualization.node_size_scale = 0.4

Publication quality:

config.visualization.width = 3600
config.visualization.height = 3600
config.visualization.background = "white"

🛠️ Development

git clone https://github.com/CoNexDat/LaNet-vi.git
cd LaNet-vi
uv sync --all-extras
uv run pre-commit install
uv run pytest

Contributing

Contributions are welcome. main is protected: open a pull request and iterate until CI and the automatic Copilot review are green. See CONTRIBUTING.md for the full workflow, coding conventions and release process, and SECURITY.md for reporting vulnerabilities.

Citation

If you use LaNet-vi in your research, please cite the software (GitHub's Cite this repository button uses CITATION.cff) and the papers behind the method:

• Alvarez-Hamelin, J.I., Dall'Asta, L., Barrat, A., Vespignani, A. (2006). "Large scale networks fingerprinting and visualization using the k-core decomposition". Advances in Neural Information Processing Systems 18.

• Beiró, M.G., Alvarez-Hamelin, J.I., Busch, J.R. (2008). "A low complexity visualization tool that helps to perform complex systems analysis". New Journal of Physics.

🏛️ Heritage

LaNet-vi 5.x is a from-scratch Python rewrite of the original LaNet-vi (Large Network visualization tool), a C++ program developed since 2005 by Mariano G. Beiró and J. Ignacio Alvarez-Hamelin (Universidad de Buenos Aires / CONICET) together with Alain Barrat, Luca Dall'Asta and Alessandro Vespignani. The C++ tool introduced the concentric k-core layout this package is built on and produced, among others, the Internet AS-level maps that made the method known.

• Original releases (1.x to 3.0.1, last one in January 2016) are published on SourceForge: https://sourceforge.net/projects/lanet-vi/ under the Academic Free License 3.0.
• Original project homepage: http://lanet-vi.fi.uba.ar/.
• The C++ sources are not part of this repository or of the PyPI package; they remain available at the links above.

License

The Python implementation is released under the MIT License, with the original authors of the C++ version as co-holders of the copyright. The original C++ LaNet-vi remains available under the Academic Free License 3.0 on SourceForge.

Authors

• Esteban Carisimo (Python implementation)
• Mariano G. Beiró (original C++ version)
• J. Ignacio Alvarez-Hamelin (original C++ version)