ckd-detection: NephroScan, the CKD detector that tries to behave like a clinical tool, not a notebook
A Flask and React pipeline turns an imbalanced kidney dataset into risk scores, stage estimates, and a visual fingerprint of renal health.
- NephroScan is strongest as a productization example, because it turns a brittle clinical dataset into a workflow with risk, staging, and history.
- Its ML pipeline gets the dangerous parts right by splitting before preprocessing, applying SMOTENC only to training data, and selecting models by F1 rather than vanity accuracy.
- The frontend matters as much as the model, because the kidney radar and risk UI translate lab values into a shape a non-specialist can read quickly.
- The repo feels credible, but it still reads like a prototype because it lacks deeper explainability tooling and shows signs of repo hygiene gaps.
The CKD app that acts like a workflow, not a form
The first thing NephroScan gets right is the experience. It does not stop at a yes-or-no prediction. It returns a risk level, a stage estimate, a visual readout, and saved history for logged-in users, which makes it feel closer to clinical decision support than a demo classifier.
This project focuses on predicting chronic kidney disease (CKD) using machine learning techniques. The goal is to assist in early detection by analyzing patient medical data and identifying patterns associated with chronic disease risk.
That framing matters. A lot of CKD repos can predict one label. Far fewer build a loop that helps a user enter incomplete values, understand the output, and preserve the result in a way that feels operational.
Why CKD detection is a nasty machine learning problem
CKD prediction is not a clean benchmark problem. The dataset is small, the classes are imbalanced, and the features mix continuous lab values with binary clinical markers. That combination is where many hobby ML projects quietly fall apart.
The repo treats that problem like a production constraint, not an academic footnote. It uses SMOTENC so the oversampling step respects mixed feature types, and it splits data before any scaling so test leakage does not inflate the result.
The model pipeline is quietly doing the right things
The training flow is the technical center of gravity. The code compares Logistic Regression, Random Forest, SVM, and XGBoost, then ranks them by F1 score. That choice is telling. In a disease setting, F1 is a better signal than raw accuracy because the class balance is not your friend.
| Stage | What it does | Why it matters |
|---|---|---|
| Train/test split | Separates raw data before preprocessing | Prevents leakage from the test set |
| Median imputation | Fills missing values from the training data profile | Keeps the model usable on incomplete input |
| SMOTENC | Oversamples the minority class with mixed feature awareness | Addresses imbalance without flattening binary markers |
| F1 ranking | Compares models on the balance of precision and recall | Rewards better disease detection behavior |
This is the part that makes the project feel more serious than a typical UCI dataset clone. The code is not trying to impress with one giant model. It is trying to avoid obvious mistakes, then choose the best performing candidate in a disciplined way.
The backend turns a saved model into a resilient service
`app.py` is the bridge between the pickle file and the user-facing product. It loads the model, computes feature medians at startup, and uses those medians when the input is incomplete. That keeps the app usable without forcing the user to understand the dataset behind it.
The persistence layer is practical too. Authenticated users can save prediction history, and the result payload is flexible enough to evolve. That matters in a medical tool, where output fields often change as the model or product matures.
The backend is not elegant for elegance's sake. It is doing the boring work that makes inference feel like a service instead of a script.
The frontend does the translation from lab values to a visual story
The frontend is where NephroScan stops looking like machine learning infrastructure and starts looking like a clinical interface. `Predict.js` combines a kidney radar chart, risk gauges, a BMI helper, and report generation so the user sees more than a raw probability.
That matters because medical numbers are hard to scan in isolation. A creatinine level or GFR reading is useful, but a radial chart makes the pattern legible at a glance. The UI is not decorative. It is doing interpretive work.
The report export is another product signal. It suggests the app expects the result to leave the browser and become part of a real workflow, not just a one-off prediction screen.
How this compares to other CKD repos
| Repo type | Strength | Weakness | Where NephroScan sits |
|---|---|---|---|
| Basic UCI classifier | Easy to build and easy to understand | Often ends at a notebook or minimal form | More complete as a product |
| Ensemble plus SHAP project | Stronger explainability and often better modeling depth | Can feel heavier and less workflow-focused | Less explainable, but cleaner UX |
| Research-first CKD study | Better validation and clinical credibility | Less deployable as an app | Less rigorous, more approachable |
| NephroScan | Balanced end-to-end product flow | Not a benchmark leader or explainability showcase | A strong prototype with product instincts |
So the judgment is not that NephroScan is the most advanced CKD model. It is that the repo is unusually coherent. It handles imbalance, inference, persistence, and visualization as one system, which is rarer than it should be.
What NephroScan gets right, and what keeps it in prototype territory
The repo shows real judgment in the places that usually get ignored. It avoids leakage, respects mixed feature types, and presents its output in a way that a human could actually use.
But it is still a prototype. The repository hygiene is not perfect, with committed dependencies visible in the tree, and the app does not lean on explainability tools like SHAP or LIME. Those are not fatal flaws. They are the difference between a solid demo and a mature clinical system.
That is why NephroScan is worth noticing. It is not trying to win the machine learning leaderboard. It is trying to make a medical classifier feel operational, and that is a harder engineering problem than it looks.