Common Issues and Troubleshooting

This guide helps you troubleshoot common problems when getting started with py3plex.

Installation Issues

“No module named ‘numpy’”

Problem: Import error when trying to use py3plex.

Solution: Install numpy first:

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

Compilation Errors on Windows

Problem: C++ compilation errors during installation on Windows.

Solution: Install Visual C++ Build Tools:

  1. Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

  2. Install “Desktop development with C++”

  3. Retry installation

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

“Permission denied” on Linux/macOS

Problem: Permission errors during pip install.

Solution 1: Use pip install with –user flag:

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

Solution 2: Use a virtual environment (recommended):

python3 -m venv py3plex-env
source py3plex-env/bin/activate  # On Windows: py3plex-env\Scripts\activate
pip install git+https://github.com/SkBlaz/py3plex.git

Old Version Installed

Problem: Changes not reflecting or documentation mentions newer features.

Solution: Upgrade to the latest version:

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

Data Loading Issues

File Not Found Errors

Problem: FileNotFoundError when loading networks.

Solution 1: Use absolute paths:

import os

network_path = "/absolute/path/to/data.edgelist"
network = multinet.multi_layer_network().load_network(
    network_path, input_type="edgelist", directed=False
)

Solution 2: Ensure you’re running from the correct directory:

import os

# Check current directory
print("Current directory:", os.getcwd())

# List files
print("Files:", os.listdir('.'))

Solution 3: Use paths relative to script location:

import os

script_dir = os.path.dirname(os.path.abspath(__file__))
data_path = os.path.join(script_dir, "data", "network.edgelist")

Empty or Malformed Networks

Problem: Network loads but has no nodes or edges.

Solution: Check file format matches input_type:

# For simple edge lists (source target)
network.load_network("data.txt", input_type="edgelist")

# For multilayer edge lists (source target layer)
network.load_network("data.txt", input_type="multiedgelist")

# Always verify after loading
network.basic_stats()

Visualization Issues

Visualization Not Showing

Problem: No window appears when calling visualization functions.

Solution 1: For Jupyter notebooks, add at the top:

%matplotlib inline

Solution 2: For scripts, explicitly show the plot:

import matplotlib.pyplot as plt

# Your visualization code
draw_multilayer_default([network], display=False)

# Explicitly show
plt.show()

Solution 3: Save to file instead of displaying:

from py3plex.visualization.multilayer import hairball_plot
import matplotlib.pyplot as plt

plt.figure(figsize=(10, 10))
hairball_plot(network.core_network, layout_algorithm="force")
plt.savefig("network.png", dpi=150, bbox_inches='tight')
plt.close()

“No Display Found” Error

Problem: Error on headless servers or SSH sessions without X11.

Solution: Use Agg backend for matplotlib:

import matplotlib
matplotlib.use('Agg')  # Must be before importing pyplot
import matplotlib.pyplot as plt

# Now visualization will save to file instead of displaying
from py3plex.visualization.multilayer import draw_multilayer_default
draw_multilayer_default([network], display=False)
plt.savefig("output.png")

Blurry or Low-Quality Plots

Problem: Plots look pixelated or blurry.

Solution: Increase DPI when saving:

plt.savefig("network.png", dpi=300, bbox_inches='tight')

Missing Dependencies

“No module named ‘plotly’”

Problem: Interactive visualization features not working.

Solution: Install visualization extras:

pip install git+https://github.com/SkBlaz/py3plex.git#egg=py3plex[viz]

“No module named ‘infomap’”

Problem: Infomap community detection not working.

Solution: Install Infomap support:

pip install git+https://github.com/SkBlaz/py3plex.git#egg=py3plex[infomap]

Or use alternative community detection methods:

from py3plex.algorithms.community_detection import community_louvain
communities = community_louvain.best_partition(network.core_network)

Performance Issues

Very Slow Loading

Problem: Loading large networks takes too long.

Solution 1: Use Arrow/Parquet format for large networks:

# Install Arrow support
pip install git+https://github.com/SkBlaz/py3plex.git#egg=py3plex[arrow]

from py3plex.io import read, write

# Save in efficient format
write(network, "network.arrow")

# Load much faster
network = read("network.arrow")

Solution 2: Process in chunks or use subnetworks:

# Extract a single layer for testing
layer_1 = network.subnetwork(['layer1'], subset_by="layers")

# Work with the smaller network
layer_1.basic_stats()

Out of Memory Errors

Problem: Python crashes or raises MemoryError with large networks.

Solution: See Performance and Scalability Best Practices for:

  • Memory-efficient loading strategies

  • Batch processing techniques

  • Sparse matrix representations

  • Subnetwork extraction

Algorithm Issues

Community Detection Returns Trivial Results

Problem: Each node in its own community or all nodes in one community.

Solution: Adjust algorithm parameters:

from py3plex.algorithms.community_detection.multilayer_modularity import (
    louvain_multilayer
)

# Try different resolution parameters
partition = louvain_multilayer(
    network,
    gamma=0.5,    # Lower = fewer, larger communities
    omega=1.5,    # Higher = more layer consistency
    random_state=42
)

Random Walk or Embedding Errors

Problem: Random walk or Node2Vec functions fail.

Solution: Ensure network is connected:

import networkx as nx

# Check connectivity
if not nx.is_connected(network.core_network.to_undirected()):
    print("Warning: Network is not connected")

    # Get largest component
    largest = max(nx.connected_components(
        network.core_network.to_undirected()
    ), key=len)

    # Create subgraph
    subgraph = network.core_network.subgraph(largest)

Docker Issues

Docker Build Fails

Problem: Docker build fails or takes very long.

Solution: Clear Docker cache and rebuild:

docker system prune -a
docker build --no-cache -t py3plex:latest .

Cannot Access Files in Docker

Problem: Docker container can’t see your data files.

Solution: Mount volumes correctly:

# Mount current directory
docker run -v $(pwd):/data py3plex:latest /data/network.edgelist

# On Windows (PowerShell)
docker run -v ${PWD}:/data py3plex:latest /data/network.edgelist

See Docker Usage Guide for complete Docker documentation.

Getting Help

If you encounter an issue not covered here:

  1. Search GitHub Issues: https://github.com/SkBlaz/py3plex/issues

  2. Check Documentation: https://skblaz.github.io/py3plex/

  3. Browse Examples: https://github.com/SkBlaz/py3plex/tree/master/examples

When reporting issues, include: * Python version (python --version) * py3plex version (pip show py3plex) * Operating system * Full error traceback * Minimal code to reproduce the problem