# medmaca/pgcna architecture

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

- Interactive diagram: https://gitdiagram.com/medmaca/pgcna
- Repository: https://github.com/medmaca/pgcna

## Overview

##### Project type and purpose
- Type: Python-based command-line tool for parsimonious gene correlation network analysis.
- Purpose:
- Read gene expression input data
- Compute pairwise correlations
- Retain the top 3 edges per gene (parsimonious pruning)
- Build a gene–gene network
- Detect communities/modules (PGCNA uses original algorithm; PGCNA2 uses improved community detection)
- Output network and module assignments for downstream tools

##### File structure
- Top‐level: README.md describing both versions.
- Subfolder “PGCNA”:
- pgcna.py – core CLI entrypoint and processing pipeline for original version
- pgcna-multi.py – variant supporting multi‐threading or batch runs
- README.md – usage instructions for original version
- Subfolder “PGCNA2”:
- pgcna2.py – CLI entrypoint using the improved community detection algorithm
- README.md – usage instructions for the 2.0 version

##### README for architectural clues
- Both versions share the same high-level pipeline up to community detection
- Only the “community detection” block differs between PGCNA and PGCNA2

##### Main components
a. CLI Interface
- Argument parser (input file paths, parameters, version flag)
b. Data Loader
- CSV/TSV expression matrix reader
c. Correlation Matrix Calculator
- Compute pairwise gene correlation (e.g. Pearson)
d. Parsimonious Pruner
- For each gene, select top-3 edges
e. Network Builder
- Build graph data structure (nodes = genes; edges = top correlations)
- Original algorithm (PGCNA)
- Improved algorithm (PGCNA2)
g. Output Writer
- Module assignments file
- Network edge list file
- (Optionally) visualization files for downstream tools
h. External Libraries/Dependencies
- NumPy/Pandas (data handling)
- NetworkX or igraph (graph operations)
- community-detection library (for PGCNA2)

##### Relationships and data flows
CLI → Data Loader → Correlation Calculator → Pruner → Network Builder → Community Detection → Output Writer

##### Architectural patterns and principles
- Pipeline pattern: each step is a separate, composable function/module
- Separation of concerns: data I/O, computation, graph operations, and output
- Version-swap point: isolate community-detection algorithm so it can be replaced (strategy pattern)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline Steps
    CLI["CLI Interface\n(argument parser)"]:::io
    Loader["Data Loader\n(read CSV/TSV)"]:::io
    Correlator["Correlation Calculator\n(pairwise correlations)"]:::computation
    Pruner["Parsimonious Pruner\n(top-3 edges)"]:::computation
    Builder["Network Builder\n(graph construction)"]:::graphlogic
    Decision{"Version Flag?"}:::computation
    OrigAlgo["Original Community Detection"]:::algorithm
    ImpAlgo["Improved Community Detection"]:::algorithm
    Writer["Output Writer\n(network & modules)"]:::io

    %% Documentation
    DocsRoot["Project Overview\nREADME.md"]:::docs
    Docs1["PGCNA Usage\nREADME.md"]:::docs
    Docs2["PGCNA2 Usage\nREADME.md"]:::docs

    %% External Libraries
    subgraph "External Libraries"
        NumPandas["NumPy/Pandas"]:::ext
        NetLib["NetworkX/igraph"]:::ext
        CommLib["community-detection lib"]:::ext
    end

    %% Data Flow
    CLI -->|"expression matrix"| Loader
    Loader -->|"raw data"| Correlator
    Correlator -->|"correlation matrix"| Pruner
    Pruner -->|"pruned edges"| Builder
    Builder -->|"initial graph"| Decision
    Decision -->|"PGCNA v1"| OrigAlgo
    Decision -->|"PGCNA v2"| ImpAlgo
    OrigAlgo -->|"modules & network"| Writer
    ImpAlgo -->|"modules & network"| Writer

    %% Optional Multi-threaded Runner
    Multi["Multi-threaded Runner"]:::io
    Multi --> CLI

    %% Docs Links
    DocsRoot
    Docs1
    Docs2

    %% Dependency Arrows
    NumPandas --> Loader
    NumPandas --> Correlator
    NetLib --> Builder
    CommLib --> ImpAlgo

    %% Click Events
    click CLI "https://github.com/medmaca/pgcna/blob/master/PGCNA/pgcna.py"
    click Multi "https://github.com/medmaca/pgcna/blob/master/PGCNA/pgcna-multi.py"
    click ImpAlgo "https://github.com/medmaca/pgcna/blob/master/PGCNA2/pgcna2.py"
    click Docs1 "https://github.com/medmaca/pgcna/blob/master/PGCNA/README.md"
    click Docs2 "https://github.com/medmaca/pgcna/blob/master/PGCNA2/README.md"
    click DocsRoot "https://github.com/medmaca/pgcna/blob/master/README.md"
    click OrigAlgo "https://github.com/medmaca/pgcna/blob/master/PGCNA/pgcna.py"

    %% Styles
    classDef io fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef computation fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef graphlogic fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef algorithm fill:#FFCDD2,stroke:#333,stroke-width:1px
    classDef docs fill:#E1BEE7,stroke:#333,stroke-width:1px
    classDef ext fill:#EEEEEE,stroke:#999,stroke-dasharray: 2 2
```
