How nikonpic/bonetumornet works
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)