# rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem architecture

> Architecture diagram of the GitHub repository rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem
- Repository: https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem

## Overview

This repository is a **research-grade offline ML pipeline** for **3-class image classification** (hip X-ray femoral stem type) with:
- **Training** (`main.py`)
- **Evaluation + metrics/plots** (`evaluate.py`, `final_metrics_plot.py`)
- **Inference + explainability (Grad-CAM)** (`predict.py`, `gradcam.py`)
- **Model package** (`models/`) implementing **MSFT-Net** (ResNet backbone + multi-scale features + **ECA attention** + Transformer encoder + classifier head)
- **Shared utilities** (`utils/`) for dataset loading, transforms, training loop, and metrics

So the “system” here is not a web service; it’s a **batch/offline ML workflow** that consumes image folders, produces model artifacts + reports, and optionally produces Grad-CAM visual explanations.

From the tree:

##### Entry-point pipelines (top-level scripts)
- `main.py` — training pipeline (dataset → model → optimizer → checkpoints/results)
- `evaluate.py` — evaluation pipeline (load weights → run test set → compute metrics → write results)
- `predict.py` — inference pipeline (single/few images → prediction → Grad-CAM outputs)
- `final_metrics_plot.py` — reporting/plotting pipeline (reads `results/metrics.json` → produces plots)
- `gradcam.py` — explainability engine used by prediction (and possibly evaluation)

##### Core libraries (imported by entrypoints)
These are internal modules; show them as shared components:
- `utils/dataset.py` — dataset + dataloader wiring (reads directory-structured dataset)
- `utils/transforms.py` — preprocessing/augmentation (Albumentations/torchvision style)
- `utils/engine.py` — training/validation loops, device mgmt, epoch iteration
- `utils/metrics.py` — F1, ROC-AUC, confusion matrix (scikit-learn style)

##### Model implementation
- `models/msftnet.py` — MSFT-Net definition (the central “compute” component)
- `models/eca.py` — ECA attention module (subcomponent used inside MSFT-Net)

##### Artifacts / outputs
The repo strongly implies a local artifact store:
- `results/metrics.json` (canonical numeric metrics artifact)
- `results/evaluation/` (confusion matrix, ROC, per-class outputs)
- `results/plots/` (figures such as F1 comparison, key metrics)
- `results/gradcam/` (Grad-CAM overlay images)
- `test_images/` (inference inputs / demos)

##### Training
- `dataset/` (image folders) → `utils/transforms.py` → `utils/dataset.py` → `main.py`
- `main.py` → (trained weights/checkpoints) → `results/` (and/or a weights file path)
- Optionally `main.py` → logs → `Logs/`

##### Evaluation
- `dataset/` (test split) → `utils/dataset.py` → `evaluate.py`
- `evaluate.py` + (load trained weights) → metrics computations (`utils/metrics.py`) → write:
- `results/metrics.json`
- `results/evaluation/*` (confusion matrix, ROC, etc.)

##### Reporting
- `results/metrics.json` → `final_metrics_plot.py` → `results/plots/*`

##### Inference + Explainability
- `test_images/` (or arbitrary input images) → `predict.py` → `utils/transforms.py`
- `predict.py` + (load trained weights) → model forward pass (`models/msftnet.py`)
- `predict.py` → Grad-CAM (`gradcam.py`) → `results/gradcam/*`

These describe imports/usage:
- `main.py` → `utils/engine.py`, `utils/metrics.py`, `models/msftnet.py`
- `evaluate.py` → `utils/dataset.py`, `utils/metrics.py`, `models/msftnet.py`
- `predict.py` → `models/msftnet.py`, `gradcam.py`, `utils/transforms.py`
- `models/msftnet.py` → `models/eca.py` (and backbone library: timm/torchvision)

##### Pipeline separation by concern
- Training / evaluation / inference are separate entrypoints, each producing distinct artifacts.
- Shared utilities reduce duplication (dataset, transforms, engine, metrics).

