## Fashion-MNIST Classifier
[](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
Raw data
{
"_id": null,
"home_page": null,
"name": "fashion-mnist-classifier",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "pytorch, lightning, fashion-mnist, image-classification",
"author": null,
"author_email": "Ainhoa Del Rey <delrey.132148@e.unavarra.es>, I\u00f1igo Goikoetxea <goicoechea.128710@e.unavarra.es>, Maria Ines <haddad.179806@e.unavarra.es>",
"download_url": "https://files.pythonhosted.org/packages/b1/a8/2342fb423e31ecff0fdca5db13ab1836acdba63edcb10b63cbbdf0b0b82b/fashion_mnist_classifier-0.1.11.tar.gz",
"platform": null,
"description": "## Fashion-MNIST Classifier\n\n[](https://pypi.org/project/fashion-mnist-classifier/)\n\n**[View Documentation on GitHub Pages](https://ainhoupna.github.io/SD/my_project.html)**\n\nThis 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.\nThe dataset is loaded directly from `torchvision.datasets`. The goal is to train a simple convolutional network that classifies images into 10 different clothing categories. \n\n\n## Installation\nTo install dependencies and prepare the environment with uv, run the following commands in the terminal:\n1. Download and install dependencies: `curl -sSf https://uv.io/install.sh | sh`\n2. Initialize the environment: `uv init`\n3. Sync dependencies and environment: `uv sync`\n\n\n\n## Training and Evaluation\nYou 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.\n\nTo run the training script:\n```bash\nuvx fashion-mnist-classifier\n```\nTo run the app:\n\n```bash\nuvx --from fashion-mnist-classifier fashion-mnist-app\n```\n\n## Building and Publishing to PyPI\nTo build and publish the package to PyPI, follow these steps:\n\n1. **Install build tools:**\n ```bash\n uv pip install build twine\n ```\n2. **Build the package:**\n ```bash\n python -m build\n ```\n3. **Publish to PyPI:**\n ```bash\n twine upload dist/*\n ```\n You will be prompted for your PyPI username and password.\n\n\n## Technical Details\n- **Dataset**: `torchvision.datasets.FashionMNIST` with custom transformations.\n- **Model**: Simple CNN with one convolutional layer, pooling, and fully connected layers.\n- **Training**: Implemented with PyTorch Lightning to facilitate handling epochs, performance, and metrics.\n- **Configuration**: Parameters such as batch size, paths, epochs defined in config.py.\n- **Optimization**: Adam with CrossEntropyLoss.\n\n## Generated Artifacts\n\nWhen 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:\n\n- **`data/`**:\n - Contains the downloaded Fashion-MNIST dataset files (e.g., `FashionMNIST/raw/train-images-idx3-ubyte.gz`).\n- **`models/lightning_logs/`**:\n - Stores logs and checkpoints generated by PyTorch Lightning during training. This typically includes:\n - `version_X/checkpoints/`: Model checkpoints (e.g., `epoch=4-step=2340.ckpt`).\n - `version_X/metrics.csv`: Training and validation metrics logged by `CSVLogger`.\n- **`reports/figures/`**:\n - Contains output visualizations from the evaluation step and data exploration. These include:\n - `confusion_matrix.png`: Confusion matrix of model predictions on the test set.\n - `per_class_accuracy.png`: Bar chart showing accuracy for each class.\n - `misclassified_grid.png`: Grid of misclassified sample images from the test set.\n - `calibration_curve.png`: Reliability diagram for model calibration.\n - `train_loss_*.png`: Plots of training loss over steps/epochs (generated if `CSVLogger` is used).\n - `val_acc_*.png`: Plots of validation accuracy over epochs (generated if `CSVLogger` is used).\n - `class_distribution.png`: Plot showing the distribution of samples per class in the dataset.\n - `class_correlation_dendrogram.png`: Dendrogram illustrating class similarity based on mean images.\n - `reports/figures/gradio/`: A subdirectory specifically for figures generated when using the Gradio application.\n\n## Reports & Visualizations\nThe 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.\n\nKey visualizations include:\n- **Confusion matrix**: Shows the performance of the classification model.\n- **Per-class accuracy**: Illustrates how well the model performs on each individual class.\n- **Calibration curve**: Assesses the confidence of the model's predictions.\n- **Misclassified image grids**: Displays examples of images that the model predicted incorrectly.\n- **Class distribution plots**: Visualizes the balance of classes within the dataset.\n- **Class similarity dendrograms**: Helps understand relationships between different clothing categories based on their image features.\n- **Training loss and validation accuracy curves**: Track the model's learning progress over epochs.\n\n## Generating PDF Report with Typst\n\nThis project uses [Typst](https://typst.app/) to generate a PDF report from the model's results and visualizations.\n\n### Installation\n\nTo 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).\n\n### Compiling the Report\n\nOnce 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.\n\n## Project Structure\n\n```\nfashion-mnist-classifier/\n\u251c\u2500\u2500 models/ # Directory for saved models and checkpoints\n\u251c\u2500\u2500 reports/ # Evaluation reports and generated figures\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 my_project/ # Project source code\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 app.py # Gradio application\n\u2502 \u251c\u2500\u2500 config.py # Configurations and parameters\n\u2502 \u251c\u2500\u2500 dataset.py # Dataset and DataModule\n\u2502 \u251c\u2500\u2500 model.py # PyTorch Lightning model\n\u2502 \u251c\u2500\u2500 plots.py # Visualization functions\n\u2502 \u2514\u2500\u2500 train.py # Main training script\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 LICENSE # Project license\n\u251c\u2500\u2500 pyproject.toml # Project metadata and dependencies\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Contact\n- delrey.132148@e.unavarra.es\n- goicoechea.128710@e.unavarra.es\n- haddad.179806@e.unavarra.es\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An image classification model for Fashion MNIST using PyTorch Lightning.",
"version": "0.1.11",
"project_urls": {
"Bug Tracker": "https://github.com/tu_usuario/fashion-mnist-classifier/issues",
"Homepage": "https://github.com/tu_usuario/fashion-mnist-classifier"
},
"split_keywords": [
"pytorch",
" lightning",
" fashion-mnist",
" image-classification"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c29c0b39d8270184972cf4b37b41f58556ba8ea435dfbccd99a0d0ecd0b37dd1",
"md5": "c6823ed282f8db144d1071457b0dd5b7",
"sha256": "194822a36075e24664437d1d61186cd1fc7b3d38d99da9e26b7ccfb65a5229c8"
},
"downloads": -1,
"filename": "fashion_mnist_classifier-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6823ed282f8db144d1071457b0dd5b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 19125,
"upload_time": "2025-10-23T10:27:20",
"upload_time_iso_8601": "2025-10-23T10:27:20.332734Z",
"url": "https://files.pythonhosted.org/packages/c2/9c/0b39d8270184972cf4b37b41f58556ba8ea435dfbccd99a0d0ecd0b37dd1/fashion_mnist_classifier-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1a82342fb423e31ecff0fdca5db13ab1836acdba63edcb10b63cbbdf0b0b82b",
"md5": "45b66c6daf9b1244cdd0a8e65f78deee",
"sha256": "c29caf5c1fe9992d5c55a13c35d84998a148aec01c15f52aef7953cf7b695871"
},
"downloads": -1,
"filename": "fashion_mnist_classifier-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "45b66c6daf9b1244cdd0a8e65f78deee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 16587,
"upload_time": "2025-10-23T10:27:21",
"upload_time_iso_8601": "2025-10-23T10:27:21.634394Z",
"url": "https://files.pythonhosted.org/packages/b1/a8/2342fb423e31ecff0fdca5db13ab1836acdba63edcb10b63cbbdf0b0b82b/fashion_mnist_classifier-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 10:27:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tu_usuario",
"github_project": "fashion-mnist-classifier",
"github_not_found": true,
"lcname": "fashion-mnist-classifier"
}
JSON
