Upload README.md with huggingface_hub

README.md

@@ -1,246 +1,488 @@
----
-language: en
-license: mit
-library_name: tensorflow
-tags:
-- computer-vision
-- image-classification
-- age-estimation
-- face-analysis
-- resnet50v2
-- tensorflow
-- keras
-- utkface
-- bias-correction
-- age-groups
-- classification
-- deep-learning
-- facial-analysis
-- demographic-estimation
-- transfer-learning
-datasets:
-- UTKFace
-metrics:
-- accuracy
-model-index:
-- name: age-group-classifier
-  results:
-  - task:
-      type: image-classification
-      name: Age Group Classification
-    dataset:
-      type: UTKFace
-      name: UTKFace
-    metrics:
-    - type: accuracy
-      value: 0.755
-      name: Validation Accuracy
----
+------
+
+language: enlanguage: en
+
+license: mitlicense: mit
+
+library_name: tensorflowlibrary_name: tensorflow
+
+tags:tags:
+
+- computer-vision- computer-vision
+
+- image-classification- image-classification
+
+- age-estimation- age-estimation
+
+- face-analysis- face-analysis
+
+- resnet50v2- resnet50v2
+
+- tensorflow- tensorflow
+
+- keras- keras
+
+- utkface- utkface
+
+- bias-correction- bias-correction
+
+- age-groups- age-groups
+
+- classification- classification
+
+- deep-learning- deep-learning
+
+- facial-analysis- facial-analysis
+
+- demographic-estimation- demographic-estimation
+
+- transfer-learning- transfer-learning
+
+datasets:datasets:
+
+- UTKFace- UTKFace
+
+metrics:metrics:
+
+- accuracy- accuracy
+
+model-index:model-index:
+
+- name: age-group-classifier- name: age-group-classifier
+
+  results:  results:
 
-# Age Group Classification Model
+  - task:  - task:
 
-## Model Description
+      type: image-classification      type: image-classification
+
+      name: Age Group Classification      name: Age Group Classification
+
+    dataset:    dataset:
+
+      type: UTKFace      type: UTKFace
+
+      name: UTKFace      name: UTKFace
+
+    metrics:    metrics:
+
+    - type: accuracy    - type: accuracy
+
+      value: 0.755      value: 0.755
+
+      name: Validation Accuracy      name: Validation Accuracy
+
+pipeline_tag: image-classification---
+
+base_model: tensorflow/resnet50v2
+
+widget:# Age Group Classification Model
+
+- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpg
+
+  example_title: Sample Face Image## Model Description
+
+---
 
 This model performs age group classification on facial images, predicting one of 5 age categories instead of exact ages. It was specifically designed to solve the common bias problem where older adults (70+) are incorrectly predicted as young adults (30s).
 
+# Age Group Classification Model 🎯👥
+
 ### Key Features
-- **Bias-Free Predictions**: Correctly classifies seniors instead of mispredicting them as young adults
+
+A breakthrough age group classification model that **solves the age prediction bias problem** where 70-year-olds are incorrectly predicted as 30-year-olds. Instead of exact age regression, this model classifies faces into 5 practical age groups with **75.5% validation accuracy**.- **Bias-Free Predictions**: Correctly classifies seniors instead of mispredicting them as young adults
+
 - **Practical Categories**: Returns useful age ranges rather than potentially inaccurate exact ages
-- **High Performance**: 75.5% validation accuracy on 5-class classification
+
+## 🚀 Quick Start- **High Performance**: 75.5% validation accuracy on 5-class classification
+
 - **Stable Architecture**: ResNet50V2 backbone with proven reliability
 
-## Model Details
+### Using Hugging Face Transformers
+
+```python## Model Details
+
+from transformers import pipeline
+
+from PIL import Image### Architecture
 
-### Architecture
 - **Base Model**: ResNet50V2 (pre-trained on ImageNet)
-- **Task**: Multi-class classification (5 categories)
-- **Input**: RGB facial images (224x224)
-- **Output**: Age group probabilities
 
-### Age Groups
-- **Group 0**: Youth (0-20 years)
-- **Group 1**: Young Adult (21-40 years)
+# Load the classifier- **Task**: Multi-class classification (5 categories)
+
+classifier = pipeline("image-classification", - **Input**: RGB facial images (224x224)
+
+                     model="Sharris/age-group-classifier")- **Output**: Age group probabilities
+
+
+
+# Classify an image### Age Groups
+
+image = Image.open("face_image.jpg")- **Group 0**: Youth (0-20 years)
+
+results = classifier(image)- **Group 1**: Young Adult (21-40 years)
+
 - **Group 2**: Middle Age (41-60 years)
-- **Group 3**: Senior (61-80 years)
-- **Group 4**: Elderly (81-100 years)
+
+print(f"Predicted age group: {results[0]['label']}")- **Group 3**: Senior (61-80 years)
+
+print(f"Confidence: {results[0]['score']:.2%}")- **Group 4**: Elderly (81-100 years)
+
+```
 
 ### Performance
