fashion-mnist-classifier 0.1.11
An image classification model for Fashion MNIST using PyTorch Lightning.
License: MIT
Requires Python: >=3.12
Keywords: pytorch, lightning, fashion-mnist, image-classification

## Fashion-MNIST Classifier

[![PyPI version](https://badge.fury.io/py/fashion-mnist-classifier.svg)](https://pypi.org/project/fashion-mnist-classifier/)

**[View Documentation on GitHub Pages](https://ainhoupna.github.io/SD/my_project.html)**

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`



## Training and Evaluation
You can run the training and evaluation script using `uvx`, which executes the project's command-line scripts without needing to install the package in editable mode.

To run the training script:
```bash
uvx fashion-mnist-classifier
```
To run the app:

```bash
uvx --from fashion-mnist-classifier fashion-mnist-app
```

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

1.  **Install build tools:**
    ```bash
    uv pip install build twine
    ```
2.  **Build the package:**
    ```bash
    python -m build
    ```
3.  **Publish to PyPI:**
    ```bash
    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.

## Generating PDF Report with Typst

This project uses [Typst](https://typst.app/) to generate a PDF report from the model's results and visualizations.

### Installation

To compile the report, you first need to install Typst. You can find installation instructions for your operating system on the [official Typst GitHub repository](https://github.com/typst/typst#installation).

### Compiling the Report

Once Typst is installed, navigate to the `reports` directory and compile the `main.typ` file. This will generate a report file in the same directory, containing a summary of the project, including the generated plots and evaluation metrics.

## 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
```

## Contact
- delrey.132148@e.unavarra.es
- goicoechea.128710@e.unavarra.es
- haddad.179806@e.unavarra.es