# nanocell-lab/metabcrosstalk architecture

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

- Interactive diagram: https://gitdiagram.com/nanocell-lab/metabcrosstalk
- Repository: https://github.com/nanocell-lab/metabcrosstalk

## Overview

##### Project Type and Purpose
- This is a bioinformatics data analysis pipeline implemented in Jupyter notebooks.
- Purpose: perform proteomics-based metabolic cross-talk analyses between human and bacterial systems. It ingests experimental data, enriches functional annotations, queries external biological databases (HOMD, MetaCyc, g:Profiler, IPA), and produces visualizations and summary tables.

##### File Structure Analysis
- Top-level directories:
– data/ : raw and intermediate tabular datasets (TSV, CSV, XLSX)
– src/ : four Jupyter notebooks, each corresponding to a major processing step
- Data sources under data/:
– Bacteria.tsv, HOMD/*.tsv for bacterial gene mapping
– Human Proteins.xlsx and Proteomica_Humana_CO/*.csv/.xlsx for human proteomics enrichment
- Notebooks under src/:
– 01ProteomicsHuman.ipynb: loads human proteomics, preps for enrichment
– 02FunctionalEnrichmentA.ipynb: runs GOEA (g:Profiler) and IPA analyses
– 03ProteomicsBacteria.ipynb: maps bacterial proteins to genes (HOMD)
– 04MetaCyc.ipynb: queries MetaCyc for L-glutamate pathways and counts gene occurrences
- No build scripts or server components—pipeline is orchestrated by sequential notebook execution.

##### README Insights
- Dependencies: Python 3, Pandas, Bioinfokit, QIAGEN IPA (external tool), g:Profiler API
- The methodology describes three stages for bacteria and two for human analyses.
- External services: QIAGEN IPA (proprietary), g:Profiler (web API), HOMD database, MetaCyc database.

a. Main Components
1. Data Ingestion Layer
– Local raw data files (data/*.tsv, *.xlsx)
– External reference databases (HOMD, MetaCyc)
2. Processing & Analysis Modules
– Notebook 01: Human proteomics data preprocessing
– Notebook 02: Functional enrichment (g:Profiler + IPA)
– Notebook 03: Bacterial gene mapping via HOMD
– Notebook 04: Pathway retrieval & gene counting in MetaCyc
3. External Services
– g:Profiler REST API
– QIAGEN IPA tool (local client or API)
– HOMD and MetaCyc (flat files or web API)
4. Output/Visualization
– Figures and tables exported by notebooks (charts, CSV, XLSX)

b. Relationships and Data Flows
- Data files feed into notebooks in sequence:
01ProteomicsHuman → 02FunctionalEnrichmentA
03ProteomicsBacteria → 04MetaCyc
- 02FunctionalEnrichmentA calls g:Profiler and IPA, merges results.
- 03ProteomicsBacteria queries HOMD dataset to map proteins → genes.
- 04MetaCyc uses gene lists to query MetaCyc pathways and aggregates counts.
- Final visualizations and summary tables are generated per notebook and stored locally.

c. Architectural Patterns and Principles
- Pipeline pattern: sequential data processing stages.
- Modularity: each notebook encapsulates a logical analysis step.
- Data provenance: raw inputs, intermediate artifacts, final outputs.
- External integration: clear boundaries where external APIs/tools are invoked.

d. Technologies / Libraries
- Python 3 and Jupyter notebooks
- Pandas for data manipulation
- Bioinfokit for statistical plots
- g:Profiler API, QIAGEN IPA
- Flat-file data sources (TSV, XLSX) for HOMD and MetaCyc

## Diagram (Mermaid)

```mermaid
graph TD
    %% Human Workflow
    subgraph "Human Workflow"
        direction TB
        RawHuman["Human Proteomics Data\n(data/Human Proteins.xlsx)"]:::data-source
        NB1["01ProteomicsHuman.ipynb"]:::process
        PreppedHuman["Preprocessed Human Data\n(TSV/CSV)"]:::intermediate
        NB2["02FunctionalEnrichmentA.ipynb"]:::process
        UPRes["g:Profiler UP Results\n(CSV)"]:::output
        DOWNRes["g:Profiler DOWN Results\n(CSV)"]:::output
        IPARes["QIAGEN IPA Results\n(XLSX)"]:::output
    end

    RawHuman -->|"XLSX"| NB1
    NB1 -->|"TSV/CSV"| PreppedHuman
    PreppedHuman -->|"TSV/CSV"| NB2
    NB2 -->|"API request/response"| gProfiler
    NB2 -->|"local tool"| IPA
    NB2 -->|"exports CSV"| UPRes
    NB2 -->|"exports CSV"| DOWNRes
    NB2 -->|"exports XLSX"| IPARes

    %% Bacterial Workflow
    subgraph "Bacterial Workflow"
        direction TB
        RawBacteria["Bacterial Proteomics Data\n(data/Bacteria.tsv)"]:::data-source
        NB3["03ProteomicsBacteria.ipynb"]:::process
        HOMDRef["HOMD Reference\n(data/HOMD/SEQF10000.1.tsv)"]:::data-source
        BactGenes["Mapped Bacterial Genes\n(TSV)"]:::intermediate
        NB4["04MetaCyc.ipynb"]:::process
        MetaCycDB["MetaCyc Database"]:::external
        PathwayRes["Pathway Counts\n(CSV)"]:::output
    end

    RawBacteria -->|"TSV"| NB3
    NB3 -->|"flat-file lookup"| HOMDRef
    HOMDRef -->|"TSV"| NB3
    NB3 -->|"TSV"| BactGenes
    BactGenes -->|"TSV"| NB4
    NB4 -->|"API request/response"| MetaCycDB
    NB4 -->|"aggregates counts"| PathwayRes

    %% External Services
    subgraph "External Services"
        direction TB
        gProfiler["g:Profiler API"]:::external
        IPA["QIAGEN IPA"]:::external
        MetaCycDB
    end

    %% Click Events
    click RawHuman "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/Human Proteins.xlsx"
    click RawBacteria "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/Bacteria.tsv"
    click HOMDRef "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/HOMD/SEQF10000.1.tsv"
    click NB1 "https://github.com/nanocell-lab/metabcrosstalk/blob/main/src/01ProteomicsHuman.ipynb"
    click NB2 "https://github.com/nanocell-lab/metabcrosstalk/blob/main/src/02FunctionalEnrichmentA.ipynb"
    click NB3 "https://github.com/nanocell-lab/metabcrosstalk/blob/main/src/03ProteomicsBacteria.ipynb"
    click NB4 "https://github.com/nanocell-lab/metabcrosstalk/blob/main/src/04MetaCyc.ipynb"
    click UPRes "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/Proteomica_Humana_CO/UPhuman_gProfiler_hsapiens_12-12-2023_17-08-02__intersections.csv"
    click DOWNRes "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/Proteomica_Humana_CO/DOWNhuman_gProfiler_hsapiens_12-12-2023_17-11-29__intersections.csv"
    click IPARes "https://github.com/nanocell-lab/metabcrosstalk/blob/main/data/Proteomica_Humana_CO/IPA.xlsx"

    %% Styling
    classDef data-source fill:#FFD580,stroke:#E69A00,stroke-width:2px;
    classDef process fill:#80B3FF,stroke:#0059B3,stroke-width:2px;
    classDef external fill:#C2F0C2,stroke:#339933,stroke-width:2px;
    classDef intermediate fill:#FFCCCB,stroke:#B30000,stroke-width:2px;
    classDef output fill:#D9D9D9,stroke:#666666,stroke-width:2px;
```
