Command-Line Interface (CLI) Tutorial

Py3plex includes a comprehensive command-line interface that provides access to all main algorithms and functionality directly from the terminal. This is useful for quick analysis, scripting, and automation workflows.

Installation

The CLI tool is automatically available after installing py3plex:

pip install git+https://github.com/SkBlaz/py3plex.git

After installation, verify the CLI is available:

py3plex --help

Getting Help

The CLI includes built-in documentation for all commands:

# Main help with all commands
py3plex --help

# Help for specific command
py3plex create --help
py3plex community --help
py3plex centrality --help

Available Commands

The py3plex CLI provides 8 main commands:

create - Create new multilayer networks
load - Load and inspect networks
community - Detect communities
centrality - Compute centrality measures
stats - Compute multilayer network statistics
visualize - Create network visualizations
aggregate - Aggregate multilayer networks into single layer
convert - Convert between network formats

Creating Networks

Create Random Networks

Create a simple multilayer network with random edges:

py3plex create --nodes 100 --layers 3 --output network.graphml --seed 42

This creates a network with 100 nodes per layer and 3 layers, saving it to network.graphml.

Network Generation Models

Erdős-Rényi Random Graphs:

py3plex create --nodes 50 --layers 2 --type er --probability 0.15 \
    --output er_network.graphml --seed 42

Barabási-Albert Preferential Attachment:

py3plex create --nodes 100 --layers 3 --type ba --probability 0.05 \
    --output ba_network.graphml --seed 42

Watts-Strogatz Small-World:

py3plex create --nodes 50 --layers 2 --type ws --probability 0.2 \
    --output ws_network.graphml --seed 42

Output Formats

The CLI supports multiple output formats (automatically detected from file extension):

.graphml - GraphML format (XML-based, recommended)
.gexf - GEXF format (XML-based, for Gephi)
.gpickle - Python pickle format (binary, fastest)

Loading and Inspecting Networks

Basic Network Information

Display basic network statistics:

py3plex load network.graphml --info

Output:

Network Information:
  Nodes: 300
  Edges: 450
  Layers: 3 (layer1, layer2, layer3)
  Directed: False

Detailed Statistics

Get comprehensive statistics including layer densities and clustering:

py3plex load network.graphml --stats

Output:

Network Information:
  Nodes: 300
  Edges: 450
  Layers: 3 (layer1, layer2, layer3)
  Directed: False

Basic Statistics:
  Layer Densities:
    layer1: 0.0303
    layer2: 0.0298
    layer3: 0.0305
  Avg Clustering: 0.0421
  Avg Degree: 3.00
  Max Degree: 12

Save to JSON

Export network information to JSON for further processing:

py3plex load network.graphml --info --output network_info.json

Community Detection

Louvain Algorithm

Detect communities using the Louvain modularity optimization algorithm:

py3plex community network.graphml --algorithm louvain --output communities.json

Output:

Loading network from network.graphml...
Detecting communities using louvain...
Found 8 communities
Community sizes: min=15, max=52, avg=37.5
Communities saved to communities.json

With Custom Resolution

Adjust the resolution parameter to find more or fewer communities:

# Higher resolution = more communities
py3plex community network.graphml --algorithm louvain --resolution 1.5

# Lower resolution = fewer communities
py3plex community network.graphml --algorithm louvain --resolution 0.5

Label Propagation

Use label propagation for fast community detection:

py3plex community network.graphml --algorithm label_prop --output communities.json

Infomap (Optional)

If Infomap is installed, use it for overlapping community detection:

py3plex community network.graphml --algorithm infomap --output communities.json

Centrality Measures

Degree Centrality

Compute degree centrality and show top nodes:

py3plex centrality network.graphml --measure degree --top 10

Output:

Loading network from network.graphml...
Computing degree centrality...

Top 10 nodes by degree centrality:
  node42---layer1: 12.000000
  node18---layer2: 11.000000
  node77---layer1: 10.000000
  ...

Save Results

Export centrality scores to JSON:

py3plex centrality network.graphml --measure degree --output centrality.json

All Centrality Measures

Betweenness Centrality:

py3plex centrality network.graphml --measure betweenness --top 10

Closeness Centrality:

py3plex centrality network.graphml --measure closeness --top 10

Eigenvector Centrality:

py3plex centrality network.graphml --measure eigenvector --top 10

PageRank:

py3plex centrality network.graphml --measure pagerank --top 10

Multilayer Network Statistics

Comprehensive Statistics

Compute all available multilayer statistics:

py3plex stats network.graphml --measure all --output stats.json

Output includes:

Layer densities for each layer
Clustering coefficient
Node activity samples
Versatility centrality (top nodes)
Edge overlap between layers

Specific Statistics

Layer Density:

py3plex stats network.graphml --measure layer_density

Clustering Coefficient:

py3plex stats network.graphml --measure clustering

Node Activity:

py3plex stats network.graphml --measure node_activity

Versatility Centrality:

py3plex stats network.graphml --measure versatility

Edge Overlap:

py3plex stats network.graphml --measure edge_overlap

Network Visualization

Multilayer Layout

Create a visualization using the specialized multilayer layout:

py3plex visualize network.graphml --layout multilayer --output network.png