##### Hybrid model architecture
- CNN backbone (ResNet-50, pretrained via `timm`) for local feature extraction
- Multi-scale feature usage (C2–C5 concept from README)
- **ECA attention** module as lightweight channel attention
- **Transformer encoder** for global context
- Classifier head for 3-way output

##### Explainable AI as first-class output
- Grad-CAM generation is integrated as a pipeline stage, producing interpretable overlays.

##### File-system as the “integration bus”
- There is no DB/message queue; the integration mechanism is persisted artifacts in `results/` and (implied) saved weights + logs.

##### View 1 — “Workflow / orchestration” (highest value)
Purpose: show how a user runs the system and what gets produced.

- Inputs: `dataset/`, `test_images/`
- Runners: `main.py`, `evaluate.py`, `predict.py`, `final_metrics_plot.py`
- Shared libs: `utils/*`, `models/*`, `gradcam.py`
- Artifacts: `results/*` (+ optional `Logs/`)

- Solid = data/artifacts (images, weights, metrics.json, plots, heatmaps)

This should closely mirror the repo’s reality.

##### View 2 — “Model internal architecture (MSFT-Net)”
Purpose: show what is inside `models/msftnet.py` at a block level.

Recommended blocks:
- Input tensor (post-transform)
- ResNet-50 backbone (pretrained)
- Multi-scale feature aggregation (C2/C3/C4/C5)
- ECA attention (from `models/eca.py`)
- Transformer encoder module
- Pooling/flatten + classifier head
- Softmax/logits → 3 classes

Short annotations: “local features”, “channel recalibration”, “global context”.

##### View 3 — “Metrics + explainability subsystem”
Purpose: separate “model performance reporting” from “prediction explainability”.

Show:
- `utils/metrics.py` generating F1/ROC-AUC/confusion matrix
- `final_metrics_plot.py` consuming `results/metrics.json`
- `gradcam.py` producing overlays stored under `results/gradcam/`

