dataset_analysis package

Package dataset_analysis

Contient les modules de préparation et d’études des jeux de données.

Préparation des jeux de données Recipes / Interactions pour les analyses.

Ce module regroupe la logique appliquée dans les notebooks d’exploration afin de produire un jeu de données unique, prêt pour les analyses univariées et multivariées. Il expose des fonctions réutilisables et un point d’entrée exécutable pour générer les fichiers nettoyés sur disque.

dataset_analysis.dataset_preprocessing.build_analysis_dataset(save: bool = True) → tuple[DataFrame, DataFrame, DataFrame]

Construit les différents DataFrames nécessaires à l’analyse.

Paramètres:

save (bool, optional) – Indique s’il faut enregistrer les fichiers générés sur disque, defaults to True.

Renvoie:

Tuple (recipes_clean, interactions_clean, df_analysis) contenant les jeux de données générés.

Type renvoyé:

tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]

dataset_analysis.dataset_preprocessing.calculate_avg_words_per_step(steps_value: object) → float

Calcule le nombre moyen de mots par étape pour une recette.

Paramètres:

steps_value (object) – Valeur brute de la colonne steps.

Renvoie:

Nombre moyen de mots par étape (0 si aucune étape valide).

Type renvoyé:

float

dataset_analysis.dataset_preprocessing.categorize_complexity(n_steps: int) → str

Classe la complexité d’une recette selon le nombre d’étapes.

Paramètres:

n_steps (int) – Nombre d’étapes décrites dans la recette.

Renvoie:

Libellé de complexité (« Simple », « Modéré », « Complexe », « Très complexe »).

Type renvoyé:

str

dataset_analysis.dataset_preprocessing.categorize_n_ingredients(n_ingredients: int) → str

Catégorise la recette selon le nombre d’ingrédients.

Paramètres:

n_ingredients (int) – Nombre d’ingrédients distincts.

Renvoie:

Libellé de catégorie (« Peu d’ingrédients », « Ingrédients modérés », « Beaucoup d’ingrédients »).

Type renvoyé:

str

dataset_analysis.dataset_preprocessing.categorize_prep_time(minutes: float) → str

Catégorise un temps de préparation en classes qualitatives.

Paramètres:

minutes (float) – Durée totale de la recette en minutes.

Renvoie:

Libellé de catégorie (« Rapide », « Moyenne » ou « Longue »).

Type renvoyé:

str

dataset_analysis.dataset_preprocessing.categorize_step_length(avg_words: float) → str

Catégorise la longueur moyenne des étapes d’une recette.

Paramètres:

avg_words (float) – Nombre moyen de mots par étape.

Renvoie:

Catégorie de longueur (« Étapes courtes », « Étapes moyennes », « Étapes longues »).

Type renvoyé:

str

dataset_analysis.dataset_preprocessing.enrich_analysis_dataset(recipes: DataFrame, interactions: DataFrame) → DataFrame

Fusionne les recettes nettoyées avec les métriques d’interactions.

Paramètres:

• recipes (pd.DataFrame) – Recettes prétraitées.

• interactions (pd.DataFrame) – Interactions nettoyées prêtes pour l’agrégation.

Renvoie:

DataFrame consolidé avec variables d’effort, d’engagement et dérivées logarithmiques.

Type renvoyé:

pd.DataFrame

dataset_analysis.dataset_preprocessing.load_raw_datasets() → tuple[DataFrame, DataFrame]

Charge les fichiers RAW_recipes.csv et RAW_interactions.csv.

Renvoie:

Tuple contenant respectivement les DataFrames des recettes et des interactions.

Type renvoyé:

tuple[pd.DataFrame, pd.DataFrame]

dataset_analysis.dataset_preprocessing.prepare_interactions(interactions: DataFrame) → DataFrame

Nettoie les interactions utilisateur-recette.

Paramètres:

interactions (pd.DataFrame) – DataFrame brut RAW_interactions.csv.

Renvoie:

DataFrame nettoyé avec conversions de dates, suppression des notes nulles et longueurs de review.

Type renvoyé:

pd.DataFrame

dataset_analysis.dataset_preprocessing.prepare_recipes(recipes: DataFrame) → DataFrame

Nettoie et enrichit le jeu de données des recettes Kaggle.

Paramètres:

recipes (pd.DataFrame) – DataFrame brut provenant du fichier RAW_recipes.csv.

Renvoie:

DataFrame nettoyé avec colonnes enrichies (scores, catégories, transformations).

