# nikonpic/bonetumornet architecture

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

- Interactive diagram: https://gitdiagram.com/nikonpic/bonetumornet
- Repository: https://github.com/nikonpic/bonetumornet

## Overview

##### Project type and purpose
- This is an ML research pipeline (“BonetumorNet”) for multitask deep learning on radiographs: it performs both segmentation and classification of primary bone tumors.
- It uses Python scripts and a Jupyter notebook to load data, preprocess images, train a Detectron-based model, and evaluate performance against human experts.

##### File structure
Top-level:
- main_notebook.ipynb – orchestrates the entire workflow (data loading → model training → evaluation → results)
- apt.txt, requirements.txt – system and Python dependencies
- datainfo.csv – tabular labels and filenames
- results/ – output GIFs, metrics, plots
- PNG/ – raw radiograph images (input)
- SEG/ – ground-truth segmentations (NRRD format)
src/ directory (core modules):
- utils_tumor.py – dataset preparation and data-loader logic
- utils_detectron.py – model training utilities, data augmentation, Detectron2 config
- categories.py – definition of tumor categories for classification & evaluation
- detec_helper.py – helper functions for inference and metric calculation
- intrareader_reliability.py – computes inter-reader reliability on segmentations
- eval_doctors.py – compares doctor-provided labels vs. ground truth
- extend_training.py – (if present) code to extend or fine-tune a trained model

##### README insights
- Confirms project goal, setup steps (install apt.txt, requirements.txt, add images/labels)
- Shows a demo GIF under results/
- Describes each src/ module’s role

a. Main components:
1. Data Sources: PNG images folder + SEG folder + datainfo.csv
2. Data Preparation: utils_tumor.py
3. Model Training & Inference: utils_detectron.py + Detectron2 framework
4. Category Definitions: categories.py
5. Evaluation Modules:
– detec_helper.py (model metrics)
– intrareader_reliability.py (reader consistency)
– eval_doctors.py (doctor vs. ground truth)
6. Orchestration Layer: main_notebook.ipynb
7. Output Artifacts: results/ directory (plots, GIFs, metrics)
b. Relationships & Data Flow:
- Data Preparation → Model Training & Inference
- Category Definitions feed into both training (label mapping) and evaluation
- Model outputs flow into Evaluation Modules
- Evaluation outputs flow into results/
- main_notebook.ipynb orchestrates all module calls
c. Architectural patterns & design principles:
- Pipeline pattern: distinct stages (ingest → preprocess → train → evaluate)
- Modular design: each src/ file encapsulates a single responsibility
- Notebook as orchestration vs. scripts for reusable logic
d. Key technologies/frameworks:
- Python 3.x, Jupyter Notebook
- Detectron2 (Facebook AI Research) for segmentation/classification
- Numpy, Pandas, Torch, open-source libs listed in requirements.txt
- NRRD format reader for SEG files

- Clearly label every component block (e.g., “Data Preparation (utils_tumor.py)”)
– Blue: Data sources & outputs
– Green: Processing/Training
– Orange: Evaluation & metrics
– Purple: Orchestration (notebook)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        PNG["PNG Images"]:::data
        SEG["SEG Segmentations\n(NRRD)"]:::data
        CSV["datainfo.csv"]:::data
    end

    %% Documentation & Config
    subgraph "Documentation & Config"
        README["README.md"]:::data
        APT["apt.txt"]:::data
        REQ["requirements.txt"]:::data
    end

    %% Processing & Training
    subgraph "Processing & Training"
        Prep["Data Preparation\n(utils_tumor.py)"]:::process
        Categories["Category Definitions\n(categories.py)"]:::process
        Training["Model Training & Inference\n(utils_detectron.py)"]:::process
    end

    %% Evaluation Modules
    subgraph "Evaluation Modules"
        Metrics["Model Metrics\n(detec_helper.py)"]:::eval
        Reliability["Inter-Reader Reliability\n(intrareader_reliability.py)"]:::eval
        DoctorEval["Doctor vs Ground Truth\n(eval_doctors.py)"]:::eval
        Extension["Extension / Fine-Tuning\n(extend_training.py)"]:::eval
    end

    %% Orchestration
    Orchestration["Orchestration Notebook\n(main_notebook.ipynb)"]:::orch

    %% Outputs
    Results["Results/\nOutputs (plots, GIFs, metrics)"]:::output

    %% Data Flow
    PNG --> Prep
    SEG --> Prep
    CSV --> Prep

    Prep --> Training
    Categories --> Training

    Training --> Metrics
    Training --> Reliability
    Training --> DoctorEval

    Categories --> Metrics
    Categories --> DoctorEval

    Metrics --> Results
    Reliability --> Results
    DoctorEval --> Results
    Extension --> Training

    %% Orchestration Control
    Orchestration --> Prep
    Orchestration --> Training
    Orchestration --> Metrics
    Orchestration --> Reliability
    Orchestration --> DoctorEval
    Orchestration --> Extension
    Orchestration --> Results

    %% Documentation & Config Flow
    README -.-> Orchestration
    APT -.-> Orchestration
    REQ -.-> Orchestration

    %% Click Events
    click PNG "https://github.com/nikonpic/bonetumornet/tree/main/PNG/"
    click SEG "https://github.com/nikonpic/bonetumornet/tree/main/SEG/"
    click CSV "https://github.com/nikonpic/bonetumornet/blob/main/datainfo.csv"
    click README "https://github.com/nikonpic/bonetumornet/blob/main/README.md"
    click APT "https://github.com/nikonpic/bonetumornet/blob/main/apt.txt"
    click REQ "https://github.com/nikonpic/bonetumornet/blob/main/requirements.txt"
    click Prep "https://github.com/nikonpic/bonetumornet/blob/main/src/utils_tumor.py"
    click Categories "https://github.com/nikonpic/bonetumornet/blob/main/src/categories.py"
    click Training "https://github.com/nikonpic/bonetumornet/blob/main/src/utils_detectron.py"
    click Metrics "https://github.com/nikonpic/bonetumornet/blob/main/src/detec_helper.py"
    click Reliability "https://github.com/nikonpic/bonetumornet/blob/main/src/intrareader_reliability.py"
    click DoctorEval "https://github.com/nikonpic/bonetumornet/blob/main/src/eval_doctors.py"
    click Extension "https://github.com/nikonpic/bonetumornet/blob/main/src/extend_training.py"
    click Orchestration "https://github.com/nikonpic/bonetumornet/blob/main/main_notebook.ipynb"
    click Results "https://github.com/nikonpic/bonetumornet/tree/main/results/"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef process fill:#90EE90,stroke:#000,stroke-width:1px
    classDef eval fill:#FFA500,stroke:#000,stroke-width:1px
    classDef orch fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef output fill:#ADD8E6,stroke:#000,stroke-width:1px
```
