# ngirmay/tissue-of-origin architecture

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

- Interactive diagram: https://gitdiagram.com/ngirmay/tissue-of-origin
- Repository: https://github.com/ngirmay/tissue-of-origin

## Overview

##### Project Type and Purpose
- This is a data-analysis pipeline implemented in a Jupyter notebook (“tissue_oo.ipynb”) that ingests RNA-Seq gene-expression data, preprocesses it, trains a gradient-boosting model to classify tumor tissue of origin, evaluates performance, and generates visualizations and notes.

##### Main Components
a. External Data Source
- ICGC DCC (projects/releases) – contains compressed TSV files (e.g., exp_seq.KIRP-US.tsv.gz)
b. Local Data Store
- genes.txt – list of the 400 signature genes
c. Processing & Modeling
- Data Ingestion & Decompression module (Python/pandas)
- Preprocessing module (gene filtering using genes.txt, normalization)
- Model Training module (Gradient Boosting via scikit-learn/XGBoost)
d. Evaluation & Visualization
- Performance Evaluation module (computes F1, precision, recall per cancer type)
- Visualization module (matplotlib/seaborn plots embedded in Jupyter)
e. Reporting & Notes
- tissue_oo.ipynb – orchestrates the pipeline end-to-end, displays results
- TOO_paper_notes, TMB_classification_notes – markdown/text notes documenting methods and insights
f. Versioning & Config
- .gitattributes – ensures consistent EOLs in Git

##### Relationships and Data Flow
- External Data Source → (download) → Local RawData
- Local RawData + genes.txt → Data Ingestion & Decompression → Preprocessing
- Preprocessing → Model Training → Evaluation
- Evaluation → Visualization → Outputs back into tissue_oo.ipynb
- Notes files (TOO_paper_notes, TMB_classification_notes) ← inform parameters & interpretation of results

##### Architectural Patterns & Principles
- Linear, directed pipeline (DAG) with clear stage separation
- Single-entry orchestrator (the notebook) that ties together all stages
- Modular code cells or scripts for each stage (ingest, preprocess, train, evaluate, plot)
- Reproducibility emphasis: versioned data, fixed gene list, documented pipeline

##### Key Technologies & Frameworks
- Python ecosystem: pandas, numpy, scikit-learn / XGBoost, matplotlib/seaborn
- Jupyter Notebook as both orchestration and reporting layer
- Data source: ICGC DCC (TSV data files)

##### Essential Elements
- Clear, unambiguous labels on all components
- Optional: “Future Directions” extension path (e.g., add “Pathway Analysis” module)

## Diagram (Mermaid)

```mermaid
flowchart TD
    NB["tissue_oo.ipynb"]:::report
    EDC((ICGC DCC TSV files)):::external
    RD["RawData/ (TSV.gz files)"]:::dataStore
    GL["genes.txt"]:::dataStore
    DI["Data Ingestion & Decompression<br/>(pandas)"]:::process
    PR["Preprocessing<br/>(gene filtering, normalization)"]:::process
    MT["Model Training<br/>(Gradient Boosting)"]:::process
    EV["Performance Evaluation<br/>(F1, precision, recall)"]:::process
    VIZ["Visualization<br/>(matplotlib/seaborn)"]:::process
    TN["TOO_paper_notes"]:::report
    TM["TMB_classification_notes"]:::report
    GIT[".gitattributes"]:::config
    README["README.md"]:::config

    NB -->|download data| EDC
    EDC -->|stores raw data| RD
    GL -->|provides gene list| DI
    RD -->|input data| DI
    DI -->|filtered data| PR
    PR -->|training set| MT
    MT -->|model & predictions| EV
    EV -->|metrics| VIZ
    VIZ -->|plots & results| NB
    TN -->|inform parameters| NB
    TM -->|inform parameters| NB
    GIT -->|version control| NB
    README -->|project instructions| NB

    click RD "https://github.com/ngirmay/tissue-of-origin/tree/main/RawData/"
    click GL "https://github.com/ngirmay/tissue-of-origin/blob/main/genes.txt"
    click NB "https://github.com/ngirmay/tissue-of-origin/blob/main/tissue_oo.ipynb"
    click TN "https://github.com/ngirmay/tissue-of-origin/tree/main/TOO_paper_notes"
    click TM "https://github.com/ngirmay/tissue-of-origin/tree/main/TMB_classification_notes"
    click GIT "https://github.com/ngirmay/tissue-of-origin/blob/main/.gitattributes"
    click README "https://github.com/ngirmay/tissue-of-origin/blob/main/README.md"

    classDef dataStore fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef process  fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef report   fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef config   fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef external fill:#f0e68c,stroke:#333,stroke-width:1px;
```
