feature_engineering.py

"""
Feature Engineering Module
--------------------------
Toutes les transformations de features pour la détection de fraude

Ce module contient les fonctions pour :
1. Calculer la distance GPS entre client et marchand
2. Extraire les features temporelles (heure, jour, weekend, etc.)
3. Calculer l'âge du porteur de carte
4. Créer toutes les features nécessaires pour le modèle ML

Author: Terorra
Date: January 2026
"""

from datetime import datetime, date
from math import radians, sin, cos, sqrt, atan2
import pandas as pd


# =====================================================================
# FONCTION 1 : CALCUL DE DISTANCE GPS
# =====================================================================

def haversine_distance(lat1, lon1, lat2, lon2):
    """
    Calcule la distance entre 2 points GPS avec la formule Haversine
    
    La formule Haversine permet de calculer la distance entre deux points
    sur une sphère (la Terre) à partir de leurs coordonnées GPS.
    
    Args:
        lat1 (float): Latitude du point 1 (client)
        lon1 (float): Longitude du point 1 (client)
        lat2 (float): Latitude du point 2 (marchand)
        lon2 (float): Longitude du point 2 (marchand)
    
    Returns:
        float: Distance en kilomètres (arrondie à 2 décimales)
        None: Si une coordonnée est manquante
    
    Example:
        >>> haversine_distance(48.8566, 2.3522, 51.5074, -0.1278)
        344.45  # Distance Paris-Londres en km
    """
    # Vérifier si des valeurs sont manquantes
    if any(pd.isna([lat1, lon1, lat2, lon2])):
        return None
    
    try:
        # Rayon de la Terre en kilomètres
        R = 6371
        
        # Convertir les degrés en radians (nécessaire pour les calculs trigonométriques)
        lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
        
        # Différences de latitude et longitude
        dlat = lat2 - lat1
        dlon = lon2 - lon1
        
        # Formule Haversine
        # a = sin²(Δlat/2) + cos(lat1) * cos(lat2) * sin²(Δlon/2)
        a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
        
        # c = 2 * atan2(√a, √(1-a))
        c = 2 * atan2(sqrt(a), sqrt(1-a))
        
        # Distance = R * c
        distance = R * c
        
        # Arrondir à 2 décimales
        return round(distance, 2)
        
    except Exception as e:
        print(f"⚠️ Erreur calcul distance: {e}")
        return None


# =====================================================================
# FONCTION 2 : CALCUL DE L'ÂGE
# =====================================================================

def calculate_age(born):
    """
    Calcule l'âge à partir de la date de naissance
    
    Cette fonction calcule l'âge en années complètes, en tenant compte
    du fait que l'anniversaire peut ne pas encore être passé cette année.
    
    Args:
        born (str): Date de naissance au format 'YYYY-MM-DD'
    
    Returns:
        int: Âge en années
        None: Si la date est invalide ou manquante
    
    Example:
        >>> calculate_age('1990-01-15')
        36  # Si on est en 2026
    """
    # Vérifier si la valeur est manquante
    if pd.isna(born) or born is None or born == '':
        return None
    
    try:
        # Convertir la string en date
        born_date = datetime.strptime(str(born), '%Y-%m-%d').date()
        
        # Date du jour
        today = date.today()
        
        # Calcul de l'âge
        # On soustrait 1 si l'anniversaire n'est pas encore passé cette année
        age = today.year - born_date.year - (
            (today.month, today.day) < (born_date.month, born_date.day)
        )
        
        return age
        
    except Exception as e:
        print(f"⚠️ Erreur calcul âge pour {born}: {e}")
        return None


# =====================================================================
# FONCTION 3 : FEATURES TEMPORELLES
# =====================================================================

def extract_time_features(transaction_time):
    """
    Extrait toutes les features temporelles d'une transaction
    
    À partir de l'heure de transaction, cette fonction crée :
    - L'heure (0-23)
    - Le jour de la semaine (0=lundi, 6=dimanche)
    - Si c'est le weekend (samedi ou dimanche)
    - Si c'est la nuit (22h-6h)
    - Si c'est le matin (6h-12h)
    - Si c'est l'après-midi (12h-18h)
    - Si c'est le soir (18h-22h)
    - Si c'est pendant les heures de bureau (8h-17h)
    - L'année, le mois, le jour
    
    Args:
        transaction_time (str or datetime): Heure de la transaction
    
    Returns:
        dict: Dictionnaire avec toutes les features temporelles
        None: Si la date est invalide
    
    Example:
        >>> extract_time_features('2026-01-29 14:30:00')
        {
            'hour': 14,
            'day_of_week': 2,  # Mercredi
            'is_weekend': 0,
            'is_night': 0,
            'is_morning': 0,
            'is_afternoon': 1,
            'is_evening': 0,
            'is_business_hour': 1,
            'year': 2026,
            'month': 1,
            'day': 29
        }
    """
    # Vérifier si la valeur est manquante
    if pd.isna(transaction_time) or transaction_time is None:
        return None
    
    try:
        # Convertir en datetime si nécessaire
        if isinstance(transaction_time, str):
            dt = pd.to_datetime(transaction_time)
        else:
            dt = transaction_time
        
        # Extraire l'heure (0-23)
        hour = dt.hour
        
        # Extraire le jour de la semaine (0=lundi, 6=dimanche)
        day_of_week = dt.dayofweek
        
        # Créer le dictionnaire de features
        features = {
            # Heure brute
            'hour': hour,
            'day_of_week': day_of_week,
            
            # Périodes de la journée (binaire : 0 ou 1)
            'is_night': 1 if 22 <= hour or hour < 6 else 0,        # 22h-6h
            'is_morning': 1 if 6 <= hour < 12 else 0,              # 6h-12h
            'is_afternoon': 1 if 12 <= hour < 18 else 0,           # 12h-18h
            'is_evening': 1 if 18 <= hour < 22 else 0,             # 18h-22h
            'is_business_hour': 1 if 8 <= hour < 17 else 0,        # 8h-17h
            
            # Weekend (samedi=5, dimanche=6)
            'is_we': 1 if day_of_week in [5, 6] else 0,
            
            # Composantes de la date
            'year': dt.year,
            'month': dt.month,
            'day': dt.day
        }
        
        return features
        
    except Exception as e:
        print(f"⚠️ Erreur extraction features temps pour {transaction_time}: {e}")
        return None


