kechiro/timeseries-image-classifier

•Updated over 1 year ago

Image

Machine learning & AI

392

kechiro/timeseries-image-classifier repository overview

⁠Time-Series Image Classifier

A production-ready Docker image for time-series image classification using EfficientNet/NFNet with PyTorch Lightning. This containerized solution implements transfer learning for multi-class classification tasks with selective fine-tuning techniques, supporting both single-modal (image-only) and multi-modal (image + time-series features) learning approaches.

⁠Quick Start

⁠Pull and Run

# Pull the latest image
docker pull kechiro/timeseries-image-classifier:latest

# Run with GPU support (recommended)
docker run --gpus all -it kechiro/timeseries-image-classifier:latest

# Run without GPU
docker run -it kechiro/timeseries-image-classifier:latest

⁠Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/kechirojp/timeseries-image-classifier.git
cd timeseries-image-classifier

# Run with Docker Compose
docker-compose up

⁠Key Features

🚀 Ready-to-Use: Pre-configured environment with all dependencies
🎯 GPU Accelerated: CUDA support for high-performance training
🔧 Configurable: Flexible YAML-based configuration system
📊 Multi-Modal: Support for image-only and image+numerical features
🎨 Model Selection: EfficientNet-B4, NFNet-F0, or ResNet18 (fallback)
📈 F1-Score Optimized: Advanced evaluation and early stopping
🔍 TensorBoard: Integrated visualization and monitoring
⚡ Production Ready: Checkpoint resumption and robust training pipeline

⁠Environment Variables

Variable	Default	Description
`MODEL_MODE`	`single`	Training mode: 'single' or 'multi'
`MODEL_ARCHITECTURE`	`nfnet`	Architecture: 'nfnet', 'efficientnet', 'resnet18'
`BATCH_SIZE`	`32`	Training batch size
`MAX_EPOCHS`	`100`	Maximum training epochs
`PRECISION`	`16-mixed`	Training precision
`NUM_WORKERS`	`4`	DataLoader workers (set to 0 for Windows)

⁠Volume Mounts

Mount your data and configuration directories:

docker run --gpus all -it \
  -v /path/to/your/data:/app/data \
  -v /path/to/your/configs:/app/configs \
  -v /path/to/save/checkpoints:/app/checkpoints \
  -v /path/to/save/logs:/app/logs \
  kechiro/timeseries-image-classifier:latest

⁠Data Structure

Your data directory should follow this structure:

data/
├── README.md                                # Data structure documentation
├── fix_labeled_data_timeseries_15m.csv     # Label file (for multi-modal)
├── timeseries_15m_202412301431.csv         # Feature file (for multi-modal)
├── dataset_a_15m_winsize40/                # Dataset A (image data)
│   ├── README.md                           # Image data requirements
│   ├── train/                              # Training data
│   │   ├── class_0/                        # Class 0 images (label 0)
│   │   │   ├── dataset_a_15m_20240101_0900_label_0.png
│   │   │   └── ...
│   │   ├── class_1/                        # Class 1 images (label 1)
│   │   └── class_2/                        # Class 2 images (label 2)
│   └── test/                               # Test data
│       ├── class_0/                        # Class 0 images (label 0)
│       ├── class_1/                        # Class 1 images (label 1)
│       └── class_2/                        # Class 2 images (label 2)
├── dataset_b_15m_winsize40/                # Dataset B (same structure)
│   ├── README.md
│   ├── train/
│   │   ├── class_0/
│   │   ├── class_1/
│   │   └── class_2/
│   └── test/
│       ├── class_0/
│       ├── class_1/
│       └── class_2/
└── dataset_c_15m_winsize40/                # Dataset C (same structure)
    ├── README.md
    ├── train/
    │   ├── class_0/
    │   ├── class_1/
    │   └── class_2/
    └── test/
        ├── class_0/
        ├── class_1/
        └── class_2/

⁠File Naming Conventions

⁠Image Files

{dataset_name}_{timeframe}_{YYYYMMDD}_{HHMM}_label_{class_id}.png

Examples:

dataset_a_15m_20240101_0900_label_0.png → class_0 (label 0)
dataset_a_15m_20240101_0915_label_1.png → class_1 (label 1)

{dataset_name}_{timeframe}_{YYYYMMDD}{HHMM}.csv

Example:

dataset_a_15m_202412301431.csv → Data for 2024-12-30 14:31

⁠Configuration

Create a config.yaml file in your configs directory:

# Model settings
model_mode: 'single'  # or 'multi'
model_architecture_name: 'nfnet'  # 'nfnet', 'efficientnet', 'resnet18'

# Training settings
max_epochs: 100
batch_size: 32
precision: '16-mixed'

# Data settings
datasets: ['dataset_a', 'dataset_b', 'dataset_c']
num_classes: 3
class_names: ['class_0', 'class_1', 'class_2']

# Multi-modal settings (for model_mode: 'multi')
timeseries:
  data_path: './data/timeseries_15m_202412301431.csv'
  feature_columns: ['feature_1', 'feature_2', 'feature_3', 'feature_4', 'feature_5', 'feature_6']
  window_size: 40

# Resume training (optional)
resume_from_checkpoint: null  # or 'last.ckpt'

⁠Usage Examples

⁠Basic Training

# Single-modal training
docker run --gpus all -it \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/configs:/app/configs \
  -e MODEL_MODE=single \
  -e MODEL_ARCHITECTURE=nfnet \
  kechiro/timeseries-image-classifier:latest

# Multi-modal training with time-series features
docker run --gpus all -it \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/configs:/app/configs \
  -e MODEL_MODE=multi \
  -e MODEL_ARCHITECTURE=nfnet \
  kechiro/timeseries-image-classifier:latest

⁠Resume Training

# Resume from checkpoint
docker run --gpus all -it \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/configs:/app/configs \
  -v $(pwd)/checkpoints:/app/checkpoints \
  kechiro/timeseries-image-classifier:latest

⁠TensorBoard Monitoring

# Run TensorBoard (in separate container or host)
docker run --rm -p 6006:6006 \
  -v $(pwd)/logs:/app/logs \
  tensorflow/tensorflow:latest \
  tensorboard --logdir=/app/logs --host=0.0.0.0

⁠Advanced Features

Progressive Fine-tuning: Stage-wise differential learning rates
Progressive Unfreezing: Gradual layer unfreezing for optimal transfer learning
Feature Importance Analysis: LightGBM-based feature selection for multi-modal models
Hyperparameter Optimization: Optuna integration for automated tuning
Class Imbalance Handling: Uniform sampling and balanced dataset splits

⁠Tags

latest: Latest stable version with all features
stable: Production-ready stable version (same as latest)
gpu: GPU-optimized version (same as latest)
v1.1.0: Latest version 1.1.0 release (recommended)
v1.0.0: Previous version 1.0.0 release

⁠System Requirements

GPU: NVIDIA GPU with CUDA 12.1+ support (recommended)
CPU: Multi-core processor (minimum 4 cores)
Memory: 8GB RAM minimum, 16GB+ recommended
Storage: 10GB+ free space for data and models

⁠Support & Documentation

GitHub Repository: https://github.com/kechirojp/timeseries-image-classifier⁠
Issues: Report bugs and feature requests on GitHub
Documentation: Comprehensive README and configuration examples in the repository

⁠License

This project is licensed under the MIT License. See the LICENSE⁠ file for details.

Built with ❤️ using PyTorch Lightning and Docker

Tag summary

Recent tags

Content type

Image

Digest

sha256:0118ffc8a…

Size

10.1 GB

Last updated

over 1 year ago

docker pull kechiro/timeseries-image-classifier