Sharris/age_detection_regression

UTKFace Age Regression — Model Card

This repository contains code to train a TensorFlow / Keras regression model that estimates a person's age from a face image using the UTKFace dataset. The model uses a MobileNetV2 backbone and a small regression head on top.

Summary

• Model type: Image regression (single-output continuous)
• Backbone: MobileNetV2 (ImageNet pre-trained)
• Task: Age estimation (years)
• Dataset: UTKFace (public dataset; filenames encode age)
• Reported metric: Mean Absolute Error (MAE) — see Evaluation section for how to compute and report MAE for your runs

Model details

• Input: RGB face image (recommended size: 224×224)
• Output: Single scalar value — predicted age in years
• Preprocessing: MobileNetV2 preprocessing (scales inputs to [-1, 1])
• Loss: Mean Squared Error (MSE) used during training
• Metric for reporting: Mean Absolute Error (MAE)

Intended uses

• Research and educational purposes for learning about image regression and age estimation
• Prototyping demo applications that predict approximate age ranges from face crops

Out-of-scope / Limitations

• This model provides an estimate of age; it's not a substitute for official identification
• Models trained on UTKFace carry dataset biases (race, gender, age distribution). They may underperform on underrepresented groups.
• Do not use this model for high-stakes decision making (employment, legal, medical, etc.)

Dataset

UTKFace

• Source: https://susanqq.github.io/UTKFace/
• Format: Filenames encode metadata as <age>_<gender>_<race>_<date&time>.jpg.
• Usage: The training scripts in this repo extract the age from the filename (the integer before the first underscore).
• Note: Respect the dataset's license and authors when redistributing or publishing results.

Training details

• Framework: TensorFlow / Keras
• Backbone: MobileNetV2 pretrained on ImageNet
• Head: GlobalAveragePooling2D -> Dense(128, relu) -> Dense(1, linear)
• Recommended input size: 224×224 (configurable via command-line args in train.py)
• Batch size: configurable (default set in train.py)
• Optimizer: Adam (default), learning rate and scheduler configurable in train.py
• Loss: Mean Squared Error (MSE)
• Metric: Mean Absolute Error (MAE) reported on validation/test sets
• Augmentations: Basic augmentations recommended (flip, random crop/brightness) for better robustness

Reproducibility / Example training command

1. Prepare UTKFace dataset
   • Download and extract UTKFace images into data/UTKFace/ or pass --dataset_dir to the training script.
2. Install dependencies
   • python -m pip install -r requirements.txt
3. Train
   • python train.py --dataset_dir data/UTKFace --epochs 30 --batch_size 32 --img_size 224 --output_dir saved_model

The train.py script builds a tf.data pipeline, extracts ages from filenames, constructs a MobileNetV2-based model, and saves the trained model to the --output_dir.

Evaluation and metrics (MAE)

Mean Absolute Error (MAE) gives an intuitive measure of average error in predicted age (in years):

MAE = mean(|y_true - y_pred|)

Compute MAE in Python (example):

import numpy as np
mae = np.mean(np.abs(y_true - y_pred))

Example: the training script prints per-epoch validation MAE. To reproduce test MAE after training, run the provided evaluation routine or:

from tensorflow import keras
import numpy as np
model = keras.models.load_model('saved_model')
# prepare test_images, test_labels arrays
preds = model.predict(test_images).squeeze()
mae = float(np.mean(np.abs(test_labels - preds)))
print('Test MAE (years):', mae)

Note: Exact MAE depends on preprocessing, train/validation split, augmentations, and hyperparameters. Report MAE alongside the exact training configuration for reproducibility.

Usage — Quick examples

Python (local SavedModel)

import tensorflow as tf
import numpy as np
from PIL import Image
from tensorflow.keras.applications.mobilenet_v2 import preprocess_input

model = tf.keras.models.load_model('saved_model')  # path to a SavedModel directory
img = Image.open('path/to/face.jpg').convert('RGB').resize((224, 224))
arr = np.array(img, dtype=np.float32)
arr = preprocess_input(arr)
pred = model.predict(np.expand_dims(arr, 0))[0, 0]
print('Predicted age (years):', float(pred))

Command-line (using predict.py)

python predict.py --model_dir saved_model --image path/to/face.jpg

Loading from Hugging Face Hub

If you upload your saved model to the Hugging Face Hub, Consumers can download it using the huggingface_hub package. For example, in a Space, set the environment variable HF_MODEL_ID to the model repository (e.g. username/my-age-model) and the Gradio app supplied in this repo will attempt to download and use it.

Gradio demo / Hugging Face Space

A simple Gradio app is provided in app.py that:

• accepts an input face image
• preprocesses it (224×224 + MobileNetV2 preprocess)
• returns the predicted age (years) and the model's raw output

How to host as a Space

1. Create a new Space on Hugging Face and select "Gradio" as the SDK.
2. Push this repository to the Space (include app.py, your saved_model/ directory or set HF_MODEL_ID to your model on the Hub).
3. Make sure requirements.txt includes gradio and huggingface_hub (the repository requirements.txt in this project may be extended with these packages for the Space).

Files in this repository

• train.py — training script
• predict.py — single-image prediction helper
• convert_model.py — conversion helpers
• inference_log.py, inference_log.txt, load_predict_log.txt — logging and CLI helpers for inference (dev)
• app.py — (added) Gradio demo app for live predictions
• requirements.txt — Python dependencies (extend for Spaces with gradio and huggingface_hub)

Security, biases and ethical considerations

• Age estimation models can reflect and amplify biases in the training data (race and gender imbalance, age distribution). Evaluate fairness across demographic slices before using widely.
• Avoid using the model in high-risk contexts where inaccurate age estimates could cause harm.

How to cite / license

• UTKFace authors and dataset should be cited if you publish results.
• This repository is provided under the MIT license (see LICENSE file if present).

Contact and credits

Maintainer: Stealth Labs Ltd.

Acknowledgements

Thanks to the UTKFace dataset authors for the publicly available images used in training and experimentation.