# =====================================================================
# FONCTION 4 : FEATURE ENGINEERING COMPLET
# =====================================================================

def engineer_features(transaction_data):
    """
    Applique TOUTES les transformations de features sur une transaction
    
    Cette fonction est la fonction PRINCIPALE qui :
    1. Prend les données brutes d'une transaction
    2. Calcule la distance GPS client-marchand
    3. Extrait les features temporelles
    4. Calcule l'âge si la date de naissance est fournie
    5. Retourne un dictionnaire avec TOUTES les features
    
    Args:
        transaction_data (dict): Dictionnaire avec les données brutes
            Clés requises:
            - lat, long: Coordonnées client
            - merch_lat, merch_long: Coordonnées marchand
            - transaction_time: Heure de transaction
            Clés optionnelles:
            - dob: Date de naissance (pour calculer l'âge)
            - amt, cc_num, etc.: Autres features
    
    Returns:
        dict: Dictionnaire avec toutes les features (brutes + engineered)
    
    Example:
        >>> data = {
        ...     'amt': 150.75,
        ...     'lat': 40.7128,
        ...     'long': -74.0060,
        ...     'merch_lat': 40.7589,
        ...     'merch_long': -73.9851,
        ...     'transaction_time': '2026-01-29 14:30:00',
        ...     'city_pop': 8000000,
        ...     'dob': '1990-01-15'
        ... }
        >>> result = engineer_features(data)
        >>> print(result['distance_km'])
        5.87  # Distance en km
        >>> print(result['hour'])
        14
        >>> print(result['age'])
        36
    """
    # Copier les données pour ne pas modifier l'original
    features = transaction_data.copy()
    
    # ========================================
    # 1. CALCUL DE LA DISTANCE GPS
    # ========================================
    
    # Vérifier que les coordonnées sont présentes
    if all(key in features for key in ['lat', 'long', 'merch_lat', 'merch_long']):
        distance = haversine_distance(
            features['lat'],
            features['long'],
            features['merch_lat'],
            features['merch_long']
        )
        features['distance_km'] = distance
        print(f"  ✅ Distance calculée: {distance} km")
    else:
        features['distance_km'] = None
        print(f"  ⚠️ Coordonnées GPS manquantes, distance non calculée")
    
    # ========================================
    # 2. EXTRACTION DES FEATURES TEMPORELLES
    # ========================================
    
    # Vérifier que l'heure de transaction est présente
    if 'transaction_time' in features:
        time_features = extract_time_features(features['transaction_time'])
        
        if time_features:
            # Ajouter toutes les features temporelles au dictionnaire
            features.update(time_features)
            print(f"  ✅ Features temporelles extraites (heure: {time_features['hour']})")
        else:
            print(f"  ⚠️ Impossible d'extraire les features temporelles")
    else:
        print(f"  ⚠️ Heure de transaction manquante")
    
    # ========================================
    # 3. CALCUL DE L'ÂGE (si date de naissance fournie)
    # ========================================
    
    if 'dob' in features:
        age = calculate_age(features['dob'])
        features['age'] = age
        if age:
            print(f"  ✅ Âge calculé: {age} ans")
        else:
            print(f"  ⚠️ Impossible de calculer l'âge")
    else:
        features['age'] = None
        print(f"  ⚠️ Date de naissance non fournie")
    
    # ========================================
    # RETOUR
    # ========================================
    
    return features


# =====================================================================
# FONCTION 5 : LISTE DES FEATURES POUR LE MODÈLE
# =====================================================================

