visionkit-pro 0.1.2__tar.gz

visionkit_pro-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hideaki Mizoue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

visionkit_pro-0.1.2/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: visionkit_pro
+Version: 0.1.2
+Summary: Reusable training, evaluation, and Grad-CAM utilities for CSV-backed image classification.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: pillow>=9.0
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: torch>=2.0
+Requires-Dist: torchvision>=0.15
+Requires-Dist: tqdm>=4.64
+Dynamic: license-file
+
+# visionkit
+
+<p align="center">
+  <img src="doc/image/image.png" width="900">
+</p>
+
+`visionkit` is a small PyTorch package for image-classification projects where
+image metadata is stored in a CSV file and the image files live in a directory.
+It provides a reusable workflow for training, evaluation, prediction tables, and
+Grad-CAM visualization.
+
+It turns the notebook workflow into a package that can be reused with different
+CSV files and image folders:
+
+- Load image filenames, labels, and train/validation splits from a CSV
+- Train torchvision models such as EfficientNet or ResNet
+- Save checkpoints, training logs, prediction CSVs, and metric CSVs
+- Generate Grad-CAM heatmaps and overlay images
+
+## Quick Start
+
+Prepare an image directory and a CSV file.
+
+```text
+your_project/
+  data/
+    images/
+      case001.png
+      case002.png
+      case003.png
+    meta.csv
+  outputs/
+```
+
+The minimal `meta.csv` should look like this:
+
+```csv
+filename,label,split
+case001.png,F,train
+case002.png,N,train
+case003.png,F,validation
+case004.png,N,validation
+```
+
+Train a model:
+
+```bash
+visionkit train \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --classes F N \
+  --positive-class N \
+  --epochs 30
+```
+
+Evaluate the validation split:
+
+```bash
+visionkit evaluate \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --checkpoint outputs/experiment_001/models/best.pt \
+  --classes F N \
+  --positive-class N \
+  --split validation
+```
+
+Generate Grad-CAM overlays:
+
+```bash
+visionkit gradcam \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --checkpoint outputs/experiment_001/models/best.pt \
+  --classes F N \
+  --positive-class N \
+  --split validation \
+  --target-class N
+```
+
+## Required CSV
+
+For CLI training, the CSV usually needs these three columns.
+
+| column | required | example | meaning |
+| --- | --- | --- | --- |
+| `filename` | yes | `case001.png` | Image path relative to `--image-dir` |
+| `label` | yes | `F` / `N` | Class label |
+| `split` | yes | `train` / `validation` | Which split the row belongs to |
+
+The default column names are `filename`, `label`, and `split`. If your CSV uses
+different names, pass them explicitly:
+
+```bash
+visionkit train \
+  --csv data/metadata.csv \
+  --image-dir data/fig \
+  --output-dir outputs/run_001 \
+  --filename-column image_name \
+  --label-column diagnosis \
+  --split-column fixed_family_level_split \
+  --train-split train \
+  --val-split validation
+```
+
+Extra CSV columns are allowed. Columns such as `patient_id`, `family_id`, or
+`age` are carried through into the prediction CSVs.
+
+```csv
+filename,label,split,patient_id,family_id
+case001.png,F,train,P001,A
+case002.png,N,train,P002,B
+case003.png,F,validation,P003,C
+```
+
+## Image Paths
+
+`filename` is interpreted as a path relative to `--image-dir`.
+
+If all images are in the same folder:
+
+```csv
+filename,label,split
+case001.png,F,train
+case002.png,N,validation
+```
+
+If images are stored in subfolders, include the subfolder in `filename`:
+
+```csv
+filename,label,split
+train/case001.png,F,train
+validation/case002.png,N,validation
+```
+
+This expects files like:
+
+```text
+data/images/train/case001.png
+data/images/validation/case002.png
+```
+
+## Classes And Positive Class
+
+For binary classification, the order of `--classes` defines the class indices.
+
+```bash
+--classes F N
+```
+
+This means:
+
+- `F` is class 0
+- `N` is class 1
+
+If you want AUC, sensitivity, specificity, and PR-AUC to use a specific positive
+class, set it explicitly:
+
+```bash
+--positive-class N
+```
+
+If `--classes` is omitted, class names are inferred from the labels in the CSV.
+For reproducible research or paper figures, it is better to pass `--classes`
+explicitly because class order affects the numeric labels and positive class.
+
+## Outputs
+
+With `--output-dir outputs/experiment_001`, the package creates files like:
+
+```text
+outputs/experiment_001/
+  models/
+    best.pt
+    epoch_001.pt
+    epoch_002.pt
+  logs/
+    training_history.csv
+  predictions/
+    validation_predictions.csv
+    validation_predictions_metrics.csv
+    gradcam_validation.csv
+    gradcam_validation_metrics.csv
+  gradcam/
+    validation/
+      case001__pred-N.png
+```
+
+By default, `best.pt` is the checkpoint from the epoch with the best `val_auc`.
+
+## Common Commands
+
+Use a torchvision model other than EfficientNet-B3:
+
+```bash
+visionkit train \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/resnet50_run \
+  --architecture resnet50 \
+  --image-size 224x224 \
+  --classes F N \
+  --positive-class N
+```
+
+Use a CSV layout similar to the original notebook:
+
+```bash
+visionkit train \
+  --csv train_val/data/meta/fixed/fixed_family_level_split.csv \
+  --image-dir train_val/data/fig \
+  --output-dir train_val/review_outputs/family_level_split_efficientnetb3_seed123 \
+  --filename-column filename \
+  --label-column label \
+  --split-column fixed_family_level_split \
+  --train-split train \
+  --val-split validation \
+  --classes F N \
+  --positive-class N \
+  --architecture efficientnet_b3 \
+  --image-size 300x300
+```
+
+## Python API
+
+```python
+from pathlib import Path
+
+from visionkit.config import ExperimentConfig
+from visionkit.pipeline import run_training, run_evaluation, run_gradcam
+
+config = ExperimentConfig(
+    csv_path=Path("data/meta.csv"),
+    image_dir=Path("data/images"),
+    output_dir=Path("outputs/experiment_001"),
+    class_names=["F", "N"],
+    positive_class="N",
+    split_column="split",
+    train_split="train",
+    val_split="validation",
+    architecture="efficientnet_b3",
+    image_size=(300, 300),
+    epochs=30,
+)
+
+model, history = run_training(config)
+
+predictions, metrics = run_evaluation(
+    config,
+    checkpoint_path=config.output_dir / "models" / "best.pt",
+    split_name="validation",
+)
+
+gradcam_results, gradcam_metrics = run_gradcam(
+    config,
+    checkpoint_path=config.output_dir / "models" / "best.pt",
+    split_name="validation",
+    target_class="N",
+)
+```
+
+## Install
+
+Use the package locally in editable mode:
+
+```bash
+pip install -e .
+```
+
+If PyTorch is not installed yet, install `torch` and `torchvision` first using
+the command appropriate for your CPU or CUDA environment.

