# miplabch/bimodularity architecture

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

- Interactive diagram: https://gitdiagram.com/miplabch/bimodularity
- Repository: https://github.com/miplabch/bimodularity

## Overview

##### Project Type and Purpose
- This is a data‐analysis/research toolkit (not a web app). Its purpose is to replicate the figures and analyses from the PNAS paper on bimodularity in directed networks.
- Key indicators: two Jupyter notebooks that generate figures, Python scripts for computational modules, and a “data” directory with C. elegans connectivity files.

##### File Structure
Top level:
- README.md, LICENSE, CITATION.cff – documentation and licensing
- requirements.txt – environment dependencies
- Bimodularity–Figures.ipynb, Bimodularity–Supplementary.ipynb – orchestration notebooks
- bimod_plots.py – plotting utilities
- graph_examples.py – canonical graph construction
- dgsp.py – core bimodularity analysis functions
- data/ – numerical and CSV data inputs
- graph_examples.py and bimod_plots.py reference data and dgsp.py
- No deployment scripts—this runs locally in Python 3.11.8.

##### Extract Insights from the README
- Environment setup: pip/conda for Python 3.11.8
- Notebook roles: Figures notebook handles main article figures; Supplementary notebook handles extra figures.
- Data sources: WormAtlas C. elegans connectivity files.

##### Main Components
a. Data Layer
– data/celegans_graph.csv, .npy, etc.
– Possibly external data source (WormAtlas) as a reference
b. Computational Modules
– dgsp.py (bimodularity computations)
– graph_examples.py (builds example graphs)
– bimod_plots.py (plotting routines)
c. Orchestration Layer
– Jupyter notebooks (Figures and Supplementary)
- They import modules, load data, run analyses, output figures
d. Environment & Dependencies
– Python 3.11.8 runtime
– Third‐party libraries (numpy, pandas, networkx, matplotlib, etc. from requirements.txt)
e. Outputs
– Generated figure files (e.g., PNG/SVG) embedded in notebooks
– Potential saved analysis results (e.g., .npy benchmark arrays)

##### Relationships and Data Flow
- Notebooks → import modules (dgsp, graph_examples, bimod_plots)
- Modules → read raw data from data/
- graph_examples → generate canonical graphs → pass to dgsp
- dgsp → compute bimodularity metrics → pass results to bimod_plots
- bimod_plots → render figures → notebooks display/save them
- Third‐party libraries support all modules

##### Architectural Patterns & Principles
- Modular Pipeline: separate concerns (data loading, computation, visualization)
- Orchestration via notebooks: high‐level workflow scripts
- Reproducibility: explicit requirements.txt and environment versions
- No external services—purely local computation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment & Dependencies
    Env["Python 3.11.8 + Libraries"]:::env
    Requirements["requirements.txt"]:::env
    Requirements -->|"provides deps"| Env

    %% Documentation & Metadata
    subgraph "Documentation & Metadata"
        README["README.md"]:::doc
        CITATION["CITATION.cff"]:::doc
        LICENSE["LICENSE"]:::doc
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        DataFolder["data/"]:::data
        CSV1["celegans_graph.csv"]:::data
        CSV2["celegans_graph_GAP.csv"]:::data
        CSV3["celegans_neurons.csv"]:::data
        NPY["Benchmark_all_dice-N5-B18-C10-T5.npy"]:::data
        DataFolder --> CSV1
        DataFolder --> CSV2
        DataFolder --> CSV3
        DataFolder --> NPY
    end

    %% Computational Modules
    subgraph "Computational Modules"
        direction TB
        DGSP["dgsp.py<br/>(Bimodularity Engine)"]:::code
        GraphEx["graph_examples.py<br/>(Graph Example Generator)"]:::code
        Plots["bimod_plots.py<br/>(Plotting Utilities)"]:::code
    end

    %% Orchestration Layer
    subgraph "Orchestration Notebooks"
        direction TB
        Figures["Bimodularity-Figures.ipynb"]:::notebook
        Supplementary["Bimodularity-Supplementary.ipynb"]:::notebook
    end

    %% Outputs
    Output["Generated Figures<br/>(PNG/SVG)"]:::output

    %% Relationships
    DataFolder -->|"load data"| GraphEx
    DataFolder -->|"load data"| DGSP
    GraphEx -->|"generate graphs"| DGSP
    DGSP -->|"compute bimodularity"| Plots
    Plots -->|"render plots"| Figures
    Plots -->|"render plots"| Supplementary
    Figures -->|"produce figures"| Output
    Supplementary -->|"produce figures"| Output

    Env -->|"runs modules"| GraphEx
    Env -->|"runs modules"| DGSP
    Env -->|"runs modules"| Plots
    Env -->|"runs notebooks"| Figures
    Env -->|"runs notebooks"| Supplementary

    README -.-> Env
    CITATION -.-> Env
    LICENSE -.-> Env

    %% Click Events
    click DataFolder "https://github.com/miplabch/bimodularity/tree/main/data/"
    click CSV1 "https://github.com/miplabch/bimodularity/blob/main/data/celegans_graph.csv"
    click CSV2 "https://github.com/miplabch/bimodularity/blob/main/data/celegans_graph_GAP.csv"
    click CSV3 "https://github.com/miplabch/bimodularity/blob/main/data/celegans_neurons.csv"
    click NPY "https://github.com/miplabch/bimodularity/blob/main/data/Benchmark_all_dice-N5-B18-C10-T5.npy"
    click DGSP "https://github.com/miplabch/bimodularity/blob/main/dgsp.py"
    click GraphEx "https://github.com/miplabch/bimodularity/blob/main/graph_examples.py"
    click Plots "https://github.com/miplabch/bimodularity/blob/main/bimod_plots.py"
    click Figures "https://github.com/miplabch/bimodularity/blob/main/Bimodularity-Figures.ipynb"
    click Supplementary "https://github.com/miplabch/bimodularity/blob/main/Bimodularity-Supplementary.ipynb"
    click Requirements "https://github.com/miplabch/bimodularity/blob/main/requirements.txt"
    click README "https://github.com/miplabch/bimodularity/blob/main/README.md"
    click CITATION "https://github.com/miplabch/bimodularity/blob/main/CITATION.cff"
    click LICENSE "https://github.com/miplabch/bimodularity/tree/main/LICENSE"

    %% Styles
    classDef data fill:#e0ffe0,stroke:#2d7f2d,color:#000
    classDef code fill:#e0f0ff,stroke:#1f4b8f,color:#000
    classDef notebook fill:#ffffcc,stroke:#8f7500,color:#000
    classDef env fill:#dddddd,stroke:#555555,color:#000
    classDef doc fill:#f5f5f5,stroke:#777777,color:#000
    classDef output fill:#ffe0e0,stroke:#8f0000,color:#000
```