def get_model_features():
    """
    Retourne la liste EXACTE des features attendues par le modèle ML
    
    Cette fonction définit l'ordre EXACT des colonnes que le modèle attend.
    IMPORTANT: L'ordre DOIT être le même que lors de l'entraînement !
    
    Returns:
        list: Liste des noms de features dans le bon ordre
    
    Categories:
        - Numerical: 17 features numériques
        - Categorical: 4 features catégorielles
    """
    # Features NUMÉRIQUES (17 features)
    numerical_features = [
        'cc_num',           # Numéro de carte (hashé)
        'amt',              # Montant de la transaction
        'zip',              # Code postal
        'city_pop',         # Population de la ville
        'distance_km',      # Distance client-marchand (ENGINEERED)
        'age',              # Âge du porteur (ENGINEERED)
        'hour',             # Heure 0-23 (ENGINEERED)
        'is_night',         # 1 si nuit (ENGINEERED)
        'is_morning',       # 1 si matin (ENGINEERED)
        'is_afternoon',     # 1 si après-midi (ENGINEERED)
        'is_evening',       # 1 si soir (ENGINEERED)
        'is_business_hour', # 1 si heures de bureau (ENGINEERED)
        'year',             # Année (ENGINEERED)
        'month',            # Mois (ENGINEERED)
        'day',              # Jour (ENGINEERED)
        'dayofweek',        # Jour de la semaine (ENGINEERED) - Renommé de 'day_of_week'
        'is_we'             # 1 si weekend (ENGINEERED)
    ]
    
    # Features CATÉGORIELLES (4 features)
    categorical_features = [
        'merchant',         # Nom du marchand
        'category',         # Catégorie de la transaction
        'gender',           # Genre du client
        'state'             # État (US)
    ]
    
    # TOUTES les features dans l'ORDRE
    all_features = numerical_features + categorical_features
    
    return all_features


def prepare_for_model(features_dict):
    """
    Prépare les features dans le bon format pour le modèle
    
    Cette fonction :
    1. Prend le dictionnaire de features
    2. Sélectionne UNIQUEMENT les features nécessaires
    3. Les arrange dans le BON ORDRE
    4. Convertit en DataFrame
    5. Renomme 'day_of_week' en 'dayofweek' (compatibilité modèle)
    
    Args:
        features_dict (dict): Dictionnaire avec toutes les features
    
    Returns:
        pd.DataFrame: DataFrame avec les features dans le bon ordre
        None: Si des features manquent
    
    Example:
        >>> features = engineer_features(transaction_data)
        >>> df_ready = prepare_for_model(features)
        >>> # df_ready est prêt pour model.predict()
    """
    # Renommer 'day_of_week' en 'dayofweek' si présent
    # (Le modèle a été entraîné avec 'dayofweek')
    if 'day_of_week' in features_dict and 'dayofweek' not in features_dict:
        features_dict['dayofweek'] = features_dict['day_of_week']
    
    # Obtenir la liste des features attendues
    expected_features = get_model_features()
    
    # Vérifier que toutes les features sont présentes
    missing_features = [f for f in expected_features if f not in features_dict]
    
    if missing_features:
        print(f"❌ Features manquantes: {missing_features}")
        return None
    
    # Sélectionner uniquement les features nécessaires DANS LE BON ORDRE
    selected_data = {feature: features_dict[feature] for feature in expected_features}
    
    # Convertir en DataFrame (le modèle attend un DataFrame)
    df = pd.DataFrame([selected_data])
    
    print(f"✅ Features préparées: {df.shape[1]} colonnes")
    
    return df


# =====================================================================
# MÉTADONNÉES DU MODULE
# =====================================================================

__version__ = "1.0.0"
__author__ = "Terorra"

# Liste des fonctions exportées
__all__ = [
    'haversine_distance',
    'calculate_age',
    'extract_time_features',
    'engineer_features',
    'get_model_features',
    'prepare_for_model'
]


# =====================================================================
# TEST DU MODULE (si exécuté directement)
# =====================================================================

if __name__ == "__main__":
    print("=" * 70)
    print("🧪 Test du module Feature Engineering")
    print("=" * 70)
    
    # Données de test
    test_transaction = {
        'cc_num': 374125201044065,
        'amt': 150.75,
        'lat': 40.7128,
        'long': -74.0060,
        'city_pop': 8000000,
        'merch_lat': 40.7589,
        'merch_long': -73.9851,
        'transaction_time': '2026-01-29 14:30:00',
        'dob': '1990-01-15',
        'merchant': 'Amazon',
        'category': 'shopping_net',
        'gender': 'M',
        'state': 'NY',
        'zip': 10001
    }
    
    print("\n📊 Données de test:")
    for key, value in test_transaction.items():
        print(f"  {key}: {value}")
    
    print("\n🔧 Application du feature engineering...")
    engineered = engineer_features(test_transaction)
    
    print("\n📊 Features créées:")
    for key in ['distance_km', 'hour', 'is_afternoon', 'age']:
        if key in engineered:
            print(f"  {key}: {engineered[key]}")
    
    print("\n📦 Préparation pour le modèle...")
    df_ready = prepare_for_model(engineered)
    
    if df_ready is not None:
        print(f"✅ Prêt pour prédiction: {df_ready.shape}")
        print(f"   Colonnes: {list(df_ready.columns)}")
    
    print("\n" + "=" * 70)