image-classification-tools 0.5.6__py3-none-any.whl

image_classification_tools/pytorch/training.py

@@ -0,0 +1,256 @@
+'''Training functions for models.'''
+
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader
+
+
+def train_one_epoch(model, data_loader, criterion, optimizer, device, lazy_loading=False, cyclic_scheduler=None, history=None):
+    '''Run one training epoch, tracking metrics per batch.
+    
+    Args:
+        model: PyTorch model to train
+        data_loader: Training data loader
+        criterion: Loss function
+        optimizer: Optimizer
+        device: Device for training (e.g., 'cuda' or 'cpu')
+        lazy_loading: If True, move batches to device during training. If False,
+                     assumes data is already on device (default: False)
+        cyclic_scheduler: Optional CyclicLR scheduler to step after each batch
+        history: Optional history dictionary to record batch-level metrics
+    
+    Returns:
+        Tuple of (average_loss, accuracy_percentage) for the epoch
+    '''
+
+    model.train()
+    running_loss = 0.0
+    correct = 0
+    total = 0
+    
+    for _, (images, labels) in enumerate(data_loader):
+        if lazy_loading:
+            images, labels = images.to(device), labels.to(device)
+        
+        optimizer.zero_grad()
+        outputs = model(images)
+        loss = criterion(outputs, labels)
+        loss.backward()
+        optimizer.step()
+        
+        # Step cyclic scheduler after each batch
+        if cyclic_scheduler is not None:
+            cyclic_scheduler.step()
+        
+        # Track batch-level metrics
+        batch_loss = loss.item()
+        _, predicted = torch.max(outputs, 1)
+        batch_correct = (predicted == labels).sum().item()
+        batch_total = labels.size(0)
+        batch_acc = 100 * batch_correct / batch_total
+        
+        # Record batch metrics if history is provided
+        if history is not None:
+            history['batch_train_loss'].append(batch_loss)
+            history['batch_train_accuracy'].append(batch_acc)
+            history['batch_learning_rates'].append(optimizer.param_groups[0]['lr'])
+            
+            if cyclic_scheduler is not None:
+                history['batch_base_lrs'].append(cyclic_scheduler.base_lrs[0])
+                history['batch_max_lrs'].append(cyclic_scheduler.max_lrs[0])
+        
+        running_loss += batch_loss
+        correct += batch_correct
+        total += batch_total
+    
+    return running_loss / len(data_loader), 100 * correct / total
+
+
+def evaluate(model, data_loader, criterion, device, lazy_loading=False):
+    '''Evaluate model on a dataset.
+    
+    Args:
+        model: PyTorch model to evaluate
+        data_loader: Data loader (validation or test set)
+        criterion: Loss function
+        device: Device for evaluation (e.g., 'cuda' or 'cpu')
+        lazy_loading: If True, move batches to device during evaluation. If False,
+                     assumes data is already on device (default: False)
+    
+    Returns:
+        Tuple of (average_loss, accuracy_percentage) for the dataset
+    '''
+
+    model.eval()
+    running_loss = 0.0
+    correct = 0
+    total = 0
+    
+    with torch.no_grad():
+        for images, labels in data_loader:
+            if lazy_loading:
+                images, labels = images.to(device), labels.to(device)
+            
+            outputs = model(images)
+            loss = criterion(outputs, labels)
+            
+            running_loss += loss.item()
+            _, predicted = torch.max(outputs, 1)
+            total += labels.size(0)
+            correct += (predicted == labels).sum().item()
+    
+    return running_loss / len(data_loader), 100 * correct / total
+
+
+def train_model(
+    model: nn.Module,
+    train_loader: DataLoader,
+    val_loader: DataLoader = None,
+    criterion: nn.Module = None,
+    optimizer: optim.Optimizer = None,
+    device: torch.device = None,
+    lazy_loading: bool = False,
+    cyclic_scheduler = None,
+    epoch_scheduler = None,
+    lr_schedule: dict = None,
+    epochs: int = 10,
+    enable_early_stopping: bool = False,
+    early_stopping_patience: int = 10,
+    print_every: int = 1
+) -> dict[str, list[float]]:
+    '''Training loop with optional validation and early stopping.
+    
+    Tracks metrics at both batch and epoch levels.
+    
+    Args:
+        model: PyTorch model to train
+        train_loader: Training data loader
+        val_loader: Validation data loader (None for training without validation)
+        criterion: Loss function
+        optimizer: Optimizer
+        device: Device for training (e.g., 'cuda' or 'cpu')
+        lazy_loading: If True, move batches to device during training. If False,
+                     assumes data is already on device (default: False)
+        cyclic_scheduler: CyclicLR scheduler (steps per batch)
+        epoch_scheduler: Epoch-based scheduler like ReduceLROnPlateau (steps per epoch)
+        lr_schedule: Optional dict with scheduled LR bounds reduction:
+                    {'initial_base_lr', 'initial_max_lr', 'final_base_lr', 
+                     'final_max_lr', 'schedule_epochs'}
+        epochs: Maximum number of epochs
+        enable_early_stopping: Whether to enable early stopping (default: False)
+        early_stopping_patience: Stop if val_loss doesn't improve for this many epochs
+                                (only used if enable_early_stopping=True and val_loader is not None)
+        print_every: Print progress every N epochs
+    
+    Returns:
+        Dictionary containing training history with epoch and batch-level metrics
+    '''
+
+    history = {
+        # Epoch-level metrics
+        'train_loss': [], 'val_loss': [],
+        'train_accuracy': [], 'val_accuracy': [],
+        'learning_rates': [],
+        'base_lrs': [],
+        'max_lrs': [],
+        
+        # Batch-level metrics
+        'batch_train_loss': [],
+        'batch_train_accuracy': [],
+        'batch_learning_rates': [],
+        'batch_base_lrs': [],
+        'batch_max_lrs': []
+    }
+    
+    best_val_loss = float('inf')
+    epochs_without_improvement = 0
+    best_model_state = None
+
+    for epoch in range(epochs):
+
+        # Train and validate (now passing history to track batch metrics)
+        train_loss, train_acc = train_one_epoch(model, train_loader, criterion, optimizer, device, lazy_loading, cyclic_scheduler, history)
+        
+        # Only evaluate on validation set if provided
+        if val_loader is not None:
+            val_loss, val_acc = evaluate(model, val_loader, criterion, device, lazy_loading)
+        else:
+            val_loss, val_acc = None, None
+        
+        # Record epoch-level metrics
+        history['train_loss'].append(train_loss)
+        history['val_loss'].append(val_loss if val_loss is not None else float('nan'))
+        history['train_accuracy'].append(train_acc)
+        history['val_accuracy'].append(val_acc if val_acc is not None else float('nan'))
+        history['learning_rates'].append(optimizer.param_groups[0]['lr'])
+        
+        # Record base and max LR if using cyclic scheduler
+        if cyclic_scheduler is not None:
+            history['base_lrs'].append(cyclic_scheduler.base_lrs[0])
+            history['max_lrs'].append(cyclic_scheduler.max_lrs[0])
+        
+        # Early stopping (only if validation data is provided and early stopping is enabled)
+        if enable_early_stopping and val_loader is not None and val_loss is not None:
+            if val_loss < best_val_loss:
+                best_val_loss = val_loss
+                epochs_without_improvement = 0
+                best_model_state = {k: v.cpu().clone() for k, v in model.state_dict().items()}
+            else:
+                epochs_without_improvement += 1
+        
+        # Update LR bounds based on schedule
+        if lr_schedule is not None and cyclic_scheduler is not None and epoch < lr_schedule['schedule_epochs']:
+            # Linear interpolation of base and max LR
+            progress = (epoch + 1) / lr_schedule['schedule_epochs']
+            new_base_lr = lr_schedule['initial_base_lr'] * (1 - progress) + lr_schedule['final_base_lr'] * progress
+            new_max_lr = lr_schedule['initial_max_lr'] * (1 - progress) + lr_schedule['final_max_lr'] * progress
+            
+            # Update the cyclic scheduler's base and max LRs
+            cyclic_scheduler.base_lrs = [new_base_lr]
+            cyclic_scheduler.max_lrs = [new_max_lr]
+        
+        # Step epoch-based scheduler (e.g., ReduceLROnPlateau)
+        if epoch_scheduler is not None:
+            if val_loader is not None and val_loss is not None:
+                # ReduceLROnPlateau needs a metric
+                if hasattr(epoch_scheduler, 'step') and 'metrics' in epoch_scheduler.step.__code__.co_varnames:
+                    epoch_scheduler.step(val_loss)
+                else:
+                    epoch_scheduler.step()
+            else:
+                epoch_scheduler.step()
+        
+        # Print progress
+        if (epoch + 1) % print_every == 0 or epoch == 0:
+            # Only show LR info if a scheduler is being used
+            if cyclic_scheduler is not None or epoch_scheduler is not None:
+                lr = optimizer.param_groups[0]['lr']
+                lr_info = f' - lr: {lr:.6f}'
+            else:
+                lr_info = ''
+            
+            if val_loader is not None:
+                print(
+                    f'Epoch {epoch+1:3d}/{epochs} - '
+                    f'loss: {train_loss:.4f} - acc: {train_acc:5.2f}% - '
+                    f'val_loss: {val_loss:.4f} - val_acc: {val_acc:5.2f}%{lr_info}'
+                )
+            else:
+                print(
+                    f'Epoch {epoch+1:3d}/{epochs} - '
+                    f'loss: {train_loss:.4f} - acc: {train_acc:5.2f}%{lr_info}'
+                )
+        
+        # Check early stopping (only if validation data is provided and early stopping is enabled)
+        if enable_early_stopping and val_loader is not None and epochs_without_improvement >= early_stopping_patience:
+            print(f'\nEarly stopping at epoch {epoch + 1}')
+            print(f'Best val_loss: {best_val_loss:.4f} at epoch {epoch + 1 - epochs_without_improvement}')
+            break
+    
+    # Restore best model (only if early stopping was enabled)
+    if enable_early_stopping and best_model_state is not None:
+        model.load_state_dict(best_model_state)
+        print(f'Restored best model weights')
+    
+    return history