-- **Validation Accuracy**: 75.5%
-- **Training Accuracy**: 79.1%
-- **Generalization Gap**: 3.6% (healthy)
-- **Training Epochs**: 13 (with early stopping)
 
-## Problem Solved
+### Using TensorFlow Directly- **Validation Accuracy**: 75.5%
 
-### Original Issue
-Traditional age regression models often exhibit severe bias:
-- 70-year-old faces predicted as 30-year-olds
-- Inconsistent predictions across age ranges
-- Poor handling of seniors and elderly individuals
+```python- **Training Accuracy**: 79.1%
 
-### Our Solution
-- **Age Group Classification**: More robust than exact age regression
-- **Balanced Training**: Proper representation across all age groups
-- **Transfer Learning**: Leverages ResNet50V2 features optimized for facial analysis
+import tensorflow as tf- **Generalization Gap**: 3.6% (healthy)
 
-## Usage
+import numpy as np- **Training Epochs**: 13 (with early stopping)
 
-```python
-from transformers import pipeline
-import numpy as np
 from PIL import Image
 
-# Load the model
-classifier = pipeline("image-classification", 
+from huggingface_hub import hf_hub_download## Problem Solved
+
+
+
+# Download and load model### Original Issue
+
+model_path = hf_hub_download(Traditional age regression models often exhibit severe bias:
+
+    repo_id="Sharris/age-group-classifier",- 70-year-old faces predicted as 30-year-olds
+
+    filename="resnet50v2_age_classifier_best.h5"- Inconsistent predictions across age ranges
+
+)- Poor handling of seniors and elderly individuals
+
+model = tf.keras.models.load_model(model_path)
+
+### Our Solution
+
+# Preprocess image- **Age Group Classification**: More robust than exact age regression
+
+image = Image.open("face_image.jpg").convert("RGB")- **Balanced Training**: Proper representation across all age groups
+
+image = image.resize((224, 224))- **Transfer Learning**: Leverages ResNet50V2 features optimized for facial analysis
+
+image_array = np.array(image, dtype=np.float32) / 255.0
+
+image_array = np.expand_dims(image_array, axis=0)## Usage
+
+
+
+# Predict```python
+
+predictions = model.predict(image_array)[0]from transformers import pipeline
+
+age_groups = ["Youth (0-20)", "Young Adult (21-40)", "Middle Age (41-60)", import numpy as np
+
+              "Senior (61-80)", "Elderly (81-100)"]from PIL import Image
+
+
+
+predicted_group = age_groups[np.argmax(predictions)]# Load the model
+
+confidence = predictions[np.argmax(predictions)]classifier = pipeline("image-classification", 
+
                      model="your-username/age-group-classifier")
 
-# Classify an image
+print(f"Predicted: {predicted_group} ({confidence:.1%} confidence)")
+
+```# Classify an image
+
 image = Image.open("face_image.jpg")
-results = classifier(image)
 
-print(f"Predicted age group: {results[0]['label']}")
-print(f"Confidence: {results[0]['score']:.2%}")
-```
+## 🎯 Model Overviewresults = classifier(image)
+
+
+
+### The Problem We Solvedprint(f"Predicted age group: {results[0]['label']}")
+
+Traditional age regression models suffer from **severe age bias**:print(f"Confidence: {results[0]['score']:.2%}")
+
+- 70-year-old faces → Predicted as 30-year-olds ❌```
+
+- Inconsistent predictions across age ranges
+
+- Poor handling of seniors and elderly individuals### Example Output
+
+- Exact age predictions often inaccurate and not practical```python
 
-### Example Output
-```python
 [
-    {'label': 'Senior (61-80)', 'score': 0.87},
-    {'label': 'Middle Age (41-60)', 'score': 0.09},
-    {'label': 'Elderly (81-100)', 'score': 0.03},
-    {'label': 'Young Adult (21-40)', 'score': 0.01},
-    {'label': 'Youth (0-20)', 'score': 0.00}
+
+### Our Solution: Age Group Classification    {'label': 'Senior (61-80)', 'score': 0.87},
+
+- **5 Age Groups**: More robust than exact age regression ✅    {'label': 'Middle Age (41-60)', 'score': 0.09},
+
+- **Bias-Free**: 75-year-olds correctly classified as "Senior (61-80)" ✅    {'label': 'Elderly (81-100)', 'score': 0.03},
+
+- **Practical**: Returns useful age ranges for real applications ✅    {'label': 'Young Adult (21-40)', 'score': 0.01},
+
+- **Reliable**: 75.5% validation accuracy with stable predictions ✅    {'label': 'Youth (0-20)', 'score': 0.00}
+
 ]
-```
 
-## Training Details
+## 📊 Model Performance```
+
+
+
+| Metric | Value | Description |## Training Details
+
+|--------|-------|-------------|
+
+| **Validation Accuracy** | **75.5%** | 5-class classification accuracy |### Dataset
+
+| **Training Accuracy** | **79.1%** | Training set performance |- **Source**: UTKFace dataset
+
+| **Generalization Gap** | **3.6%** | Healthy gap - no overfitting |- **Size**: 23,687 facial images
+
+| **Training Epochs** | **13** | Early stopping applied |- **Split**: 80% training, 20% validation
+
+| **Parameters** | **23.8M** | ResNet50V2 backbone |- **Preprocessing**: Stratified sampling to ensure balanced age group representation
+
 
-### Dataset
-- **Source**: UTKFace dataset
-- **Size**: 23,687 facial images
-- **Split**: 80% training, 20% validation
-- **Preprocessing**: Stratified sampling to ensure balanced age group representation
 
-### Training Process
+## 🏷️ Age Groups### Training Process
+
 1. **Phase 1**: Frozen ResNet50V2 base, train classification head only
-2. **Phase 2**: Fine-tune top layers with reduced learning rate
-3. **Early Stopping**: Automatic termination when validation plateaus
 
-### Training Configuration
-- **Optimizer**: Adam
-- **Learning Rate**: 0.001 → 0.0001 (Phase 2)
-- **Loss Function**: Categorical Crossentropy
+| Group ID | Age Range | Label | Description |2. **Phase 2**: Fine-tune top layers with reduced learning rate
+
+|----------|-----------|-------|-------------|3. **Early Stopping**: Automatic termination when validation plateaus
+
+| 0 | 0-20 years | Youth | Children, teenagers |
+
+| 1 | 21-40 years | Young Adult | College age to early career |### Training Configuration
+
+| 2 | 41-60 years | Middle Age | Established adults |- **Optimizer**: Adam
+
+| 3 | 61-80 years | Senior | Retirement age |- **Learning Rate**: 0.001 → 0.0001 (Phase 2)
+
+| 4 | 81-100 years | Elderly | Advanced age |- **Loss Function**: Categorical Crossentropy
+
 - **Batch Size**: 32
-- **Callbacks**: Early stopping, model checkpointing, learning rate reduction
 
-## Bias Validation
+## 🔧 Technical Details- **Callbacks**: Early stopping, model checkpointing, learning rate reduction
+
+
+
+### Architecture## Bias Validation
+
+- **Base Model**: ResNet50V2 (pre-trained on ImageNet)
+
+- **Task**: Multi-class classification (5 categories)### Test Cases
+
+- **Input**: RGB facial images (224×224)| Input Age | Predicted Group | Correct? |
+
+- **Output**: Age group probabilities|-----------|----------------|----------|
+
+- **Transfer Learning**: 2-phase training (frozen base → fine-tuning)| 25 years | Young Adult (21-40) | ✅ |
 
-### Test Cases
-| Input Age | Predicted Group | Correct? |
-|-----------|----------------|----------|
-| 25 years | Young Adult (21-40) | ✅ |
 | 35 years | Young Adult (21-40) | ✅ |
-| 45 years | Middle Age (41-60) | ✅ |
-| 55 years | Middle Age (41-60) | ✅ |
-| 65 years | Senior (61-80) | ✅ |
-| 75 years | Senior (61-80) | ✅ **Fixed!** |
-| 85 years | Elderly (81-100) | ✅ |
 
-## Limitations
+### Training Configuration| 45 years | Middle Age (41-60) | ✅ |
+
+- **Framework**: TensorFlow/Keras| 55 years | Middle Age (41-60) | ✅ |
+
+- **Optimizer**: Adam (lr: 0.001 → 0.0001)| 65 years | Senior (61-80) | ✅ |
+
+- **Loss Function**: Categorical Crossentropy| 75 years | Senior (61-80) | ✅ **Fixed!** |
+
+- **Batch Size**: 32| 85 years | Elderly (81-100) | ✅ |
+
+- **Data Split**: 80% train, 20% validation (stratified)
 
-- Performance may vary with extreme lighting conditions
-- Border cases between age groups (e.g., 40 vs 41) inherently challenging
-- Optimized for front-facing facial images
-- Cultural and demographic variations may affect accuracy
+- **Early Stopping**: Patience=3 epochs## Limitations
+
+
+
+### Dataset- Performance may vary with extreme lighting conditions
+
+- **Source**: UTKFace dataset- Border cases between age groups (e.g., 40 vs 41) inherently challenging
+
+- **Size**: 23,687 facial images- Optimized for front-facing facial images
+
+- **Age Distribution**: Balanced across age groups- Cultural and demographic variations may affect accuracy
+
+- **Preprocessing**: Stratified sampling for equal representation
 
 ## Ethical Considerations
 
+## 🎯 Bias Validation
+
 - **Bias Mitigation**: Specifically designed to reduce age prediction bias
-- **Fairness**: Balanced training across age groups
-- **Transparency**: Clear category boundaries rather than black-box exact ages
-- **Privacy**: Consider consent when processing facial images
 
-## Citation
+### Test Results- **Fairness**: Balanced training across age groups
 
-If you use this model, please cite:
+| Input Age | Predicted Group | Status |- **Transparency**: Clear category boundaries rather than black-box exact ages
+
+|-----------|----------------|---------|- **Privacy**: Consider consent when processing facial images
+
+| 15 years | Youth (0-20) | ✅ Correct |
+
+| 25 years | Young Adult (21-40) | ✅ Correct |## Citation
+
+| 35 years | Young Adult (21-40) | ✅ Correct |
+
+| 45 years | Middle Age (41-60) | ✅ Correct |If you use this model, please cite:
+
+| 55 years | Middle Age (41-60) | ✅ Correct |
+
+| 65 years | Senior (61-80) | ✅ Correct |```bibtex
+
+| **75 years** | **Senior (61-80)** | ✅ **BIAS FIXED!** |@misc{age-group-classifier-2025,
+
+| 85 years | Elderly (81-100) | ✅ Correct |  title={Age Group Classification Model: Bias-Free Facial Age Estimation},
 
-```bibtex
-@misc{age-group-classifier-2025,
-  title={Age Group Classification Model: Bias-Free Facial Age Estimation},
   author={SammyHarris},
-  year={2025},
+
+**Key Achievement**: 70+ year olds are now correctly classified as Senior/Elderly instead of being mispredicted as young adults!  year={2025},
+
   publisher={Hugging Face},
-  howpublished={\url{https://huggingface.co/your-username/age-group-classifier}}
+
+## 💡 Use Cases  howpublished={\url{https://huggingface.co/your-username/age-group-classifier}}
+
 }
-```
 
-## License
+### ✅ Recommended Applications```
+
+- **Content Personalization**: Age-appropriate content delivery
+
+- **Market Research**: Demographic analysis of audiences## License
+
+- **Photo Organization**: Automatic family album categorization
+
+- **Social Media**: Age group insights and targetingThis model is released under the MIT License.
+
+- **Research**: Age-related studies and analysis
+
+- **Accessibility**: Age-aware interface design## Contact
+
 
-This model is released under the MIT License.
 
-## Contact
+### ❌ LimitationsFor questions or issues, please open a discussion on the model repository.
+
+- **Border Cases**: Ages near group boundaries (e.g., 40 vs 41) can be challengingdatasets:
+
+- **Image Quality**: Performance varies with lighting and image quality- UTKFace
+
+- **Pose Sensitivity**: Works best with frontal face imagesmetrics:
+
+- **Demographic Bias**: May vary across different ethnic groups- mae
+
+- **Not for Legal Use**: Estimates only, not for official identification- mean_absolute_error
 
-For questions or issues, please open a discussion on the model repository.
-datasets:
-- UTKFace
-metrics:
-- mae
-- mean_absolute_error
 model-index:
-- name: age-detection-resnet50-model
+
+## 🔬 Model Files- name: age-detection-resnet50-model
+
   results:
-  - task:
-      type: image-regression
-      name: Age Estimation from Facial Images
+
+- **`resnet50v2_age_classifier_best.h5`**: Complete trained model (98MB)  - task:
+
+- **`config.json`**: Model configuration and label mappings      type: image-regression
+
+- **`README.md`**: This comprehensive model card      name: Age Estimation from Facial Images
+
     dataset:
-      type: UTKFace
+
+## 🤖 Live Demo      type: UTKFace
+
       name: UTKFace Dataset
-    metrics:
-    - type: mae
+
+Try the model instantly with our Gradio demo:    metrics:
+
+**[Age Group Classifier Demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo)**    - type: mae
+
       value: 19.96
-      name: Mean Absolute Error
-      verified: true
-widget:
-- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpg
-  example_title: Sample Face Image
+
+Features:      name: Mean Absolute Error
+
+- Upload facial images      verified: true
+
+- Get age group predictionswidget:
+
+- View confidence scores for all groups- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpg
+
+- Compare predictions across different ages  example_title: Sample Face Image
+
 pipeline_tag: image-regression
-base_model: microsoft/resnet-50
+
+## 📜 License & Ethicsbase_model: microsoft/resnet-50
+
 ---
 
-# Age Detection with ResNet50 🎯👨‍👩‍👧‍👦
+### License
 
-A state-of-the-art age estimation model using ResNet50 backbone with advanced bias correction techniques. This model predicts human age from facial images with high accuracy (**9.77 years MAE** - 51% improvement over baseline) and addresses systematic age prediction biases through improved square root sample weighting.
+- **Model**: MIT License# Age Detection with ResNet50 🎯👨‍👩‍👧‍👦
 
-## 🚀 Quick Start
+- **Code**: MIT License
+
+- **Dataset**: UTKFace (academic/research use)A state-of-the-art age estimation model using ResNet50 backbone with advanced bias correction techniques. This model predicts human age from facial images with high accuracy (**9.77 years MAE** - 51% improvement over baseline) and addresses systematic age prediction biases through improved square root sample weighting.
+
+
+
+### Ethical Considerations## 🚀 Quick Start
+
+- **Bias Mitigation**: Specifically designed to reduce age prediction bias
+
+- **Fairness**: Balanced training across all age groups```python
+
+- **Transparency**: Clear category boundaries and confidence scoresimport tensorflow as tf
+
+- **Privacy**: Consider consent when processing facial imagesimport numpy as np
+
+- **Responsible Use**: Avoid high-stakes decisions without human oversightfrom PIL import Image
 
-```python
-import tensorflow as tf
-import numpy as np
-from PIL import Image
 from tensorflow.keras.applications.resnet50 import preprocess_input
 
+## 📚 Citation
+
 # Load the model
-model = tf.keras.models.load_model('best_model.h5')
 
-# Preprocess image
-img = Image.open('face_image.jpg').convert('RGB').resize((256, 256))
-arr = np.array(img, dtype=np.float32)
-arr = preprocess_input(arr)
-arr = np.expand_dims(arr, 0)
+If you use this model in your research, please cite:model = tf.keras.models.load_model('best_model.h5')
+
+
+
+```bibtex# Preprocess image
+
+@misc{age-group-classifier-2025,img = Image.open('face_image.jpg').convert('RGB').resize((256, 256))
+
+  title={Age Group Classification: Solving Age Prediction Bias in Facial Analysis},arr = np.array(img, dtype=np.float32)
+
+  author={Sharris},arr = preprocess_input(arr)
+
+  year={2025},arr = np.expand_dims(arr, 0)
+
+  publisher={Hugging Face},
+
+  url={https://huggingface.co/Sharris/age-group-classifier}# Predict age
+
+}predicted_age = model.predict(arr)[0][0]
+
+```print(f"Predicted age: {predicted_age:.1f} years")
 
-# Predict age
-predicted_age = model.predict(arr)[0][0]
-print(f"Predicted age: {predicted_age:.1f} years")
 ```
 
+## 🤝 Contact & Support
+
 ## 🎯 Model Overview
 
-This model addresses the critical challenge of age estimation bias commonly found in facial analysis systems. Through sophisticated bias correction techniques and robust training methodologies, it achieves superior performance across diverse age groups.
+- **Model Repository**: [Sharris/age-group-classifier](https://huggingface.co/Sharris/age-group-classifier)
+
+- **Demo Space**: [age-group-classifier-demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo)This model addresses the critical challenge of age estimation bias commonly found in facial analysis systems. Through sophisticated bias correction techniques and robust training methodologies, it achieves superior performance across diverse age groups.
+
+- **Issues**: Use the discussions tab for questions and feedback
 
 ## 📊 Model Performance
 
+---
+
 | Metric | Value | Description |
-|--------|-------|-------------|
+
+**🎉 Ready to use bias-free age group classification?** Try our [live demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo) or integrate the model into your applications today!|--------|-------|-------------|
 | **Mean Absolute Error (MAE)** | **9.77 years** | Average prediction error (51% improvement) |
 | **Architecture** | ResNet50 | Pre-trained on ImageNet |
 | **Input Resolution** | 256×256×3 | RGB facial images |