Upload README.md with huggingface_hub

README.md

@@ -9,43 +9,121 @@ metrics:
 tags:
 - image-classification
 ---
-# Model Description
 
-The LeNNon_smile_detector model is used to detect smiling and not-smiling faces.
+# LeNNon-Smile-Detector
 
-The model was trained with CelebA dataset. 
+## Model Overview
 
-## Details
+The LeNNon-Smile-Detector is a convolutional neural network trained to detect the presence of a human smile in a facial image.
 
-- Dataset: [CelebFaces Attributes](https://www.kaggle.com/datasets/jessicali9530/celeba-dataset/)
-  
-  The creators of the dataset wrote the following paper employing CelebA for face detection:
-  S. Yang, P. Luo, C. C. Loy, and X. Tang,
-  "From Facial Parts Responses to Face Detection: A Deep Learning Approach", in IEEE International Conference on Computer Vision (ICCV), 2015.
-- Language: English
-- Number of Training Steps: 20
-- Batch size: 32
-- Optimizer: Adam
-- Learning Rate: 0.001
-- GPU: T4
-- This repository has the source [code used](https://github.com/Nkluge-correa/teeny-tiny_castle/blob/master/ML%20Fairness/fair_metrics_celeba.ipynb) to train this model.
+### Details
 
+- **Size:** 2,566,506 parameters
+- **Model type:** Convolutional neural network
+- **Optimizer**: `torch.optim.Adam` with a learning rate of 0.001
+- **Number of Epochs:** 20
+- **Batch Size:** 256
+- **Hardware:** Tesla V4
+- **Emissions:** Not measured
+- **Total Energy Consumption:** Not measured
 
-## Performance
+### How to Use
 
-Final Validation Accuracy: 90.56% Final Validation Loss: 0.6397
+```python
+import torch
+from PIL import Image
+from lennon import LeNNon
+from torchvision import transforms
+from huggingface_hub import hf_hub_download
 
-# Cite as 🤗
+# Download the pytorch model
+hf_hub_download(repo_id="AiresPucrs/LeNNon-Smile-Detector",
+                filename="LeNNon-Smile-Detector.pt",
+                local_dir="./",
+                repo_type="model"
+                )
+
+# Download the source implementation of the model's architecture
+hf_hub_download(repo_id="AiresPucrs/LeNNon-Smile-Detector",
+                filename="lennon.py",
+                local_dir="./",
+                repo_type="model"
+                )
+
+# Check if GPU is available
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# Load the model an pass it to the proper device
+model = torch.load('./LeNNon-Smile-Detector.pt')
+model = model.to(device)
+model.eval()
+
+# This `transform` object will transform our test images into proper tensors
+transform = transforms.Compose([
+    transforms.Resize((100, 100)),  # Resize the image to 100x100
+    transforms.ToTensor(),
+])
+
+image_path = "your_image_path_here"
+
+# Open and preprocess he image
+image = Image.open(image_path)
+tensor = transform(image)
+tensor = tensor.to(device)
+
+# forward pass trough the model
+with torch.no_grad():
+
+  outputs = model(tensor)
+
+# Get the class prediction
+_, predicted = torch.max(outputs.data, 1)
+
+print("Smiling" if predicted.item() > 0 else "Not Smiling")
 ```
+
+## Intended Use
+
+This model was created for research purposes only. Specifically, it was designed to explore discriminatory biases present in a subset of the CelebA dataset (the [CelebA-Smiles](https://huggingface.co/datasets/AiresPucrs/CelebA-Smiles)). We do not recommend any application of this model outside this scope.
+
+
+## Performance Metrics
+
+The model achieved an accuracy of 97% in a test set split containing 5000 images from the [CelebA-Smiles](https://huggingface.co/datasets/AiresPucrs/CelebA-Smiles).
+
+## Training Data
+
+The model was trained on a subset of the [CelebA dataset](https://www.kaggle.com/datasets/jessicali9530/celeba-dataset), i.e., CelebA-Smiles.
+
+CelebA-Smiles contains 50K images. 25K of smiling faces, and 25K of non smiling faces.
+
+Images on the CelebA-Smiles were resized to 100 x 100 pixels before training the model. For more details on the features contained in the CelebA-Smiles dataset, check its [dataset card](https://huggingface.co/datasets/AiresPucrs/CelebA-Smiles).
+
+## Limitations
+
+We performed a simple fairness analysis of our model regarding the sensitive attribute **age**.
+
+According to our analysis, the model has no discriminatory bias regarding this feature. Results can be found [here](https://github.com/Nkluge-correa/teeny-tiny_castle/blob/master/ML%20Fairness/fair_metrics_celeba.ipynb).
+
+Other possible biases were not investigated, but further investigations are likely given that other sensitive attributes present in the training dataset are available.
+
+In conclusion, we do not recommend using this model in real-world applications. It was solely developed for academic and educational purposes.
+
+## Cite as
+
+```latex
 @misc{teenytinycastle,
     doi = {10.5281/zenodo.7112065},
-    url = {https://huggingface.co/AiresPucrs/LeNNon_smile_detector},
+    url = {https://github.com/Nkluge-correa/teeny-tiny_castle},
     author = {Nicholas Kluge Corr{\^e}a},
     title = {Teeny-Tiny Castle},
-    year = {2023},
-    publisher = {HuggingFace},
-    journal = {HuggingFace repository},
+    year = {2024},
+    publisher = {GitHub},
+    journal = {GitHub repository},
 }
 ```
+
 ## License
-The LeNNon_smile_detector model is licensed under the Apache License, Version 2.0. See the LICENSE file for more details.
+
+This model is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for more details.
+