Type renvoyé:

pd.DataFrame

dataset_analysis.dataset_preprocessing.winsorize(series: Series, lower_pct: float = 0.05, upper_pct: float = 0.99) → Series

Écrête les valeurs extrêmes d’une série selon des quantiles donnés.

Paramètres:

• series (pd.Series) – Série numérique à borner.

• lower_pct (float, optional) – Quantile inférieur utilisé comme borne minimale, defaults to 0.05.

• upper_pct (float, optional) – Quantile supérieur utilisé comme borne maximale, defaults to 0.99.

Renvoie:

Série winsorisée conservant l’index d’origine.

Type renvoyé:

pd.Series

Bibliothèque d’analyse statistique pour l’étude de la relation effort culinaire ↔ popularité.

Fournit des fonctions pures et réutilisables pour l’analyse exploratoire et inférentielle du dataset de recettes, conçues pour l’intégration dans des pipelines, applications web ou scripts d’automatisation.

Fonctionnalités

• Chargement et prétraitement avec filtrage configurable

• Analyses de corrélation (Pearson, Spearman) avec transformations automatiques

• Agrégations par quantiles et tests de comparaison de groupes (ANOVA, Kruskal-Wallis)

• Régression non-paramétrique (LOWESS) pour relations non-linéaires

• Modélisation prédictive (linéaire, forêts aléatoires, OLS) avec métriques d’évaluation

Architecture

Fonctions sans effets de bord : pas de modification in-place, pas d’affichage graphique, retours sérialisables (DataFrames, dictionnaires, dataclasses).

Usage

>>> from dataset_analysis.utils import load_analysis_dataset, compute_correlations
>>> df = load_analysis_dataset()
>>> result = compute_correlations(df, method='spearman')
>>> print(result.coefficients)

Notes

Les transformations (log, winsorisation, standardisation) sont appliquées automatiquement selon les méthodes statistiques, conformément aux bonnes pratiques d’analyse exploratoire.

class dataset_analysis.utils.CorrelationResult(coefficients: DataFrame, p_values: DataFrame, n_obs: DataFrame)

Bases : object

Encapsulation des résultats d’analyse de corrélation.

Variables:

• coefficients (pd.DataFrame) – Matrice des coefficients de corrélation (ρ ou r selon la méthode).

• p_values (pd.DataFrame) – Matrice des p-values associées (test bilatéral H₀: ρ = 0).

• n_obs (pd.DataFrame) – Matrice des effectifs (paires complètes après suppression des valeurs manquantes).

__init__(coefficients: DataFrame, p_values: DataFrame, n_obs: DataFrame) → None

coefficients: DataFrame

n_obs: DataFrame

p_values: DataFrame

to_dict() → dict[str, Any]

Sérialise les matrices en dictionnaires imbriqués.

Renvoie:

Structure compatible JSON pour export ou usage API.

Type renvoyé:

dict[str, Any]

dataset_analysis.utils.add_feature_columns(df: DataFrame, *, interaction: bool = True, standardize: bool = True, columns_to_standardize: Sequence[str] | None = None) → tuple[DataFrame, dict[str, Any]]

Enrichit le dataset avec des variables dérivées pour la modélisation.

Cette fonction génère : - Termes d’interaction (produits de variables) - Variables standardisées (z-scores) pour la régression linéaire

Paramètres:

• df (pd.DataFrame) – Dataset source (non modifié, une copie est créée).

• interaction (bool) – Indique s’il faut créer la variable steps_x_ingredients.

• standardize (bool) – Indique s’il faut générer les versions centrées-réduites (suffixe _std).

• columns_to_standardize (Sequence[str] | None) – Liste personnalisée des colonnes à standardiser. Par défaut ['log_minutes', 'n_steps', 'n_ingredients', 'avg_words_per_step', 'age_months', 'effort_score', 'steps_x_ingredients'].

Renvoie:

Tuple composé du DataFrame enrichi et des métadonnées de standardisation (moyenne, écart-type par variable).

Type renvoyé:

tuple[pd.DataFrame, dict[str, Any]]

Note

La standardisation utilise l’écart-type de population (ddof=0) pour rester cohérente avec les pratiques courantes en machine learning. Les métadonnées permettent de reproduire la transformation sur de nouvelles données.

dataset_analysis.utils.compute_correlations(df: DataFrame, *, effort_vars: Sequence[str] | None = None, popularity_vars: Sequence[str] | None = None, method: Literal['spearman', 'pearson'] = 'spearman', pearson_effort_map: Mapping[str, str] | None = None, pearson_popularity_map: Mapping[str, str] | None = None) → CorrelationResult