This is valuable because it highlights the research/clinical trust aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% View 1 — Workflow / Orchestration
  %% =======================

  subgraph "View 1: Offline ML Workflow (scripts + shared libs + filesystem artifacts)"
    direction TB

    subgraph "Inputs (Local/External Folders)"
      direction TB
      DATASET[/"dataset/ (image folders; train/val/test splits)"/]:::external
      TESTIMGS[/"test_images/ (demo/inference inputs)"/]:::external
    end

    subgraph "Runners (Entry-point Scripts)"
      direction TB
      MAIN["main.py (Training Orchestrator, PyTorch)"]:::entry
      EVAL["evaluate.py (Evaluation Runner)"]:::entry
      PRED["predict.py (Inference Runner)"]:::entry
      PLOT["final_metrics_plot.py (Reporting/Plotting Runner)"]:::entry
    end

    subgraph "Shared Libraries (Imported Modules)"
      direction TB

      subgraph "utils/ (Data + loops + metrics)"
        direction TB
        U_TRANS["utils/transforms.py (Preprocess + Augment)"]:::utils
        U_DATA["utils/dataset.py (Dataset + DataLoader)"]:::utils
        U_ENG["utils/engine.py (Train/Val Epoch Loops)"]:::utils
        U_MET["utils/metrics.py (F1/ROC-AUC/Confusion Matrix)"]:::utils
        U_INIT["utils/__init__.py (Package Exports)"]:::utilsMinor
      end

      subgraph "models/ (MSFT-Net)"
        direction TB
        M_MSFT["models/msftnet.py (MSFT-Net Model)"]:::model
        M_ECA["models/eca.py (ECA Attention)"]:::modelSub
        M_INIT["models/__init__.py (Package Exports)"]:::modelMinor
      end

      GC["gradcam.py (Grad-CAM Explainability Engine)"]:::xai
    end

    subgraph "Artifacts (Filesystem Integration Bus: results/ + logs)"
      direction TB
      WTS[("trained weights/checkpoints (.pth)")]:::artifact
      METJSON[("results/metrics.json (Canonical Metrics Artifact)")]:::artifact
      REVAL[("results/evaluation/ (ROC, confusion matrix, per-class outputs)")]:::artifact
      RPLOTS[("results/plots/ (figures/reports)")]:::artifact
      RGCAM[("results/gradcam/ (Grad-CAM overlay images)")]:::artifact
      LOGS[("Logs/ (optional training logs)")]:::artifactDim
    end

    %% ---- Runtime data / artifact flow (solid) ----
    DATASET -->|"images(PNG/JPG)"| U_TRANS
    U_TRANS -->|"tensors(C×H×W)"| U_DATA

    U_DATA -->|"batches(B×C×H×W)"| MAIN
    MAIN -->|"weights(.pth)"| WTS
    MAIN -->|"logs"| LOGS

    DATASET -->|"testsplit(images)"| U_DATA
    U_DATA -->|"batches"| EVAL
    WTS -->|"loadweights"| EVAL
    EVAL -->|"metrics(json)"| METJSON
    EVAL -->|"evaloutputs(files)"| REVAL

    METJSON -->|"readmetrics"| PLOT
    PLOT -->|"plots(figures)"| RPLOTS

    TESTIMGS -->|"images(PNG/JPG)"| PRED
    PRED -->|"preprocess"| U_TRANS
    WTS -->|"loadweights"| PRED
    PRED -->|"gradcaminputs(featuremaps+grads)"| GC
    GC -->|"heatmaps(overlayPNG)"| RGCAM

    %% ---- Code/module dependencies (dashed) ----
    MAIN -.->|"imports"| U_ENG
    MAIN -.->|"imports"| U_MET
    MAIN -.->|"imports"| M_MSFT
    MAIN -.->|"imports"| U_DATA
    MAIN -.->|"imports"| U_TRANS

    EVAL -.->|"imports"| U_DATA
    EVAL -.->|"imports"| U_MET
    EVAL -.->|"imports"| M_MSFT

    PRED -.->|"imports"| M_MSFT
    PRED -.->|"imports"| GC
    PRED -.->|"imports"| U_TRANS

    M_MSFT -.->|"uses"| M_ECA
    U_DATA -.->|"exports"| U_INIT
    M_MSFT -.->|"exports"| M_INIT
  end

  %% =======================
  %% View 2 — Model Internals (MSFT-Net)
  %% =======================

  subgraph "View 2: MSFT-Net Internal Architecture (models/msftnet.py)"
    direction TB

    IN["Input tensor (B×C×H×W)"]:::tensor
    BACKBONE["ResNet-50 Backbone (timm pretrained)\n(local feature extraction)"]:::model
    MSCALE["Multi-scale feature aggregation (C2–C5)\n(multi-resolution features)"]:::model
    ECAI["ECA Attention (models/eca.py)\n(channel recalibration)"]:::modelSub
    TR["Transformer Encoder\n(global context modeling)"]:::model
    HEAD["Pooling/Flatten + Classifier Head\n(3-class logits)"]:::model
    OUT["Output logits/softmax\n(3 stem types)"]:::tensor

    IN -->|"forward"| BACKBONE
    BACKBONE -->|"featuremaps"| MSCALE
    MSCALE -->|"reweightedfeatures"| ECAI
    ECAI -->|"sequence/embeddings"| TR
    TR -->|"contextfeatures"| HEAD
    HEAD -->|"logits"| OUT
  end

  %% =======================
  %% View 3 — Metrics + Explainability Subsystem
  %% =======================

  subgraph "View 3: Metrics + Reporting + Explainability"
    direction TB

    subgraph "Metrics/Reporting"
      direction TB
      METSYS["utils/metrics.py\n(F1 macro/weighted, ROC-AUC OVR, confusion matrix)"]:::utils
      EVALRUN["evaluate.py (runs test set)"]:::entry
      MJSON[("results/metrics.json")]:::artifact
      EFILES[("results/evaluation/")]:::artifact
      PLOTRUN["final_metrics_plot.py (builds figures)"]:::entry
      PFILES[("results/plots/")]:::artifact
      EVALRUN -->|"computemetrics"| METSYS
      METSYS -->|"write"| MJSON
      METSYS -->|"write"| EFILES
      MJSON -->|"consume"| PLOTRUN
      PLOTRUN -->|"write"| PFILES
    end

    subgraph "Explainability (XAI)"
      direction TB
      PRUN["predict.py (inference)"]:::entry
      GCE["gradcam.py (Grad-CAM engine)"]:::xai
      GCF[("results/gradcam/")]:::artifact
      PRUN -->|"calls"| GCE
      GCE -->|"writeoverlays"| GCF
    end
  end

  %% =======================
  %% External dependencies (footnote cluster)
  %% =======================
  subgraph "External Dependencies (Libraries)"
    direction TB
    TORCH["PyTorch"]:::dep
    TIMM["timm/torchvision (pretrained backbones)"]:::dep
    SK["scikit-learn (metrics)"]:::dep
    CV["OpenCV (image I/O; overlays)"]:::dep
    MPL["matplotlib/seaborn (plots)"]:::dep
    NP["NumPy"]:::dep
    AUG["albumentations/torchvision transforms"]:::dep
  end

  %% Light-touch dependency hints
  U_MET -.->|"uses"| SK
  M_MSFT -.->|"uses"| TORCH
  M_MSFT -.->|"uses"| TIMM
  U_TRANS -.->|"uses"| AUG
  GC -.->|"uses"| CV
  PLOT -.->|"uses"| MPL
  U_DATA -.->|"uses"| NP

  %% =======================
  %% Click events (from component_mapping)
  %% =======================
  click MAIN "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/main.py"
  click EVAL "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/evaluate.py"
  click PRED "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/predict.py"
  click PLOT "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/final_metrics_plot.py"
  click GC "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/gradcam.py"

  click U_DATA "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/utils/dataset.py"
  click U_TRANS "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/utils/transforms.py"
  click U_ENG "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/utils/engine.py"
  click U_MET "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/utils/metrics.py"
  click U_INIT "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/utils/__init__.py"

  click M_MSFT "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/models/msftnet.py"
  click M_ECA "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/models/eca.py"
  click M_INIT "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/models/__init__.py"

  click METJSON "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/blob/experiment-eca/results/metrics.json"
  click REVAL "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/tree/experiment-eca/results/evaluation/"
  click RPLOTS "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/tree/experiment-eca/results/plots/"
  click RGCAM "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/tree/experiment-eca/results/gradcam/"
  click TESTIMGS "https://github.com/rogerjaden/deep-hybrid-model-for-classification-of-femoral-stem/tree/experiment-eca/test_images/"

  %% =======================
  %% Styles
  %% =======================
  classDef entry fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
  classDef utils fill:#fb8c00,stroke:#e65100,color:#111111,stroke-width:1.3px
  classDef utilsMinor fill:#ffcc80,stroke:#ef6c00,color:#111111,stroke-width:1px
  classDef model fill:#43a047,stroke:#1b5e20,color:#ffffff,stroke-width:1.5px
  classDef modelSub fill:#81c784,stroke:#1b5e20,color:#111111,stroke-width:1.2px
  classDef modelMinor fill:#c5e1a5,stroke:#1b5e20,color:#111111,stroke-width:1px
  classDef xai fill:#8e24aa,stroke:#4a148c,color:#ffffff,stroke-width:1.5px
  classDef artifact fill:#90a4ae,stroke:#37474f,color:#111111,stroke-width:1.3px
  classDef artifactDim fill:#cfd8dc,stroke:#607d8b,color:#111111,stroke-width:1px
  classDef external fill:#7e57c2,stroke:#311b92,color:#ffffff,stroke-width:1.4px
  classDef tensor fill:#26a69a,stroke:#004d40,color:#ffffff,stroke-width:1.2px
  classDef dep fill:#eeeeee,stroke:#616161,color:#111111,stroke-width:1px,stroke-dasharray: 4 3
```