visionkit_pro-0.1.2/README.md

@@ -0,0 +1,274 @@
+# visionkit
+
+<p align="center">
+  <img src="doc/image/image.png" width="900">
+</p>
+
+`visionkit` is a small PyTorch package for image-classification projects where
+image metadata is stored in a CSV file and the image files live in a directory.
+It provides a reusable workflow for training, evaluation, prediction tables, and
+Grad-CAM visualization.
+
+It turns the notebook workflow into a package that can be reused with different
+CSV files and image folders:
+
+- Load image filenames, labels, and train/validation splits from a CSV
+- Train torchvision models such as EfficientNet or ResNet
+- Save checkpoints, training logs, prediction CSVs, and metric CSVs
+- Generate Grad-CAM heatmaps and overlay images
+
+## Quick Start
+
+Prepare an image directory and a CSV file.
+
+```text
+your_project/
+  data/
+    images/
+      case001.png
+      case002.png
+      case003.png
+    meta.csv
+  outputs/
+```
+
+The minimal `meta.csv` should look like this:
+
+```csv
+filename,label,split
+case001.png,F,train
+case002.png,N,train
+case003.png,F,validation
+case004.png,N,validation
+```
+
+Train a model:
+
+```bash
+visionkit train \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --classes F N \
+  --positive-class N \
+  --epochs 30
+```
+
+Evaluate the validation split:
+
+```bash
+visionkit evaluate \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --checkpoint outputs/experiment_001/models/best.pt \
+  --classes F N \
+  --positive-class N \
+  --split validation
+```
+
+Generate Grad-CAM overlays:
+
+```bash
+visionkit gradcam \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/experiment_001 \
+  --checkpoint outputs/experiment_001/models/best.pt \
+  --classes F N \
+  --positive-class N \
+  --split validation \
+  --target-class N
+```
+
+## Required CSV
+
+For CLI training, the CSV usually needs these three columns.
+
+| column | required | example | meaning |
+| --- | --- | --- | --- |
+| `filename` | yes | `case001.png` | Image path relative to `--image-dir` |
+| `label` | yes | `F` / `N` | Class label |
+| `split` | yes | `train` / `validation` | Which split the row belongs to |
+
+The default column names are `filename`, `label`, and `split`. If your CSV uses
+different names, pass them explicitly:
+
+```bash
+visionkit train \
+  --csv data/metadata.csv \
+  --image-dir data/fig \
+  --output-dir outputs/run_001 \
+  --filename-column image_name \
+  --label-column diagnosis \
+  --split-column fixed_family_level_split \
+  --train-split train \
+  --val-split validation
+```
+
+Extra CSV columns are allowed. Columns such as `patient_id`, `family_id`, or
+`age` are carried through into the prediction CSVs.
+
+```csv
+filename,label,split,patient_id,family_id
+case001.png,F,train,P001,A
+case002.png,N,train,P002,B
+case003.png,F,validation,P003,C
+```
+
+## Image Paths
+
+`filename` is interpreted as a path relative to `--image-dir`.
+
+If all images are in the same folder:
+
+```csv
+filename,label,split
+case001.png,F,train
+case002.png,N,validation
+```
+
+If images are stored in subfolders, include the subfolder in `filename`:
+
+```csv
+filename,label,split
+train/case001.png,F,train
+validation/case002.png,N,validation
+```
+
+This expects files like:
+
+```text
+data/images/train/case001.png
+data/images/validation/case002.png
+```
+
+## Classes And Positive Class
+
+For binary classification, the order of `--classes` defines the class indices.
+
+```bash
+--classes F N
+```
+
+This means:
+
+- `F` is class 0
+- `N` is class 1
+
+If you want AUC, sensitivity, specificity, and PR-AUC to use a specific positive
+class, set it explicitly:
+
+```bash
+--positive-class N
+```
+
+If `--classes` is omitted, class names are inferred from the labels in the CSV.
+For reproducible research or paper figures, it is better to pass `--classes`
+explicitly because class order affects the numeric labels and positive class.
+
+## Outputs
+
+With `--output-dir outputs/experiment_001`, the package creates files like:
+
+```text
+outputs/experiment_001/
+  models/
+    best.pt
+    epoch_001.pt
+    epoch_002.pt
+  logs/
+    training_history.csv
+  predictions/
+    validation_predictions.csv
+    validation_predictions_metrics.csv
+    gradcam_validation.csv
+    gradcam_validation_metrics.csv
+  gradcam/
+    validation/
+      case001__pred-N.png
+```
+
+By default, `best.pt` is the checkpoint from the epoch with the best `val_auc`.
+
+## Common Commands
+
+Use a torchvision model other than EfficientNet-B3:
+
+```bash
+visionkit train \
+  --csv data/meta.csv \
+  --image-dir data/images \
+  --output-dir outputs/resnet50_run \
+  --architecture resnet50 \
+  --image-size 224x224 \
+  --classes F N \
+  --positive-class N
+```
+
+Use a CSV layout similar to the original notebook:
+
+```bash
+visionkit train \
+  --csv train_val/data/meta/fixed/fixed_family_level_split.csv \
+  --image-dir train_val/data/fig \
+  --output-dir train_val/review_outputs/family_level_split_efficientnetb3_seed123 \
+  --filename-column filename \
+  --label-column label \
+  --split-column fixed_family_level_split \
+  --train-split train \
+  --val-split validation \
+  --classes F N \
+  --positive-class N \
+  --architecture efficientnet_b3 \
+  --image-size 300x300
+```
+
+## Python API
+
+```python
+from pathlib import Path
+
+from visionkit.config import ExperimentConfig
+from visionkit.pipeline import run_training, run_evaluation, run_gradcam
+
+config = ExperimentConfig(
+    csv_path=Path("data/meta.csv"),
+    image_dir=Path("data/images"),
+    output_dir=Path("outputs/experiment_001"),
+    class_names=["F", "N"],
+    positive_class="N",
+    split_column="split",
+    train_split="train",
+    val_split="validation",
+    architecture="efficientnet_b3",
+    image_size=(300, 300),
+    epochs=30,
+)
+
+model, history = run_training(config)
+
+predictions, metrics = run_evaluation(
+    config,
+    checkpoint_path=config.output_dir / "models" / "best.pt",
+    split_name="validation",
+)
+
+gradcam_results, gradcam_metrics = run_gradcam(
+    config,
+    checkpoint_path=config.output_dir / "models" / "best.pt",
+    split_name="validation",
+    target_class="N",
+)
+```
+
+## Install
+
+Use the package locally in editable mode:
+
+```bash
+pip install -e .
+```
+
+If PyTorch is not installed yet, install `torch` and `torchvision` first using
+the command appropriate for your CPU or CUDA environment.