Calcule les corrélations bivariées entre variables d’effort et de popularité.

Cette fonction génère trois matrices : - Coefficients de corrélation (ρ pour Spearman, r pour Pearson) - P-values associées (test bilatéral) - Effectifs (nombre de paires complètes)

Paramètres:

• df (pd.DataFrame) – Dataset contenant les variables d’intérêt.

• effort_vars (Sequence[str] | None) – Variables d’effort culinaire. Par défaut ['log_minutes', 'n_steps', 'n_ingredients', 'effort_score'].

• popularity_vars (Sequence[str] | None) – Variables de popularité. Par défaut ['bayes_mean', 'wilson_lb', 'interactions_per_month'].

• method (Literal["spearman", "pearson"]) – Méthode de corrélation ('spearman' robuste aux distributions non-normales ou 'pearson' pour corrélations linéaires).

• pearson_effort_map (Mapping[str, str] | None) – Correspondance entre variables d’effort et leurs versions transformées.

• pearson_popularity_map (Mapping[str, str] | None) – Correspondance entre variables de popularité et leurs versions transformées.

Renvoie:

Dataclass contenant les trois matrices (coefficients, p_values, n_obs).

Type renvoyé:

CorrelationResult

Note

Pour la corrélation de Pearson, les transformations logarithmiques et la winsorisation sont appliquées automatiquement via les mappings pour satisfaire les hypothèses de normalité bivariée. Pour Spearman, les variables brutes sont utilisées.

dataset_analysis.utils.load_analysis_dataset(path: str | Path | None = None, *, columns: Sequence[str] | None = None, drop_missing_popularity: bool = True, popularity_cols: Sequence[str] | None = None) → DataFrame

Charge le dataset d’analyse avec filtrage optionnel des observations incomplètes.

Paramètres:

• path (str | Path | None) – Chemin vers le fichier CSV ou son répertoire parent.

• columns (Sequence[str] | None) – Sous-ensemble de colonnes à charger. Lorsque None, toutes les colonnes sont conservées.

• drop_missing_popularity (bool) – Indique s’il faut exclure les recettes sans métriques de popularité valides.

• popularity_cols (Sequence[str] | None) – Colonnes utilisées pour identifier les valeurs manquantes de popularité. Par défaut ['bayes_mean', 'rating_gap', 'bayes_gap'].

Renvoie:

Dataset nettoyé avec index réinitialisé.

Type renvoyé:

pd.DataFrame

Note

Le filtrage sur la popularité permet d’exclure les recettes sans interactions, évitant ainsi les biais dans les analyses de corrélation et de régression.

dataset_analysis.utils.prepare_lowess_series(df: DataFrame, *, x_col: str, y_col: str, frac: float = 0.3, sample_size: int | None = 20000, random_state: int = 42) → dict[str, Any]

Calcule une régression LOWESS (Locally Weighted Scatterplot Smoothing).

La régression LOWESS est une méthode non-paramétrique qui ajuste localement des polynômes pondérés pour capturer des relations non-linéaires sans spécifier de forme fonctionnelle a priori.

Paramètres:

• df (pd.DataFrame) – Dataset contenant les variables d’entrée.

• x_col (str) – Nom de la variable prédictrice (axe X).

• y_col (str) – Nom de la variable réponse (axe Y).

• frac (float) – Fraction de points pour chaque ajustement local (bandwidth). Valeur faible → courbe flexible.

• sample_size (int | None) – Taille d’échantillon maximale (LOWESS est coûteux). None pour utiliser toutes les lignes.

• random_state (int) – Graine aléatoire utilisée pour l’échantillonnage.

Renvoie:

Dictionnaire contenant les points bruts, la courbe lissée, le paramètre de lissage et le volume d’échantillon.

Type renvoyé:

dict[str, Any]

Lève:

ValueError – Si aucun point valide n’est disponible après nettoyage.

Note

Cette fonction ne génère pas de graphique mais fournit les données prêtes à tracer.

dataset_analysis.utils.resolve_dataset_path(path: str | Path | None = None) → Path

Résout le chemin absolu vers le fichier d’analyse.

Paramètres:

path (str | Path | None) – Chemin personnalisé vers le fichier CSV ou son répertoire parent. Si None, utilise le chemin par défaut du projet.

Renvoie:

Chemin absolu résolu vers analysis_dataset.csv.

