# skblaz/py3plex architecture

> Architecture diagram of the GitHub repository skblaz/py3plex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skblaz/py3plex
- Repository: https://github.com/skblaz/py3plex

## Overview

##### Project type and purpose
- Py3Plex is an open-source Python library and CLI tool for analysis and visualization of heterogeneous (multilayer) networks.
- It bundles core data structures, I/O modules, a suite of network algorithms (community detection, embeddings, centrality, statistics, rule-based inference “Hedwig”), and visualization primitives.
- It also provides a command-line interface, example scripts, Sphinx-based documentation, CI pipelines, benchmarks, and optional Docker/fuzzing setups.

##### File structure
- Top-level directories:
- py3plex/          ← core package
- examples/         ← user-facing scripts (50+ demos)
- docfiles/, docs/  ← source and built HTML docs
- datasets/, multilayer_datasets/ ← sample data
- benchmarks/       ← performance tests
- tests/            ← unit, property, integration tests
- fuzzing/, Dockerfile, docker-compose.yml ← CI and optional containers
- Inside py3plex/:
- core/             ← data structures, parsers, multinet support
- io/               ← API, format converters, schema, exceptions
- algorithms/       ← subpackages for community detection, multilayer algorithms, statistics, Hedwig inference
- visualization/    ← drawing machinery, force‐atlas2, embedding visualizations
- wrappers/         ← thin scripts invoking external tools (Node2Vec, benchmarks)
- cli.py            ← entrypoint for the command-line interface
- config.py, logging_config.py
- CI and tooling:
- .github/workflows/*.yml ← GitHub Actions for tests, docs, fuzzing, benchmarks, type coverage
- Makefile          ← convenience targets (test, benchmark, lint)
- pytest.ini, pre-commit config

##### README for additional insights
- Confirms Python ≥3.8, dependencies on NetworkX, NumPy, SciPy.
- Notes optional external binaries (Infomap, Node2Vec) under AGPLv3 or third-party tools.
- Emphasizes CLI tool and Sphinx documentation (hosted online).
- Shows licensing matrix and recommendations for commercial use.
- Describes benchmark workflows, testing commands, and performance targets.

a. Main Components
- CLI Layer: `py3plex/cli.py` + command-line entrypoints
- Core Library: `py3plex/core` (data models, multilayer network abstraction, random generators)
- I/O Layer: `py3plex/io` (load/save, format converters, schema validation)
- Algorithm Layer:
- Community Detection (Louvain, Infomap wrapper submodule)
- Multilayer Algorithms (centrality, entanglement, multi-rank)
- Statistical Analysis (basic stats, Bayesian tests, enrichment)
- Temporal & Dynamics (random walks, SIR multiplex)
- Hedwig Rule Engine (rule loading, inference, learners)
- Visualization Layer: drawing primitives, layout algorithms (ForceAtlas2), embedding visualization
- Wrappers & Extensions: scripts invoking external Node2Vec binaries or pure-Python replacements
- Data Sources / Datasets: sample edge lists, GML/GPickle, ontologies (GO), multiplex datasets
- External Services/Binaries: Infomap (AGPLv3), Node2Vec, networkx, NumPy/SciPy
- Examples & Tutorials: example scripts & Jupyter notebooks
- Documentation Subsystem: Sphinx (`docfiles/` → `docs/`)
- CI & Testing: GitHub Actions, pytest, fuzzing, benchmarks

b. Relationships and Data Flow
1. User invokes CLI → CLI Layer
2. CLI calls Core Library to instantiate network object
3. Core Library requests I/O Layer to load or save data
4. Loaded network passed to Algorithm Layer
5. Algorithm Layer produces results (community assignments, embeddings, stats)
6. Results passed to Visualization Layer to render plots or embeddable outputs
7. Wrappers can call external binaries; control flows back into Python pipeline
8. Examples import and combine these layers end-to-end
9. Documentation pipeline reads code & docfiles to build website
10. CI workflows test each layer, collect benchmarks, verify docs and type coverage

c. Architectural Patterns and Design Principles
- Layered modular architecture (separate CLI, core, IO, algorithms, visualization)
- Plugin-style algorithm subpackages for easy extensibility
- Single responsibility per package: e.g., I/O only handles parsing/serialization
- Clear separation of pure-Python vs. external-binary code (Infomap submodule isolated)
- Use of property-based tests and fuzzing for robust validation

d. Key Technologies, Frameworks, and Libraries
- Python 3.8+, NetworkX, NumPy, SciPy
- Sphinx for documentation
- pytest + Hypothesis for tests & property tests
- GitHub Actions for CI/CD
- Docker for isolated fuzzing and containerized examples
- Optional external C++ binaries (Infomap, Node2Vec)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        CLI1["cli.py"]:::cli
        CLI2["__main__.py"]:::cli
    end

    subgraph "Core Library"
        Core["Core Library"]:::core
    end

    subgraph "I/O Layer"
        IO["I/O Layer"]:::io
    end

    subgraph "Algorithm Layer"
        subgraph "Community Detection"
            CD["Community Detection"]:::alg
        end
        subgraph "Multilayer Algorithms"
            MA["Multilayer Algorithms"]:::alg
        end
        subgraph "Statistical Analysis"
            SA["Statistical Analysis"]:::alg
        end
        subgraph "Temporal & Dynamics"
            TDyn["Temporal & Dynamics"]:::alg
        end
        subgraph "Hedwig Rule Engine"
            Hedwig["Hedwig Rule Engine"]:::alg
        end
    end

    subgraph "Visualization Layer"
        Viz["Visualization Layer"]:::viz
    end

    Wrappers["Wrappers & Extensions"]:::ext
    DataSources["Data Sources"]:::data
    Examples["Examples & Tutorials"]:::examples
    Docs["Documentation Subsystem"]:::docs
    CI["CI & Testing"]:::ci

    %% Data & Control Flow
    CLI1 -->|invokes| Core
    CLI2 -->|invokes| Core
    Core -->|loads/saves| IO
    IO -->|provides data| Core
    Core -->|instantiates| CD
    Core -->|instantiates| MA
    Core -->|instantiates| SA
    Core -->|instantiates| TDyn
    Core -->|instantiates| Hedwig
    CD -->|results| Viz
    MA -->|results| Viz
    SA -->|results| Viz
    TDyn -->|results| Viz
    Hedwig -->|results| Viz

    %% Optional interactions
    Wrappers -.->|external binaries| CD
    Wrappers -.->|external binaries| Viz
    Examples -->|demonstrates| CLI1
    Examples -->|demonstrates| Viz
    DataSources -->|feeds| IO
    Docs -.->|builds| Core
    Docs -.->|builds| Examples
    CI -->|tests pipelines| CLI1
    CI -->|tests pipelines| Core
    CI -->|tests pipelines| IO
    CI -->|tests pipelines| CD

    %% Click Events
    click CLI1 "https://github.com/skblaz/py3plex/blob/master/py3plex/cli.py"
    click CLI2 "https://github.com/skblaz/py3plex/blob/master/py3plex/__main__.py"
    click Core "https://github.com/skblaz/py3plex/tree/master/py3plex/core/"
    click IO "https://github.com/skblaz/py3plex/tree/master/py3plex/io/"
    click CD "https://github.com/skblaz/py3plex/tree/master/py3plex/algorithms/community_detection/"
    click MA "https://github.com/skblaz/py3plex/tree/master/py3plex/algorithms/multilayer_algorithms/"
    click SA "https://github.com/skblaz/py3plex/tree/master/py3plex/algorithms/statistics/"
    click TDyn "https://github.com/skblaz/py3plex/tree/master/py3plex/algorithms/temporal_multiplex/"
    click Hedwig "https://github.com/skblaz/py3plex/tree/master/py3plex/algorithms/hedwig/"
    click Viz "https://github.com/skblaz/py3plex/tree/master/py3plex/visualization/"
    click Wrappers "https://github.com/skblaz/py3plex/tree/master/py3plex/wrappers/"
    click DataSources "https://github.com/skblaz/py3plex/tree/master/datasets/"
    click Examples "https://github.com/skblaz/py3plex/tree/master/examples/"
    click Docs "https://github.com/skblaz/py3plex/tree/master/docfiles/"
    click CI "https://github.com/skblaz/py3plex/tree/master/.github/workflows/"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef io fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef alg fill:#d4edda,stroke:#333,stroke-width:1px
    classDef viz fill:#e2e3f3,stroke:#333,stroke-width:1px
    classDef ext fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef examples fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef docs fill:#f5c6cb,stroke:#333,stroke-width:1px
    classDef ci fill:#d6d8db,stroke:#333,stroke-width:1px
```
