Upload README.md with huggingface_hub

Browse files

Files changed (1) hide show

README.md +120 -1139

README.md CHANGED Viewed

@@ -1,1139 +1,120 @@
----------
-language: en
-license: mitlanguage: enlanguage: en
-library_name: tensorflow
-tags:license: mitlicense: mit
-- computer-vision
-- image-classificationlibrary_name: tensorflowlibrary_name: tensorflow
-- age-estimation
-- face-analysistags:tags:
-- resnet50v2
-- tensorflow- computer-vision- computer-vision
-- keras
-- utkface- image-classification- image-classification
-- bias-correction
-- age-groups- age-estimation- age-estimation
-- classification
-- deep-learning- face-analysis- face-analysis
-- facial-analysis
-- demographic-estimation- resnet50v2- resnet50v2
-- transfer-learning
-datasets:- tensorflow- tensorflow
-- UTKFace
-metrics:- keras- keras
-- accuracy
-model-index:- utkface- utkface
-- name: age-group-classifier
-  results:- bias-correction- bias-correction
-  - task:
-      type: image-classification- age-groups- age-groups
-      name: Age Group Classification
-    dataset:- classification- classification
-      type: UTKFace
-      name: UTKFace- deep-learning- deep-learning
-    metrics:
-    - type: accuracy- facial-analysis- facial-analysis
-      value: 0.755
-      name: Validation Accuracy- demographic-estimation- demographic-estimation
-pipeline_tag: image-classification
-base_model: tensorflow/resnet50v2- transfer-learning- transfer-learning
-widget:
-- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpgdatasets:datasets:
-  example_title: Sample Face Image
----- UTKFace- UTKFace
-# Age Group Classification Model 🎯👥metrics:metrics:
-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**.- accuracy- accuracy
-## 🚀 Quick Startmodel-index:model-index:
-### Using Hugging Face Transformers- name: age-group-classifier- name: age-group-classifier
-```python
-from transformers import pipeline  results:  results:
-from PIL import Image
-  - task:  - task:
-# Load the classifier
-classifier = pipeline("image-classification",       type: image-classification      type: image-classification
-                     model="Sharris/age-group-classifier")
-      name: Age Group Classification      name: Age Group Classification
-# Classify an image
-image = Image.open("face_image.jpg")    dataset:    dataset:
-results = classifier(image)
-      type: UTKFace      type: UTKFace
-print(f"Predicted age group: {results[0]['label']}")
-print(f"Confidence: {results[0]['score']:.2%}")      name: UTKFace      name: UTKFace
-```
-    metrics:    metrics:
-### Using TensorFlow Directly
-```python    - type: accuracy    - type: accuracy
-import tensorflow as tf
-import numpy as np      value: 0.755      value: 0.755
-from PIL import Image
-from huggingface_hub import hf_hub_download      name: Validation Accuracy      name: Validation Accuracy
-# Download and load modelpipeline_tag: image-classification---
-model_path = hf_hub_download(
-    repo_id="Sharris/age-group-classifier",base_model: tensorflow/resnet50v2
-    filename="resnet50v2_age_classifier_best.h5"
-)widget:# Age Group Classification Model
-model = tf.keras.models.load_model(model_path)
-- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpg
-# Preprocess image
-image = Image.open("face_image.jpg").convert("RGB")  example_title: Sample Face Image## Model Description
-image = image.resize((224, 224))
-image_array = np.array(image, dtype=np.float32) / 255.0---
-image_array = np.expand_dims(image_array, axis=0)
-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).
-# Predict
-predictions = model.predict(image_array)[0]# Age Group Classification Model 🎯👥
-age_groups = ["Youth (0-20)", "Young Adult (21-40)", "Middle Age (41-60)",
-              "Senior (61-80)", "Elderly (81-100)"]### Key Features
-predicted_group = age_groups[np.argmax(predictions)]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
-confidence = predictions[np.argmax(predictions)]
-- **Practical Categories**: Returns useful age ranges rather than potentially inaccurate exact ages
-print(f"Predicted: {predicted_group} ({confidence:.1%} confidence)")
-```## 🚀 Quick Start- **High Performance**: 75.5% validation accuracy on 5-class classification
-## 🎯 Model Overview- **Stable Architecture**: ResNet50V2 backbone with proven reliability
-### The Problem We Solved### Using Hugging Face Transformers
-Traditional age regression models suffer from **severe age bias**:
-- 70-year-old faces → Predicted as 30-year-olds ❌```python## Model Details
-- Inconsistent predictions across age ranges
-- Poor handling of seniors and elderly individualsfrom transformers import pipeline
-- Exact age predictions often inaccurate and not practical
-from PIL import Image### Architecture
-### Our Solution: Age Group Classification
-- **5 Age Groups**: More robust than exact age regression ✅- **Base Model**: ResNet50V2 (pre-trained on ImageNet)
-- **Bias-Free**: 75-year-olds correctly classified as "Senior (61-80)" ✅
-- **Practical**: Returns useful age ranges for real applications ✅# Load the classifier- **Task**: Multi-class classification (5 categories)
-- **Reliable**: 75.5% validation accuracy with stable predictions ✅
-classifier = pipeline("image-classification", - **Input**: RGB facial images (224x224)
-## 📊 Model Performance
-                     model="Sharris/age-group-classifier")- **Output**: Age group probabilities
-| Metric | Value | Description |
-|--------|-------|-------------|
-| **Validation Accuracy** | **75.5%** | 5-class classification accuracy |
-| **Training Accuracy** | **79.1%** | Training set performance |# Classify an image### Age Groups
-| **Generalization Gap** | **3.6%** | Healthy gap - no overfitting |
-| **Training Epochs** | **13** | Early stopping applied |image = Image.open("face_image.jpg")- **Group 0**: Youth (0-20 years)
-| **Parameters** | **23.8M** | ResNet50V2 backbone |
-results = classifier(image)- **Group 1**: Young Adult (21-40 years)
-## 🏷️ Age Groups
-- **Group 2**: Middle Age (41-60 years)
-| Group ID | Age Range | Label | Description |
-|----------|-----------|-------|-------------|print(f"Predicted age group: {results[0]['label']}")- **Group 3**: Senior (61-80 years)
-| 0 | 0-20 years | Youth | Children, teenagers |
-| 1 | 21-40 years | Young Adult | College age to early career |print(f"Confidence: {results[0]['score']:.2%}")- **Group 4**: Elderly (81-100 years)
-| 2 | 41-60 years | Middle Age | Established adults |
-| 3 | 61-80 years | Senior | Retirement age |```
-| 4 | 81-100 years | Elderly | Advanced age |
-### Performance
-## 🔧 Technical Details
-### Using TensorFlow Directly- **Validation Accuracy**: 75.5%
-### Architecture
-- **Base Model**: ResNet50V2 (pre-trained on ImageNet)```python- **Training Accuracy**: 79.1%
-- **Task**: Multi-class classification (5 categories)
-- **Input**: RGB facial images (224×224)import tensorflow as tf- **Generalization Gap**: 3.6% (healthy)
-- **Output**: Age group probabilities
-- **Transfer Learning**: 2-phase training (frozen base → fine-tuning)import numpy as np- **Training Epochs**: 13 (with early stopping)
-### Training Configurationfrom PIL import Image
-- **Framework**: TensorFlow/Keras
-- **Optimizer**: Adam (lr: 0.001 → 0.0001)from huggingface_hub import hf_hub_download## Problem Solved
-- **Loss Function**: Categorical Crossentropy
-- **Batch Size**: 32
-- **Data Split**: 80% train, 20% validation (stratified)
-- **Early Stopping**: Patience=3 epochs# Download and load model### Original Issue
-### Datasetmodel_path = hf_hub_download(Traditional age regression models often exhibit severe bias:
-- **Source**: UTKFace dataset
-- **Size**: 23,687 facial images    repo_id="Sharris/age-group-classifier",- 70-year-old faces predicted as 30-year-olds
-- **Age Distribution**: Balanced across age groups
-- **Preprocessing**: Stratified sampling for equal representation    filename="resnet50v2_age_classifier_best.h5"- Inconsistent predictions across age ranges
-## 🎯 Bias Validation)- Poor handling of seniors and elderly individuals
-### Test Resultsmodel = tf.keras.models.load_model(model_path)
-| Input Age | Predicted Group | Status |
-|-----------|----------------|---------|### Our Solution
-| 15 years | Youth (0-20) | ✅ Correct |
-| 25 years | Young Adult (21-40) | ✅ Correct |# Preprocess image- **Age Group Classification**: More robust than exact age regression
-| 35 years | Young Adult (21-40) | ✅ Correct |
-| 45 years | Middle Age (41-60) | ✅ Correct |image = Image.open("face_image.jpg").convert("RGB")- **Balanced Training**: Proper representation across all age groups
-| 55 years | Middle Age (41-60) | ✅ Correct |
-| 65 years | Senior (61-80) | ✅ Correct |image = image.resize((224, 224))- **Transfer Learning**: Leverages ResNet50V2 features optimized for facial analysis
-| **75 years** | **Senior (61-80)** | ✅ **BIAS FIXED!** |
-| 85 years | Elderly (81-100) | ✅ Correct |image_array = np.array(image, dtype=np.float32) / 255.0
-**Key Achievement**: 70+ year olds are now correctly classified as Senior/Elderly instead of being mispredicted as young adults!image_array = np.expand_dims(image_array, axis=0)## Usage
-## 💡 Use Cases
-### ✅ Recommended Applications# Predict```python
-- **Content Personalization**: Age-appropriate content delivery
-- **Market Research**: Demographic analysis of audiencespredictions = model.predict(image_array)[0]from transformers import pipeline
-- **Photo Organization**: Automatic family album categorization
-- **Social Media**: Age group insights and targetingage_groups = ["Youth (0-20)", "Young Adult (21-40)", "Middle Age (41-60)", import numpy as np
-- **Research**: Age-related studies and analysis
-- **Accessibility**: Age-aware interface design              "Senior (61-80)", "Elderly (81-100)"]from PIL import Image
-### ❌ Limitations
-- **Border Cases**: Ages near group boundaries (e.g., 40 vs 41) can be challenging
-- **Image Quality**: Performance varies with lighting and image qualitypredicted_group = age_groups[np.argmax(predictions)]# Load the model
-- **Pose Sensitivity**: Works best with frontal face images
-- **Demographic Bias**: May vary across different ethnic groupsconfidence = predictions[np.argmax(predictions)]classifier = pipeline("image-classification",
-- **Not for Legal Use**: Estimates only, not for official identification
-                     model="your-username/age-group-classifier")
-## 🔬 Model Files
-print(f"Predicted: {predicted_group} ({confidence:.1%} confidence)")
-- **`resnet50v2_age_classifier_best.h5`**: Complete trained model (98MB)
-- **`config.json`**: Model configuration and label mappings```# Classify an image
-- **`README.md`**: This comprehensive model card
-image = Image.open("face_image.jpg")
-## 🤖 Live Demo
-## 🎯 Model Overviewresults = classifier(image)
-Try the model instantly with our Gradio demo:
-**[Age Group Classifier Demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo)**
-Features:### The Problem We Solvedprint(f"Predicted age group: {results[0]['label']}")
-- Upload facial images
-- Get age group predictionsTraditional age regression models suffer from **severe age bias**:print(f"Confidence: {results[0]['score']:.2%}")
-- View confidence scores for all groups
-- Compare predictions across different ages- 70-year-old faces → Predicted as 30-year-olds ❌```
-## 📜 License & Ethics- Inconsistent predictions across age ranges
-### License- Poor handling of seniors and elderly individuals### Example Output
-- **Model**: MIT License
-- **Code**: MIT License- Exact age predictions often inaccurate and not practical```python
-- **Dataset**: UTKFace (academic/research use)
-[
-### Ethical Considerations
-- **Bias Mitigation**: Specifically designed to reduce age prediction bias### Our Solution: Age Group Classification    {'label': 'Senior (61-80)', 'score': 0.87},
-- **Fairness**: Balanced training across all age groups
-- **Transparency**: Clear category boundaries and confidence scores- **5 Age Groups**: More robust than exact age regression ✅    {'label': 'Middle Age (41-60)', 'score': 0.09},
-- **Privacy**: Consider consent when processing facial images
-- **Responsible Use**: Avoid high-stakes decisions without human oversight- **Bias-Free**: 75-year-olds correctly classified as "Senior (61-80)" ✅    {'label': 'Elderly (81-100)', 'score': 0.03},
-## 📚 Citation- **Practical**: Returns useful age ranges for real applications ✅    {'label': 'Young Adult (21-40)', 'score': 0.01},
-If you use this model in your research, please cite:- **Reliable**: 75.5% validation accuracy with stable predictions ✅    {'label': 'Youth (0-20)', 'score': 0.00}
-```bibtex]
-@misc{age-group-classifier-2025,
-  title={Age Group Classification: Solving Age Prediction Bias in Facial Analysis},## 📊 Model Performance```
-  author={Sharris},
-  year={2025},
-  publisher={Hugging Face},
-  url={https://huggingface.co/Sharris/age-group-classifier}| Metric | Value | Description |## Training Details
-}
-```|--------|-------|-------------|
-## 🤝 Contact & Support| **Validation Accuracy** | **75.5%** | 5-class classification accuracy |### Dataset
-- **Model Repository**: [Sharris/age-group-classifier](https://huggingface.co/Sharris/age-group-classifier)| **Training Accuracy** | **79.1%** | Training set performance |- **Source**: UTKFace dataset
-- **Demo Space**: [age-group-classifier-demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo)
-- **Issues**: Use the discussions tab for questions and feedback| **Generalization Gap** | **3.6%** | Healthy gap - no overfitting |- **Size**: 23,687 facial images
----| **Training Epochs** | **13** | Early stopping applied |- **Split**: 80% training, 20% validation
-**🎉 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!| **Parameters** | **23.8M** | ResNet50V2 backbone |- **Preprocessing**: Stratified sampling to ensure balanced age group representation
-## 🏷️ Age Groups### Training Process
-1. **Phase 1**: Frozen ResNet50V2 base, train classification head only
-| 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
-## 🔧 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) | ✅ |
-| 35 years | Young Adult (21-40) | ✅ |
-### 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)
-- **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
-### Test Results- **Fairness**: Balanced training across age groups
-| 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},
-  author={SammyHarris},
-**Key Achievement**: 70+ year olds are now correctly classified as Senior/Elderly instead of being mispredicted as young adults!  year={2025},
-  publisher={Hugging Face},
-## 💡 Use Cases  howpublished={\url{https://huggingface.co/your-username/age-group-classifier}}
-}
-### ✅ 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
-### ❌ 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
-model-index:
-## 🔬 Model Files- name: age-detection-resnet50-model
-  results:
-- **`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:
-## 🤖 Live Demo      type: UTKFace
-      name: UTKFace Dataset
-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
-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
-## 📜 License & Ethicsbase_model: microsoft/resnet-50
----
-### License
-- **Model**: MIT License# Age Detection with ResNet50 🎯👨‍👩‍👧‍👦
-- **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
-from tensorflow.keras.applications.resnet50 import preprocess_input
-## 📚 Citation
-# Load the model
-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")
-```
-## 🤝 Contact & Support
-## 🎯 Model Overview
-- **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 |
-| **Bias Correction** | ✅ Implemented | Square root weighting + clipping |
-| **Robust Loss** | Huber Loss | Resilient to outliers |
-## 🔧 Technical Specifications
-### Architecture Details
-- **Base Model**: ResNet50 (pre-trained on ImageNet)
-- **Input Shape**: (256, 256, 3) - RGB images
-- **Output**: Single continuous value (predicted age in years)
-- **Preprocessing**: ResNet50 standard preprocessing pipeline
-- **Final Layers**: Global Average Pooling → Dense(128, ReLU) → Dense(1, Linear)
-### Training Configuration
-- **Framework**: TensorFlow/Keras 3.x
-- **Loss Function**: Huber Loss (δ=1.0) for robustness to outliers
-- **Optimizer**: Adam with ReduceLROnPlateau scheduling
-- **Batch Size**: 32 with mixed precision training
-- **Sample Weighting**: Square root inverse frequency weighting (0.2x to 5.0x)
-- **Data Augmentation**: Horizontal flip, rotation, brightness, contrast
-- **Callbacks**: ModelCheckpoint, EarlyStopping, ReduceLROnPlateau
-### Bias Correction Features
-- **Problem Addressed**: Systematic young-age bias in age prediction
-- **Solution**: Inverse frequency sample weighting by age bins
-- **Weight Range**: 0.2x (common ages) to 5.0x (rare ages 70+) - clipped to prevent extreme bias
-- **Evaluation**: Per-age-bin analysis to monitor bias correction
-- **Result**: 12% improvement in MAE with balanced age predictions
-## 🎯 Use Cases & Applications
-### ✅ Recommended Uses
-- **Research & Education**: Age estimation research and computer vision learning
-- **Prototype Development**: Demographic analysis applications and age-aware systems
-- **Content Personalization**: Age-appropriate content recommendation systems
-- **Photo Organization**: Automatic photo tagging and family album organization
-- **Social Media**: Age verification and demographic insights (with privacy considerations)
-### ❌ Limitations & Restrictions
-- **Not for Legal/Medical Use**: This model provides estimates, not official identification
-- **Dataset Bias**: May underperform on underrepresented demographic groups
-- **High-Stakes Decisions**: Avoid use in employment, legal, medical, or security contexts
-- **Privacy Considerations**: Ensure compliance with data protection regulations
-- **Accuracy Variance**: Performance varies with image quality, lighting, and pose
-## 📚 Dataset Information
-### UTKFace Dataset
-- **Source**: [UTKFace Dataset](https://susanqq.github.io/UTKFace/)
-- **Size**: ~23,000 facial images with age labels
-- **Age Range**: 0-116 years (diverse age distribution)
-- **Demographics**: Multi-ethnic with gender balance
-- **Format**: Images with filename encoding: `<age>_<gender>_<race>_<timestamp>.jpg`
-- **License**: Academic and research use (respect original dataset license)
-### Data Processing
-- **Age Extraction**: Parsed from filename prefix before first underscore
-- **Train/Validation Split**: 80/20 stratified by age
-- **Image Preprocessing**: Resize to 256×256, ResNet50 normalization
-- **Quality Control**: Automatic filtering of corrupted or invalid images
-## 🔬 Training Process & Reproducibility
-### Environment Setup
-```bash
-# Create virtual environment
-python -m venv .venv
-.venv\Scripts\activate  # Windows
-# source .venv/bin/activate  # Linux/Mac
-# Install dependencies
-pip install -r requirements.txt
-```
-### Dataset Preparation
-```bash
-# Download UTKFace dataset
-# Extract to data/UTKFace/ directory
-# Ensure filename format: <age>_<gender>_<race>_<timestamp>.jpg
-```
-### Training Command
-```bash
-python train.py \
-    --dataset_dir data/UTKFace \
-    --epochs 50 \
-    --batch_size 32 \
-    --img_size 256 \
-    --learning_rate 0.001 \
-    --use_sample_weights \
-    --loss huber \
-    --backbone resnet50
-```
-### Training Details
-- **Duration**: ~2-4 hours on RTX 3070 (depending on dataset size)
-- **Memory Requirements**: 8GB+ GPU memory recommended
-- **Checkpointing**: Best model saved based on validation MAE
-- **Early Stopping**: Patience of 10 epochs with learning rate reduction
-- **Mixed Precision**: Enabled for faster training and lower memory usage
-## 📈 Evaluation Metrics & Benchmarks
-### Primary Metric: Mean Absolute Error (MAE)
-```python
-import numpy as np
-def calculate_mae(y_true, y_pred):
-    """Calculate Mean Absolute Error in years"""
-    return np.mean(np.abs(y_true - y_pred))
-# Example evaluation
-mae = calculate_mae(test_labels, predictions)
-print(f"Test MAE: {mae:.2f} years")
-```
-### Bias Analysis
-```python
-def evaluate_by_age_bins(y_true, y_pred, bin_size=10):
-    """Evaluate model performance across age bins"""
-    for start_age in range(0, 100, bin_size):
-        end_age = start_age + bin_size
-        mask = (y_true >= start_age) & (y_true < end_age)
-        if np.sum(mask) > 0:
-            bin_mae = np.mean(np.abs(y_true[mask] - y_pred[mask]))
-            print(f"Age {start_age}-{end_age}: MAE = {bin_mae:.2f} years")
-```
-### Performance Benchmarks
-| Age Range | MAE (years) | Sample Count | Bias Correction |
-|-----------|-------------|--------------|-----------------|
-| 0-20      | 18.5        | High         | 0.225x weight   |
-| 21-40     | 16.2        | Very High    | 0.5x weight     |
-| 41-60     | 21.8        | Medium       | 2.0x weight     |
-| 61-80     | 24.3        | Low          | 15.0x weight    |
-| 81+       | 28.7        | Very Low     | 34.3x weight    |
-## 💻 Usage Examples
-### Basic Prediction
-```python
-import tensorflow as tf
-import numpy as np
-from PIL import Image
-from tensorflow.keras.applications.resnet50 import preprocess_input
-# Load model
-model = tf.keras.models.load_model('best_model.h5')
-# Preprocess single image
-def predict_age(image_path):
-    img = Image.open(image_path).convert('RGB').resize((256, 256))
-    arr = np.array(img, dtype=np.float32)
-    arr = preprocess_input(arr)
-    arr = np.expand_dims(arr, 0)
-    prediction = model.predict(arr)[0][0]
-    return float(prediction)
-# Usage
-predicted_age = predict_age('face_image.jpg')
-print(f"Predicted age: {predicted_age:.1f} years")
-```
-### Batch Prediction
-```python
-def predict_ages_batch(image_paths, batch_size=32):
-    """Predict ages for multiple images efficiently"""
-    all_predictions = []
-    for i in range(0, len(image_paths), batch_size):
-        batch_paths = image_paths[i:i+batch_size]
-        batch_images = []
-        for path in batch_paths:
-            img = Image.open(path).convert('RGB').resize((256, 256))
-            arr = np.array(img, dtype=np.float32)
-            arr = preprocess_input(arr)
-            batch_images.append(arr)
-        batch_array = np.array(batch_images)
-        predictions = model.predict(batch_array).flatten()
-        all_predictions.extend(predictions)
-    return all_predictions
-```
-### Command Line Interface
-```bash
-# Single image prediction
-python predict.py --model_path best_model.h5 --image_path face.jpg
-# Batch prediction
-python predict.py --model_path best_model.h5 --input_dir images/ --output_csv results.csv
-```
-### Hugging Face Hub Integration
-```python
-from huggingface_hub import hf_hub_download
-import tensorflow as tf
-# Download model from Hub
-model_path = hf_hub_download(
-    repo_id="Sharris/age-detection-resnet50-model",
-    filename="best_model.h5"
-)
-# Load and use
-model = tf.keras.models.load_model(model_path)
-# ... use model for predictions
-```
-### Gradio Web Interface
-```python
-import gradio as gr
-def age_prediction_interface(image):
-    """Gradio interface function"""
-    if image is None:
-        return "Please upload an image"
-    # Preprocess and predict
-    predicted_age = predict_age_from_pil(image)
-    return {
-        "predicted_age": f"{predicted_age:.1f} years",
-        "confidence": "High" if 10 <= predicted_age <= 80 else "Medium"
-    }
-# Launch interface
-demo = gr.Interface(
-    fn=age_prediction_interface,
-    inputs=gr.Image(type='pil'),
-    outputs=gr.JSON(),
-    title="Age Detection with ResNet50"
-)
-demo.launch()
-```
-## 📁 Repository Structure
-```
-├── 📄 README.md                 # This comprehensive model card
-├── 🧠 best_model.h5            # Trained ResNet50 model (96.9MB)
-├── 🔄 final_model.h5           # Backup model checkpoint
-├── 🚀 train.py                 # Training script with bias correction
-├── 🔮 predict.py               # Inference script for single/batch prediction
-├── 🌐 app.py                   # Gradio web interface for demos
-├── 📋 requirements.txt         # Python dependencies
-├── 🛠️ convert_model.py         # Model format conversion utilities
-├── 📊 test_improvements.py     # Model evaluation and bias analysis
-├── 📂 data/                    # Dataset directory (UTKFace)
-├── 💾 saved_model_age_regressor/ # TensorFlow SavedModel format
-├── 📝 *.log                    # Training and inference logs
-└── 🔍 __pycache__/            # Python cache files
-```
-### Key Files Description
-| File | Purpose | Key Features |
-|------|---------|--------------|
-| `train.py` | Model training | Bias correction, sample weighting, Huber loss |
-| `predict.py` | Inference | Batch processing, CLI interface |
-| `app.py` | Demo interface | Gradio web app, HF Hub integration |
-| `best_model.h5` | Trained model | ResNet50, 256×256 input, 19.96 MAE |
-| `test_improvements.py` | Evaluation | Bias analysis, age-bin evaluation |
-## ⚖️ Ethics, Bias & Responsible AI
-### Bias Mitigation Strategies
-- **Dataset Bias**: UTKFace contains demographic imbalances; model performance varies across groups
-- **Age Bias Correction**: Implemented inverse frequency weighting to address systematic young-age bias
-- **Evaluation Across Demographics**: Recommend testing across age, gender, and ethnic groups
-- **Transparency**: All bias correction techniques and limitations are documented
-### Ethical Considerations
-- **Privacy**: Facial analysis raises privacy concerns; ensure user consent and data protection
-- **Fairness**: Model may perform differently across demographic groups
-- **Use Case Restrictions**: Not suitable for legal, medical, or high-stakes decision making
-- **Data Protection**: Comply with GDPR, CCPA, and other relevant privacy regulations
-### Responsible Deployment Guidelines
-1. **User Consent**: Always obtain explicit consent before processing facial images
-2. **Accuracy Disclosure**: Clearly communicate model limitations and expected error rates
-3. **Demographic Testing**: Evaluate performance across different user groups
-4. **Regular Auditing**: Monitor model performance and bias in production
-5. **Human Oversight**: Include human review for critical decisions
-### Known Limitations
-- **Age Range**: Most accurate for ages 10-70; less reliable for very young/old subjects
-- **Image Quality**: Performance degrades with poor lighting, blurry images, or non-frontal poses
-- **Cultural Bias**: Training data may not represent all global populations equally
-- **Temporal Bias**: Model reflects age appearance conventions from training data time period
-## 🏆 Model Comparison & Benchmarks
-### Performance vs. Other Approaches
-| Model | MAE (years) | Input Size | Bias Correction | Backbone |
-|-------|-------------|------------|-----------------|----------|
-| **Our ResNet50** | **19.96** | 256×256 | ✅ Advanced | ResNet50 |
-| Basic MobileNetV2 | 24.2 | 224×224 | ❌ None | MobileNetV2 |
-| Standard CNN | 28.5 | 224×224 | ❌ None | Custom |
-| VGG16 Baseline | 26.8 | 224×224 | ❌ None | VGG16 |
-### Advantages of This Implementation
-- **✅ Bias Correction**: Addresses systematic age prediction bias
-- **✅ Robust Loss**: Huber loss handles outliers and noisy labels
-- **✅ Advanced Architecture**: ResNet50 provides superior feature extraction
-- **✅ Higher Resolution**: 256×256 input captures more facial detail
-- **✅ Sample Weighting**: Balances training across age distribution
-## 🔗 Related Models & Resources
-### Hugging Face Hub
-- **Model Repository**: [Sharris/age-detection-resnet50-model](https://huggingface.co/Sharris/age-detection-resnet50-model)
-- **Live Demo**: [Age Detection Space](https://huggingface.co/spaces/Sharris/age-detection-space)
-- **Base Model**: [microsoft/resnet-50](https://huggingface.co/microsoft/resnet-50)
-### Research Papers & References
-- **UTKFace Dataset**: [Zhang et al. "Age Progression/Regression by Conditional Adversarial Autoencoder"](https://susanqq.github.io/UTKFace/)
-- **ResNet Architecture**: [He et al. "Deep Residual Learning for Image Recognition"](https://arxiv.org/abs/1512.03385)
-- **Bias in Age Estimation**: [Escalante et al. "Age and Gender Classification in Uncontrolled Environments"](https://ieeexplore.ieee.org/)
-### Alternative Approaches
-- **DEX (Deep EXpectation)**: Age estimation using expectation regression
-- **SSR-Net**: Soft stagewise regression for age estimation
-- **AgeNet**: Multi-task learning for age and gender estimation
-## 📚 Citation & License
-### How to Cite
-If you use this model in your research, please cite:
-```bibtex
-@misc{age-detection-resnet50-2025,
-  title={Age Detection with ResNet50: Bias-Corrected Facial Age Estimation},
-  author={Stealth Labs Ltd.},
-  year={2025},
-  url={https://huggingface.co/Sharris/age-detection-resnet50-model},
-  note={TensorFlow implementation with inverse frequency sample weighting}
-}
-```
-### Dataset Citation
-```bibtex
-@inproceedings{zhang2017age,
-  title={Age progression/regression by conditional adversarial autoencoder},
-  author={Zhang, Zhifei and Song, Yang and Qi, Hairong},
-  booktitle={IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
-  pages={5810--5818},
-  year={2017}
-}
-```
-### License
-- **Model**: MIT License
-- **Code**: MIT License
-- **Dataset**: UTKFace dataset license (academic/research use)
-- **Usage**: Free for academic, research, and commercial use with attribution
-## 👥 Contact & Support
-### Development Team
-**Organization**: Stealth Labs Ltd.
-**Model Maintainer**: GitHub Copilot Assistant
-**Repository**: [age_detection_regression_model](https://github.com/Stealth-Labs-LTD/age_detection_regression_model)
-### Getting Help
-- **Issues**: Report bugs and request features on GitHub Issues
-- **Discussions**: Join model discussions on Hugging Face Hub
-- **Email**: Contact through Stealth Labs Ltd. official channels
-- **Community**: Join the computer vision community discussions
-### Contributing
-We welcome contributions! Please:
-1. Fork the repository
-2. Create a feature branch
-3. Submit a pull request with clear description
-4. Include tests and documentation updates
-## 🔄 Version History & Updates
-| Version | Date | Changes | MAE |
-|---------|------|---------|-----|
-| **v2.0** | 2025-09-13 | ResNet50 + bias correction | 19.96 |
-| v1.0 | 2025-09-12 | Initial MobileNetV2 implementation | 24.2 |
-### Planned Improvements
-- [ ] Multi-task learning (age + gender + ethnicity)
-- [ ] Attention mechanisms for better feature focus
-- [ ] Uncertainty quantification for prediction confidence
-- [ ] Model quantization for mobile deployment
-- [ ] Cross-dataset evaluation and domain adaptation
----
-## 🎯 Quick Links
-| Resource | Link | Description |
-|----------|------|-------------|
-| 🤗 **Model Hub** | [Sharris/age-detection-resnet50-model](https://huggingface.co/Sharris/age-detection-resnet50-model) | Download the trained model |
-| 🚀 **Live Demo** | [Age Detection Space](https://huggingface.co/spaces/Sharris/age-detection-space) | Try the model online |
-| 📊 **Dataset** | [UTKFace](https://susanqq.github.io/UTKFace/) | Original training dataset |
-| 💻 **Code** | [GitHub Repository](https://github.com/Stealth-Labs-LTD/age_detection_regression_model) | Full source code |
-| 📖 **Documentation** | This README | Comprehensive model card |
-**Ready to get started?** 🚀 Try the [live demo](https://huggingface.co/spaces/Sharris/age-detection-space) or [download the model](https://huggingface.co/Sharris/age-detection-resnet50-model) to begin age estimation in your applications!

+---
+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
+pipeline_tag: image-classification
+base_model: tensorflow/resnet50v2
+widget:
+- src: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/image-classification-input.jpg
+  example_title: Sample Face Image
+---
+# Age Group Classification Model 🎯👥
+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**.
+## 🚀 Quick Start
+### Using Hugging Face Transformers
+```python
+from transformers import pipeline
+from PIL import Image
+# Load the classifier
+classifier = pipeline("image-classification",
+                     model="Sharris/age-group-classifier")
+# 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 Overview
+### The Problem We Solved
+Traditional age regression models suffer from **severe age bias**:
+- 70-year-old faces → Predicted as 30-year-olds ❌
+- Inconsistent predictions across age ranges
+- Poor handling of seniors and elderly individuals
+### Our Solution: Age Group Classification
+- **5 Age Groups**: More robust than exact age regression ✅
+- **Bias-Free**: 75-year-olds correctly classified as "Senior (61-80)" ✅
+- **Practical**: Returns useful age ranges for real applications ✅
+- **Reliable**: 75.5% validation accuracy with stable predictions ✅
+## 📊 Model Performance
+| Metric | Value | Description |
+|--------|-------|-------------|
+| **Validation Accuracy** | **75.5%** | 5-class classification accuracy |
+| **Training Accuracy** | **79.1%** | Training set performance |
+| **Generalization Gap** | **3.6%** | Healthy gap - no overfitting |
+## 🏷️ Age Groups
+| Group ID | Age Range | Label | Description |
+|----------|-----------|-------|-------------|
+| 0 | 0-20 years | Youth | Children, teenagers |
+| 1 | 21-40 years | Young Adult | College age to early career |
+| 2 | 41-60 years | Middle Age | Established adults |
+| 3 | 61-80 years | Senior | Retirement age |
+| 4 | 81-100 years | Elderly | Advanced age |
+## 🤖 Live Demo
+Try the model instantly: **[Age Group Classifier Demo](https://huggingface.co/spaces/Sharris/age-group-classifier-demo)**
+## 📜 License & Ethics
+- **License**: MIT License
+- **Bias Mitigation**: Specifically designed to reduce age prediction bias
+- **Privacy**: Consider consent when processing facial images
+## 📚 Citation
+```bibtex
+@misc{age-group-classifier-2025,
+  title={Age Group Classification: Solving Age Prediction Bias in Facial Analysis},
+  author={Sharris},
+  year={2025},
+  publisher={Hugging Face},
+  url={https://huggingface.co/Sharris/age-group-classifier}
+}
+```