Type renvoyé:

Path

Note

Si un répertoire est fourni, le fichier analysis_dataset.csv est automatiquement ajouté au chemin.

dataset_analysis.utils.run_group_tests(df: DataFrame, *, group_col: str, metrics: Sequence[str], methods: Sequence[Literal['anova', 'kruskal']] = ('anova', 'kruskal')) → DataFrame

Effectue des tests de comparaison de moyennes entre groupes.

Implémente l’ANOVA paramétrique (hypothèse de normalité) et le test de Kruskal-Wallis non-paramétrique pour évaluer l’homogénéité des distributions de variables continues à travers des groupes catégoriels.

Paramètres:

• df (pd.DataFrame) – Dataset d’analyse.

• group_col (str) – Variable catégorielle définissant les groupes (ex. 'effort_category').

• metrics (Sequence[str]) – Variables continues à tester.

• methods (Sequence[Literal["anova", "kruskal"]]) – Tests statistiques à appliquer (ANOVA, Kruskal).

Renvoie:

Tableau de résultats (metric, method, statistic, p_value, n_groups, n_total, group_sizes).

Type renvoyé:

pd.DataFrame

Lève:

ValueError – Si moins de deux groupes restent après le nettoyage.

Note

• ANOVA : test F de Fisher-Snedecor (hypothèses de normalité et homoscédasticité).

• Kruskal-Wallis : test H non paramétrique (basé sur les rangs, robuste).

dataset_analysis.utils.run_models(df: DataFrame, *, features: Sequence[str] | None = None, targets: Sequence[str] | None = None, test_size: float = 0.2, random_state: int = 42, rf_params: Mapping[str, Any] | None = None) → dict[str, Any]

Entraîne et évalue plusieurs modèles de régression pour prédire la popularité.

Cette fonction implémente un pipeline complet d’entraînement avec validation hold-out, incluant trois approches : - Régression linéaire (scikit-learn) : modèle paramétrique simple - Forêt aléatoire (scikit-learn) : modèle non-linéaire avec interactions - Régression OLS (statsmodels) : inférence statistique avec p-values

Paramètres:

• df (pd.DataFrame) – Dataset contenant les prédicteurs et les variables cibles.

• features (Sequence[str] | None) – Variables prédictives. Par défaut ['log_minutes_std', 'n_steps_std', 'n_ingredients_std', 'steps_x_ingredients_std', 'age_months_std'].

• targets (Sequence[str] | None) – Variables à prédire. Par défaut ['bayes_mean', 'wilson_lb', 'log1p_interactions_per_month_w'].

• test_size (float) – Fraction du dataset réservée à la validation (hold-out).

• random_state (int) – Graine aléatoire pour la reproductibilité.

• rf_params (Mapping[str, Any] | None) – Hyperparamètres passés à RandomForestRegressor.

Renvoie:

Structure contenant la configuration utilisée et les métriques des modèles entraînés.

Type renvoyé:

dict[str, Any]

Note

• Les prédicteurs doivent être pré-standardisés (suffixe _std).

• La régression linéaire applique une seconde standardisation via StandardScaler.

• OLS est ajusté sur l’ensemble complet pour l’inférence statistique.

• Les métriques reportées proviennent de l’ensemble de test.

dataset_analysis.utils.summarize_by_effort_quantiles(df: DataFrame, *, score_col: str = 'effort_score', targets: Sequence[str] | None = None, quantiles: int = 4, labels: Sequence[str] | None = None) → dict[str, Any]

Agrège les métriques de popularité par strates d’effort culinaire.

Effectue une stratification du score d’effort en quantiles et calcule les statistiques descriptives des variables de popularité pour chaque strate.

Paramètres:

• df (pd.DataFrame) – Dataset d’analyse.

• score_col (str) – Variable continue utilisée pour la stratification.

• targets (Sequence[str] | None) – Variables de popularité à agréger. Par défaut ['bayes_mean', 'wilson_lb', 'log1p_interactions_per_month_w'].

• quantiles (int) – Nombre de quantiles (4 = quartiles, 5 = quintiles, etc.).

• labels (Sequence[str] | None) – Étiquettes personnalisées pour les strates.

Renvoie:

Dictionnaire contenant les strates calculées, les agrégations et les bornes de quantiles.

Type renvoyé:

dict[str, Any]

Note

Cette fonction est utile pour détecter des effets de seuil ou des relations non linéaires entre effort et popularité via une analyse de variance inter-strates.