Metadata-Version: 2.3
Name: lanet-vi
Version: 5.1.0
Summary: Large scale network visualization using k-core, k-dense, and d-core decomposition with community detection
Keywords: network,visualization,k-core,k-dense,graph-analysis
Author: Esteban Carisimo, Mariano Beiró, J. Ignacio Alvarez-Hamelin
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: networkx>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: polars>=0.20
Requires-Dist: pydantic>=2.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: requests>=2.31
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: pre-commit>=4.0 ; extra == 'dev'
Requires-Dist: ipython>=8.0 ; extra == 'dev'
Requires-Dist: jupyter>=1.0 ; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0 ; extra == 'dev'
Requires-Dist: types-requests>=2.31 ; extra == 'dev'
Requires-Dist: plotly>=5.0 ; extra == 'interactive'
Requires-Dist: ipywidgets>=8.0 ; extra == 'interactive'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/conexdat/LaNet-vi
Project-URL: Repository, https://github.com/conexdat/LaNet-vi.git
Project-URL: Documentation, https://github.com/conexdat/LaNet-vi/tree/main/docs
Project-URL: Issues, https://github.com/conexdat/LaNet-vi/issues
Provides-Extra: dev
Provides-Extra: interactive
Description-Content-Type: text/markdown

# 🧅 LaNet-vi

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/lanet-vi)](https://pypi.org/project/lanet-vi/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/CoNexDat/LaNet-vi/actions/workflows/ci.yml/badge.svg)](https://github.com/CoNexDat/LaNet-vi/actions/workflows/ci.yml)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

**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 →](docs/concepts.md)**

## ✨ 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

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

# Or with pip
pip install lanet-vi
```

## 🚀 Quick Start

### Command Line

```bash
# 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

```python
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

```python
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](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

<p align="center">
  <img src="examples/outputs/caida_as_relationships_kcores.png" width="45%" alt="K-cores decomposition">
  <img src="examples/outputs/caida_as_relationships_kdenses.png" width="45%" alt="K-denses decomposition">
  <br>
  <em>CAIDA AS-Relationships Network, 20251001 snapshot (78,370 nodes): K-cores (left) vs K-denses (right)</em>
</p>

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](docs/usage.md#using-lanet-vi-via-command-line)

## 🔧 Configuration

Generate a template:

```bash
lanet-vi config my_config.yaml
```

Example configuration:

```yaml
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:

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

## 📖 Documentation

- **[K-Core Concepts](docs/concepts.md)** - Understanding k-core decomposition
- **[Visualization Guide](docs/visualization.md)** - How the plots work (colors, sizing, layout)
- **[Usage Guide](docs/usage.md)** - Detailed Python API and CLI examples
- **[Examples](examples/)** - Working examples with real datasets

## 🔬 Advanced Features

### Community Detection

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

### Random Graph Generation

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

### D-Cores (Directed Networks)

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

## ⚡ Performance Tips

**Large networks (>100K nodes):**

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

**Publication quality:**

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

## 🛠️ Development

```bash
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](CONTRIBUTING.md) for the
full workflow, coding conventions and release process, and [SECURITY.md](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`](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](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)