visionkit_pro-0.1.2/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "visionkit_pro"
+version = "0.1.2"
+description = "Reusable training, evaluation, and Grad-CAM utilities for CSV-backed image classification."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "matplotlib>=3.7",
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "pillow>=9.0",
+    "scikit-learn>=1.2",
+    "torch>=2.0",
+    "torchvision>=0.15",
+    "tqdm>=4.64",
+]
+
+[project.scripts]
+visionkit = "visionkit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

visionkit_pro-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

visionkit_pro-0.1.2/src/visionkit/__init__.py

@@ -0,0 +1,23 @@
+"""Reusable image-classification training, evaluation, and Grad-CAM tools."""
+
+from visionkit.config import ExperimentConfig
+from visionkit.data import CSVImageDataset, build_dataloaders, build_transforms
+from visionkit.gradcam import GradCAM, generate_gradcam_report
+from visionkit.models import build_model, load_checkpoint
+from visionkit.pipeline import run_evaluation, run_gradcam, run_training
+from visionkit.train import train_model
+
+__all__ = [
+    "CSVImageDataset",
+    "ExperimentConfig",
+    "GradCAM",
+    "build_dataloaders",
+    "build_model",
+    "build_transforms",
+    "generate_gradcam_report",
+    "load_checkpoint",
+    "run_evaluation",
+    "run_gradcam",
+    "run_training",
+    "train_model",
+]