fashion-mnist-classifier 0.1.9

An image classification model for Fashion MNIST using PyTorch Lightning.

Fashion-MNIST Classifier

This project implements an image classification model based on the Fashion MNIST dataset, using PyTorch Lightning to structure the code in a modular and scalable way. The dataset is loaded directly from torchvision.datasets. The goal is to train a simple convolutional network that classifies images into 10 different clothing categories.

Installation

To install dependencies and prepare the environment with uv, run the following commands in the terminal:

1. Download and install dependencies: curl -sSf https://uv.io/install.sh | sh
2. Initialize the environment: uv init
3. Sync dependencies and environment: uv sync

After setting up the environment, install the project in editable mode to make the scripts available in your path:

uv pip install -e .

Project Structure

fashion-mnist-classifier/
├── models/               # Directory for saved models and checkpoints
├── reports/              # Evaluation reports and generated figures
├── src/
│   └── my_project/       # Project source code
│       ├── __init__.py
│       ├── app.py        # Gradio application
│       ├── config.py     # Configurations and parameters
│       ├── dataset.py    # Dataset and DataModule
│       ├── model.py      # PyTorch Lightning model
│       ├── plots.py      # Visualization functions
│       └── train.py      # Main training script
├── .gitignore
├── LICENSE               # Project license
├── pyproject.toml        # Project metadata and dependencies
└── README.md             # This file

Training and Evaluation

To modify the training and evaluation script, first install the package in editable mode:

uv pip install -e .

Then, run the following command in the terminal:

fashion-mnist-classifier

Building and Publishing to PyPI

To build and publish the package to PyPI, follow these steps:

1. Install build tools:

   uv pip install build twine
   

2. Build the package:

   python -m build
   

3. Publish to PyPI:

   twine upload dist/*
   

   You will be prompted for your PyPI username and password.

Technical Details

• Dataset: torchvision.datasets.FashionMNIST with custom transformations.
• Model: Simple CNN with one convolutional layer, pooling, and fully connected layers.
• Training: Implemented with PyTorch Lightning to facilitate handling epochs, performance, and metrics.
• Configuration: Parameters such as batch size, paths, epochs defined in config.py.
• Optimization: Adam with CrossEntropyLoss.

Generated Artifacts

When you run the training script (src/my_project/train.py) or the Gradio application (src/my_project/app.py), the following directories and files are created or updated:

• data/:
  • Contains the downloaded Fashion-MNIST dataset files (e.g., FashionMNIST/raw/train-images-idx3-ubyte.gz).
• models/lightning_logs/:
  • Stores logs and checkpoints generated by PyTorch Lightning during training. This typically includes:
    • version_X/checkpoints/: Model checkpoints (e.g., epoch=4-step=2340.ckpt).
    • version_X/metrics.csv: Training and validation metrics logged by CSVLogger.
• reports/figures/:
  • Contains output visualizations from the evaluation step and data exploration. These include:
    • confusion_matrix.png: Confusion matrix of model predictions on the test set.
    • per_class_accuracy.png: Bar chart showing accuracy for each class.
    • misclassified_grid.png: Grid of misclassified sample images from the test set.
    • calibration_curve.png: Reliability diagram for model calibration.
    • train_loss_*.png: Plots of training loss over steps/epochs (generated if CSVLogger is used).
    • val_acc_*.png: Plots of validation accuracy over epochs (generated if CSVLogger is used).
    • class_distribution.png: Plot showing the distribution of samples per class in the dataset.
    • class_correlation_dendrogram.png: Dendrogram illustrating class similarity based on mean images.
  • reports/figures/gradio/: A subdirectory specifically for figures generated when using the Gradio application.

Reports & Visualizations

The project generates various reports and visualizations to assess model performance and explore the dataset. Details on the specific files and their locations can be found in the Generated Artifacts section.

Key visualizations include:

• Confusion matrix: Shows the performance of the classification model.
• Per-class accuracy: Illustrates how well the model performs on each individual class.
• Calibration curve: Assesses the confidence of the model's predictions.
• Misclassified image grids: Displays examples of images that the model predicted incorrectly.
• Class distribution plots: Visualizes the balance of classes within the dataset.
• Class similarity dendrograms: Helps understand relationships between different clothing categories based on their image features.
• Training loss and validation accuracy curves: Track the model's learning progress over epochs.

Contact

[e-mail] [e-mail] [e-mail]