Kidney CT Classifier (DenseNet121)

Classifies a kidney CT slice into one of four classes: Cyst, Normal, Stone, Tumor.

The trained weights (~1 GB) are too large for GitHub, so they are hosted on the Hugging Face Hub:

FarhanKO/kidney-ct-classifier

These models are the image half of the kidney module in Disease-Risk-Prediction (kidney/image_based/). In the repo, this folder holds only this README, the OOD gate (kidney_ct_ood_detector.joblib) and metadata.json; the .keras files are git-ignored.

Research and education only. This is not a medical device. It was trained on 123 CT scans from hospitals in one city and must not be used for diagnosis or treatment decisions.

Quick start (no GitHub code needed)

pip install -r requirements.txt     # keras 3, torch, scikit-learn, numpy, pillow, huggingface_hub

from huggingface_hub import hf_hub_download
import importlib.util

REPO_ID = "FarhanKO/kidney-ct-classifier"
spec = importlib.util.spec_from_file_location("inference", hf_hub_download(REPO_ID, "inference.py"))
inference = importlib.util.module_from_spec(spec); spec.loader.exec_module(inference)

clf = inference.KidneyCTClassifier(REPO_ID)     # downloads metadata, OOD gate and DenseNet121_FT (~90 MB)
clf.predict("slice.png")
# {'status': 'accepted', 'label': 'Cyst', 'confidence': 0.943, 'p_abnormal': 0.988,
#  'probabilities': {'Cyst': 0.943, 'Normal': 0.012, 'Stone': 0.019, 'Tumor': 0.026}}

Or from the command line (--ensemble soft-votes the four fine-tuned models):

python inference.py slice1.png slice2.jpg --repo FarhanKO/kidney-ct-classifier

status is accepted (top-class probability ≥ 0.75), review (below 0.75: flag for a clinician) or rejected (the OOD gate says this is not a kidney CT slice; it is not classified). On the full test split, inference.py reproduces the notebook exactly: accuracy 0.8942, 3.64 % of slices rejected by the gate.

The OOD gate is a scikit-learn object saved with joblib, which is a pickle: load it only from a source you trust, and use scikit-learn 1.8 (pinned in requirements.txt).

Download into the GitHub repo

To use the full pipeline (with Grad-CAM) from a clone of the GitHub repo, put the files in this folder, where src/predict.py looks for them:

pip install huggingface_hub

from huggingface_hub import snapshot_download

# Everything (~1 GB): all nine checkpoints + gate + metadata
snapshot_download("FarhanKO/kidney-ct-classifier", local_dir="models")

# Only what the deployed cascade needs (~90 MB)
snapshot_download("FarhanKO/kidney-ct-classifier", local_dir="models",
                  allow_patterns=["DenseNet121_FT_best.keras", "kidney_ct_ood_detector.joblib", "metadata.json"])

Then, from kidney/image_based/:

python -m src.predict --image slice.png --heatmap-dir out/
python -m src.evaluate      # must reproduce the test metrics in metadata.json

Using a checkpoint directly

import os; os.environ["KERAS_BACKEND"] = "torch"   # before importing keras; trained on the torch backend
import keras
model = keras.models.load_model("DenseNet121_FT_best.keras", compile=False)
probs = model.predict(x)   # x: (N, 224, 224, 3) float32 in 0-255; classes in metadata.json order

Input preprocessing (the same as load_image() in src/data.py): grayscale → pad to square with black → resize to 224 × 224 (PIL BOX) → repeat to 3 channels → float32 in 0–255. Do not divide by 255: every model rescales its input internally.

Files

Every .keras file takes a (N, 224, 224, 3) input and outputs softmax probabilities for the 4 classes, in the order Cyst, Normal, Stone, Tumor.

How the cascade uses them

Training data

CT KIDNEY DATASET: Normal-Cyst-Tumor and Stone (Islam et al., Scientific Reports 2022; Kaggle nazmul0087/ct-kidney-dataset-normal-cyst-tumor-and-stone), collected from hospital PACS in Dhaka, Bangladesh.

The 12,446 published images are consecutive slices of about 189 CT scans. 517 exact duplicates were removed, and the data was split by scan, so no scan appears in more than one split:

A random image split would leak near-identical neighbouring slices: a memorising 1-nearest-neighbour classifier scores 100 % on it, against 45 % on this split. The build script and a full manifest are in the GitHub repo under kidney/image_based/data/ (see its README.md).

Training

• Framework: Keras 3 on the PyTorch backend (TensorFlow has no GPU support on native Windows), trained on an RTX 5060 (8 GB). Seed 42.
• Backbones: ImageNet-pretrained ResNet50V2, EfficientNetV2B0, DenseNet121 and ConvNeXtTiny from Keras Applications, each applying its own input scaling, plus a small from-scratch CNN.
• Phase 1: 5-epoch head warm-up with the backbone frozen.
• Phase 2 (_FT): full fine-tuning of every layer, with BatchNorm frozen. AdamW (lr 3e-5, weight decay 0.05), label smoothing 0.1, class weights, and CT-safe augmentation (small rotation, zoom and translation; no flips).
• Model selection: highest validation macro-F1, then lowest validation loss. The test set was not used for selection.

Results

Held-out test set: 1,787 slices from 36 scans never seen in training.

Scan-level 95 % bootstrap CIs for the deployed model: accuracy 0.82–0.96, macro-F1 0.70–0.91.

Per class, deployed model, test set:

Confidence check (0.75): 81 % of test slices are accepted, and 96.3 % of those are correct. The 19 % sent to review are 59.6 % correct.

OOD gate: rejects 3.6 % of real test slices, and 100 % of random noise, black images, grey speckle, chest X-rays and ECG printouts.

The ensemble is not deployed: it scores lower on validation (0.868 vs 0.889), and its tumor recall drops to 0.50.

Limitations

• Few independent scans. Only 4 tumor scans each in val and test, so per-class tumor numbers move a lot with one scan. Tumor recall (0.66) is the weakest point.
• Acquisition shortcuts. Body brightness differs by class (contrast phase, display window), and Grad-CAM often spreads over the central abdomen and spine, so part of the signal may be how the scan was taken.
• One source, one format. All scans come from Dhaka hospitals, exported as windowed JPEGs, not Hounsfield-unit DICOM. Other scanners and windows are untested and may be rejected by the gate.
• Single label per slice, and scans were grouped from image similarity because the dataset has no patient IDs.

Citation

If you use these models, please cite the dataset paper:

Islam, M. N., Hasan, M., et al. "Vision transformer and explainable transfer learning models for auto detection of kidney cyst, stone and tumor from CT-radiography." Scientific Reports 12, 11440 (2022).

Check the dataset's licence on its Kaggle page and set the model licence to match before publishing (the license: other field above).