image_classification_tools-0.5.6.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: image-classification-tools
+Version: 0.5.6
+Summary: A lightweight PyTorch toolkit for building and training image classification models
+License: GPLv3
+License-File: LICENSE
+Keywords: Python,Machine learning,Deep learning,CNNs,Computer vision,Image classification,PyTorch,Neural networks
+Author: gperdrizet
+Author-email: george@perdrizet.org
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Provides-Extra: tensorflow
+Requires-Dist: numpy (>=1.24)
+Requires-Dist: torch (>=2.0)
+Requires-Dist: torchvision (>=0.15)
+Project-URL: Documentation, https://gperdrizet.github.io/CIFAR10
+Project-URL: Homepage, https://github.com/gperdrizet/CIFAR10
+Project-URL: Issues, https://github.com/gperdrizet/CIFAR10/issues
+Project-URL: PyPI, https://pypi.org/project/image-classification-tools
+Project-URL: Repository, https://github.com/gperdrizet/CIFAR10
+Description-Content-Type: text/markdown
+
+# Image Classification Tools
+
+A lightweight PyTorch toolkit for building and training image classification models.
+
+## Overview
+
+This package provides utilities for common image classification tasks:
+
+- **Data loading**: Flexible data loaders for torchvision datasets and custom image folders
+- **Model training**: Training loops with progress tracking and validation
+- **Evaluation**: Accuracy metrics, confusion matrices, and performance analysis
+- **Visualization**: Learning curves, probability distributions, and evaluation plots
+- **Hyperparameter optimization**: Optuna integration for automated model tuning
+
+## Installation
+
+```bash
+pip install image-classification-tools
+```
+
+## Quick start
+
+### Basic usage
+
+```python
+import torch
+from pathlib import Path
+from torchvision import datasets, transforms
+from image_classification_tools.pytorch.data import (
+    load_datasets, prepare_splits, create_dataloaders
+)
+from image_classification_tools.pytorch.training import train_model
+from image_classification_tools.pytorch.evaluation import evaluate_model
+
+# Define transforms
+transform = transforms.Compose([
+    transforms.ToTensor(),
+    transforms.Normalize((0.5,), (0.5,))
+])
+
+# Load datasets
+train_dataset, test_dataset = load_datasets(
+    data_source=datasets.MNIST,
+    train_transform=transform,
+    eval_transform=transform,
+    download=True,
+    root=Path('./data/mnist')
+)
+
+# Prepare splits
+train_dataset, val_dataset, test_dataset = prepare_splits(
+    train_dataset=train_dataset,
+    test_dataset=test_dataset,
+    train_val_split=0.8
+)
+
+# Create dataloaders
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+train_loader, val_loader, test_loader = create_dataloaders(
+    train_dataset, val_dataset, test_dataset,
+    batch_size=64,
+    preload_to_memory=True,
+    device=device
+)
+
+# Define model, criterion, optimizer
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+
+model = torch.nn.Sequential(
+    torch.nn.Flatten(),
+    torch.nn.Linear(784, 128),
+    torch.nn.ReLU(),
+    torch.nn.Linear(128, 10)
+).to(device)
+
+criterion = torch.nn.CrossEntropyLoss()
+optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
+
+# Train with lazy loading (moves batches to device during training)
+history = train_model(
+    model=model,
+    train_loader=train_loader,
+    val_loader=val_loader,
+    criterion=criterion,
+    optimizer=optimizer,
+    device=device,
+    lazy_loading=True,  # Set False if data already on device
+    epochs=10
+)
+
+# Evaluate
+accuracy, predictions, labels = evaluate_model(model, test_loader)
+print(f'Test accuracy: {accuracy:.2f}%')
+```
+
+### Hyperparameter optimization
+
+```python
+from image_classification_tools.pytorch.hyperparameter_optimization import create_objective
+import optuna
+
+# Define search space
+search_space = {
+    'batch_size': [32, 64, 128],
+    'n_conv_blocks': (1, 3),
+    'initial_filters': [16, 32, 64],
+    'n_fc_layers': (1, 3),
+    'conv_dropout_rate': (0.1, 0.5),
+    'fc_dropout_rate': (0.3, 0.7),
+    'learning_rate': (1e-4, 1e-2, 'log'),
+    'optimizer': ['Adam', 'SGD'],
+    'weight_decay': (1e-6, 1e-3, 'log')
+}
+
+# Create objective function
+objective = create_objective(
+    data_dir='./data',
+    train_transform=transform,
+    eval_transform=transform,
+    n_epochs=20,
+    device=device,
+    num_classes=10,
+    in_channels=1,
+    search_space=search_space
+)
+
+# Run optimization
+study = optuna.create_study(direction='maximize')
+study.optimize(objective, n_trials=50)
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- PyTorch ≥ 2.0.0
+- torchvision ≥ 0.15.0
+- numpy
+- matplotlib
+- optuna (optional, for hyperparameter optimization)
+
+## Documentation
+
+Full documentation is available at: https://gperdrizet.github.io/CIFAR10/
+
+## Demo project
+
+See a complete example of using this package for CIFAR-10 classification:
+https://github.com/gperdrizet/CIFAR10
+
+## License
+
+GPLv3
+

image_classification_tools-0.5.6.dist-info/RECORD

@@ -0,0 +1,13 @@
+image_classification_tools/README.md,sha256=coG92m78R6ySYbIe0rL7aQTfwn8EXY1W7eHzwP4aolU,3885
+image_classification_tools/__init__.py,sha256=fjZulfAxTbbqXAvquR-ogCTSbyqaEExceEe_Kzgx7Yc,318
+image_classification_tools/pytorch/__init__.py,sha256=QZo7kAO9iacfI4HqK7ji3zUrEugo8KwMREHU149nlXY,1261
+image_classification_tools/pytorch/data.py,sha256=ZnrauKpSU--9_Hrkqxf9TBJ2zDKUzuW_tyz1dO-4J6Q,15557
+image_classification_tools/pytorch/evaluation.py,sha256=i4tRYOqWATVqQVkWT_fATWRbzo9ziX2DDkXKPaiQlFE,923
+image_classification_tools/pytorch/hyperparameter_optimization.py,sha256=_KB80E7xnHEB4b7KlISG8nLikTNNcwf_ArZM9xDen8E,11272
+image_classification_tools/pytorch/plotting.py,sha256=7B84_JayDuIL3u7hHa1ZPR0VXTe0lBIXxjJ5e4LLXzo,9738
+image_classification_tools/pytorch/training.py,sha256=NjT-g3YyamtgPeS7SxiwCjX2zunTMQI5oxQJAdoRNK0,10370
+image_classification_tools/tensorflow/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+image_classification_tools-0.5.6.dist-info/METADATA,sha256=0Kq1Az_Tt5xIFoXcGc7WhFeoGXktNB1RkGmKoBkNjJQ,5464
+image_classification_tools-0.5.6.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+image_classification_tools-0.5.6.dist-info/licenses/LICENSE,sha256=wtHfRwmCF5-_XUmYwrBKwJkGipvHVmh7GXJOKKeOe2U,1073
+image_classification_tools-0.5.6.dist-info/RECORD,,

image_classification_tools-0.5.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

image_classification_tools-0.5.6.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Perdrizet
+
+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.