| --- |
| language: en |
| tags: |
| - image-classification |
| - pytorch |
| - tensorflow |
| - scikit-learn |
| - mnist |
| - computer-vision |
| datasets: |
| - mnist |
| metrics: |
| - accuracy |
| --- |
| |
| # MNIST Framework Bake-off Models |
|
|
| ## Model Details |
| This repository contains pre-trained model weights for handwritten digit classification (0-9) trained on the MNIST dataset. |
| It was developed as part of an end-to-end MLOps and framework benchmarking portfolio project. |
|
|
| Three distinct architectures are hosted here to demonstrate the trade-offs between deep learning and classical machine learning on spatial data: |
|
|
| 1. **CNN (PyTorch & TensorFlow) (`pytorch_cnn_weights.pth`, `tf_cnn_model.keras`):** A Convolutional Neural Network designed for high accuracy and $O(1)$ inference latency. |
| 2. **Random Forest Classifier (Scikit-Learn) (`sklearn_rf.joblib`):** A baseline classical Machine Learning architecture to establish performance bounds before applying deep learning. |
| 3. **Soft-Voting Ensemble (Scikit-Learn) (`sklearn_ensemble.joblib`):** An ensemble combining a Multi-Layer Perceptron (MLP) and a K-Nearest Neighbors (K-NN) classifier. |
|
|
| * **Developed by:** AKinoshi |
| * **Model Date:** July 2026 |
| * **Model Type:** Image Classification |
| * **License:** MIT |
|
|
| ## Intended Use |
| * **Primary Use Case:** Educational benchmarking and portfolio demonstration of framework agility and model deployment. |
| * **Out-of-Scope:** This model is trained exclusively on cleanly centered, 28x28 grayscale digits. It is not intended for general-purpose Optical Character Recognition (OCR) on real-world, noisy documents or alphabetic text. |
|
|
| ## Training Data |
| The models were trained on the **MNIST dataset**, which consists of 70,000 images of handwritten digits normalized to fit into a 28x28 pixel bounding box and anti-aliased. |
| * **Preprocessing (PyTorch / TensorFlow):** Pixel values normalized to a range of [-1, 1] or [0, 1] with an explicit channel dimension added. |
| * **Preprocessing (Scikit-Learn):** MinMax scaling applied to flatten 1D arrays, scaling intensities from [0, 255] down to [0, 1]. |
|
|
| ## Evaluation Metrics |
| Models were evaluated using **Accuracy** and a detailed classification report (Precision, Recall, F1-Score) on a 20% holdout test set. |
|
|
| * **CNN:** ~99.08% Test Accuracy. Demonstrates excellent spatial feature extraction through convolutional filters. |
| * **Random Forest Classifier:** ~96.75% Test Accuracy. Fast CPU training, but loses spatial hierarchy due to image flattening. |
| * **Scikit-Learn Ensemble:** ~98.33% Test Accuracy. While highly accurate, the K-NN component introduces significant inference latency $O(N \times D)$, making it less suitable for real-time production endpoints compared to the compiled CNN. |
|
|
| ## How to Get Started with the Model |
|
|
| You can dynamically download these weights directly into your Python scripts using the `huggingface_hub` library. |
|
|
| ```python |
| # pip install huggingface_hub torch |
| |
| import torch |
| from huggingface_hub import hf_hub_download |
| |
| # 1. Download the PyTorch weights (caches automatically) |
| model_path = hf_hub_download( |
| repo_id="AKinoshi/mnist-framework-bakeoff", |
| filename="pytorch_cnn_weights.pth" |
| ) |
| |
| # 2. Load into your PyTorch architecture |
| # model = DigitClassifierCNN() |
| # model.load_state_dict(torch.load(model_path, map_location=torch.device('cpu'))) |
| # model.eval() |