Standard Layouts

Use NetworkX layouts for different visual styles:

Spring Layout (Force-Directed):

py3plex visualize network.graphml --layout spring --output network_spring.png

Circular Layout:

py3plex visualize network.graphml --layout circular --output network_circular.png

Kamada-Kawai Layout:

py3plex visualize network.graphml --layout kamada_kawai --output network_kk.png

Custom Figure Size

Adjust the output image dimensions:

py3plex visualize network.graphml --layout spring --width 15 --height 10 \
    --output large_viz.png

Network Aggregation

Aggregate multiple layers into a single layer using different methods:

Sum Aggregation

Sum edge weights across layers:

py3plex aggregate network.graphml --method sum --output aggregated.graphml

Mean Aggregation

Average edge weights across layers:

py3plex aggregate network.graphml --method mean --output aggregated_mean.graphml

Other Aggregation Methods

max - Take maximum edge weight across layers
min - Take minimum edge weight across layers

Format Conversion

Convert Between Formats

Convert networks between different file formats:

To GEXF (for Gephi):

py3plex convert network.graphml --output network.gexf

To JSON:

py3plex convert network.graphml --output network.json

To gpickle (Python binary):

py3plex convert network.graphml --output network.gpickle

Complete Workflow Examples

Example 1: Create, Analyze, and Visualize

# Step 1: Create a Barabási-Albert network
py3plex create --nodes 100 --layers 3 --type ba --probability 0.05 \
    --output ba_network.graphml --seed 42

# Step 2: Detect communities
py3plex community ba_network.graphml --algorithm louvain \
    --output communities.json

# Step 3: Compute centrality
py3plex centrality ba_network.graphml --measure pagerank --top 20 \
    --output central_nodes.json

# Step 4: Visualize
py3plex visualize ba_network.graphml --layout spring --width 15 --height 10 \
    --output ba_visualization.png

Example 2: Load, Analyze Statistics, and Export

# Step 1: Load and inspect
py3plex load existing_network.graphml --stats

# Step 2: Compute comprehensive statistics
py3plex stats existing_network.graphml --measure all --output stats.json

# Step 3: Convert to GEXF for Gephi
py3plex convert existing_network.graphml --output for_gephi.gexf

Example 3: Multiple Analysis Pipeline

# Create network
py3plex create --nodes 50 --layers 2 --type er --probability 0.15 \
    --output network.graphml --seed 42

# Run all centrality measures
py3plex centrality network.graphml --measure degree --output degree.json
py3plex centrality network.graphml --measure betweenness --output betweenness.json
py3plex centrality network.graphml --measure pagerank --output pagerank.json

# Detect communities with different algorithms
py3plex community network.graphml --algorithm louvain --output louvain.json
py3plex community network.graphml --algorithm label_prop --output label_prop.json

# Create multiple visualizations
py3plex visualize network.graphml --layout multilayer --output viz_ml.png
py3plex visualize network.graphml --layout spring --output viz_spring.png
py3plex visualize network.graphml --layout circular --output viz_circular.png

Tips and Best Practices

Use Seeds for Reproducibility: Always use --seed when creating networks for reproducible results.
JSON Output for Scripting: Use --output to save results as JSON for post-processing with other tools.
Check Help for Each Command: Each command has detailed help with examples:
```
py3plex <command> --help
```
Format Auto-Detection: The CLI automatically detects file formats from extensions, so use appropriate extensions (.graphml, .gexf, .json, .gpickle).
Large Networks: For large networks (>1000 nodes), prefer:
- spring or circular layouts for visualization
- louvain for community detection (faster than infomap)
- degree centrality for quick analysis
Batch Processing: Combine CLI commands with shell scripts for batch processing multiple networks.

Common Issues and Solutions

Issue: “Infomap not available”

Solution: Infomap requires separate installation. Use louvain or label_prop instead.

Issue: “Eigenvector centrality failed”

Solution: Some networks don’t converge for eigenvector centrality. The CLI automatically falls back to degree centrality.

Issue: Visualization too slow

Solution: Use simpler layouts (circular) or reduce figure size (--width 8 --height 6).

Issue: Memory errors with large networks

Solution: Use aggregation to reduce network size before visualization, or compute statistics without visualization.

Command-Line Interface (CLI) Tutorial

Installation

Getting Help

Available Commands

Creating Networks

Create Random Networks

Network Generation Models

Output Formats

Loading and Inspecting Networks

Basic Network Information

Detailed Statistics

Save to JSON

Community Detection

Louvain Algorithm

With Custom Resolution

Label Propagation

Infomap (Optional)

Centrality Measures

Degree Centrality

Save Results

All Centrality Measures

Multilayer Network Statistics

Comprehensive Statistics

Specific Statistics

Network Visualization

Multilayer Layout

Standard Layouts

Custom Figure Size

Network Aggregation

Sum Aggregation

Mean Aggregation

Other Aggregation Methods

Format Conversion

Convert Between Formats

Complete Workflow Examples

Example 1: Create, Analyze, and Visualize

Example 2: Load, Analyze Statistics, and Export

Example 3: Multiple Analysis Pipeline

Tips and Best Practices

Common Issues and Solutions

See Also