Annexe B — Pandas

La documentation officielle de pandas est complète, mais elle peut être dense au début. Ce document propose une paraphrase simplifiée des principales fonctions et méthodes utilisées pendant les semaines 2 à 11.

Chaque entrée indique:

Les exemples privilégient les DataFrame, car c’est l’objet principal manipulé dans le cours.

Documentation

.abs()

Documentation officielle

Objectif: calculer la valeur absolue de chaque valeur numérique.

Arguments principaux:

  • Aucun argument n’est requis; la méthode s’applique à chaque valeur numérique de la Series ou du DataFrame.

Exemple:

resultats["ecart"] = (
    resultats["rho_spearman"] - rho
).abs()
1
Calculer la valeur absolue de chaque valeur numérique.

À retenir: utile pour mesurer un écart sans tenir compte du signe.

.agg()

Documentation officielle

Objectif: appliquer une ou plusieurs fonctions de résumé à un tableau ou à des groupes.

Arguments principaux:

  • func (str, fonction ou list): opération à appliquer, par exemple "mean", "median", "count" ou une liste de ces fonctions;
  • nom_resultat=("colonne", "fonction") (tuple[str, str]): syntaxe nommée indiquant la colonne source et le résumé à calculer après groupby().

Exemple:

resume = (
    df
    .groupby("water_body")
    .agg(
        n=("max_water_height_m", "count"),
        moyenne_m=("max_water_height_m", "mean"),
        mediane_m=("max_water_height_m", "median"),
    )
)
1
Appliquer une ou plusieurs fonctions de résumé à un tableau ou à des groupes.

À retenir: après groupby(), .agg() permet de construire un tableau de synthèse propre.

.copy()

Documentation officielle

Objectif: créer une copie indépendante d’un tableau.

Arguments principaux:

  • deep (bool): True crée une copie indépendante des données et de leur index.

Exemple:

df_valides = df[df["is_valid_entry"]].copy()
1
Créer une copie indépendante d’un tableau.

À retenir: après un filtrage, .copy() rend le code plus explicite et évite certains avertissements lorsque l’on ajoute des colonnes.

.clip()

Documentation officielle

Objectif: limiter les valeurs numériques à un intervalle donné.

Arguments principaux:

  • lower (float): valeur minimale autorisée; les valeurs plus faibles sont remplacées par cette borne;
  • upper (float): valeur maximale autorisée; les valeurs plus élevées sont remplacées par cette borne.

Exemple:

df["VEI_limite"] = df["VEI"].clip(lower=0, upper=8)
1
Limiter les valeurs numériques à un intervalle donné.

À retenir: .clip() remplace les valeurs situées hors de l’intervalle par les bornes choisies. Il faut toujours justifier scientifiquement cette transformation.

.corr()

Documentation officielle

Objectif: calculer des corrélations entre colonnes numériques.

Arguments principaux:

  • method (str): coefficient à calculer; "pearson" mesure une relation linéaire et "spearman" une association fondée sur les rangs;
  • numeric_only (bool): limiter la matrice aux colonnes numériques du DataFrame.

Exemple:

correlation = df[
    ["landslide_volume_m3", "max_water_height_m"]
].corr(method="spearman")
1
Calculer des corrélations entre colonnes numériques.

À retenir: une corrélation décrit une association statistique. Elle ne prouve pas une relation de cause à effet.

.columns

Documentation officielle

Objectif: obtenir les noms des colonnes d’un DataFrame.

Arguments principaux:

  • Aucun argument: .columns est un attribut qui renvoie l’Index contenant les noms des colonnes.

Exemple:

df.columns
1
Obtenir les noms des colonnes d’un DataFrame.

À retenir: on ajoute souvent .tolist() pour convertir les noms de colonnes en liste Python plus facile à lire.

pd.DataFrame()

Documentation officielle

Objectif: créer un tableau pandas à partir de données déjà disponibles en Python.

Arguments principaux:

  • data (dict ou liste de dict): données à organiser en lignes et colonnes;
  • columns (list[str]): noms et ordre des colonnes à conserver.

Exemple:

resultats = pd.DataFrame(resultats)
1
Créer un tableau pandas à partir de données déjà disponibles en Python.

À retenir: dans le cours, cette fonction sert surtout à transformer une liste de résultats en tableau exploitable.

.describe()

Documentation officielle

Objectif: produire rapidement des statistiques descriptives.

Arguments principaux:

  • include (str): "all" inclut aussi les colonnes non numériques d’un DataFrame;
  • percentiles (list[float]): quantiles à afficher, exprimés entre 0 et 1.

Exemple:

df[["max_water_height_m", "landslide_volume_m3"]].describe()
1
Produire rapidement des statistiques descriptives.

À retenir: bon premier aperçu, mais il ne remplace pas une inspection des valeurs extrêmes et des données manquantes.

.drop()

Documentation officielle

Objectif: retirer des lignes ou des colonnes.

Arguments principaux:

  • index (str, int ou liste): étiquette(s) des lignes à retirer;
  • columns (str ou list[str]): nom(s) des colonnes à retirer;
  • inplace (bool): False renvoie un nouveau tableau sans modifier l’original.

Exemple:

i_max = df[["max_water_height_m"]].idxmax().iloc[0]
df_sans_max = df.drop(index=i_max)
1
Retirer des lignes ou des colonnes.

À retenir: utile pour tester si un résultat dépend d’un événement extrême.

.drop_duplicates()

Documentation officielle

Objectif: supprimer les lignes dupliquées selon une ou plusieurs colonnes.

Arguments principaux:

  • subset (str ou list[str]): colonne(s) utilisées pour identifier les doublons;
  • keep (str ou bool): "first" conserve la première occurrence, "last" la dernière et False supprime toutes les occurrences dupliquées.

Exemple:

tsunamis = (
    df
    .sort_values(["tsunami_id", "landslide_id"])
    .drop_duplicates(subset="tsunami_id")
    .copy()
)
1
Supprimer les lignes dupliquées selon une ou plusieurs colonnes.

À retenir: le tri avant .drop_duplicates() détermine quelle ligne sera conservée.

.dropna()

Documentation officielle

Objectif: retirer les lignes ou colonnes qui contiennent des valeurs manquantes.

Arguments principaux:

  • subset (list[str]): colonnes dans lesquelles rechercher les valeurs manquantes;
  • how (str): "any" retire une ligne dès qu’une valeur est manquante; "all" exige que toutes le soient.

Exemple:

hauteurs = df.dropna(subset=["max_water_height_m"]).copy()
1
Retirer les lignes ou colonnes qui contiennent des valeurs manquantes.

À retenir: toujours préciser les colonnes importantes avec subset; sinon on risque de retirer trop de lignes.

.groupby()

Documentation officielle

Objectif: diviser un tableau en groupes selon une ou plusieurs colonnes, puis calculer des résumés par groupe.

Arguments principaux:

  • by (str ou list[str]): colonne(s) catégorielles utilisées pour former les groupes;
  • dropna (bool): False conserve un groupe correspondant aux valeurs manquantes;
  • observed (bool): True conserve uniquement les catégories réellement observées.

Exemple:

resume = (
    df
    .groupby("landslide_cause", dropna=False)
    .agg(n=("landslide_id", "count"))
)
1
Diviser un tableau en groupes selon une ou plusieurs colonnes, puis calculer des résumés par groupe.

À retenir: groupby() prépare les groupes; il faut ensuite appeler une méthode comme .agg(), .mean() ou .median().

.size() après groupby()

Documentation officielle

Objectif: compter le nombre de lignes dans chaque groupe, y compris lorsque certaines valeurs des autres colonnes sont manquantes.

Arguments principaux:

  • Aucun argument: après groupby(), la méthode renvoie le nombre de lignes de chaque groupe sous la forme d’une Series.

Exemple:

effectifs = df.groupby("contexte").size()
1
Compter toutes les lignes de chaque contexte.

À retenir: .size() compte les lignes; .count() compte les valeurs non manquantes d’une colonne.

.head()

Documentation officielle

Objectif: afficher les premières lignes d’un tableau.

Arguments principaux:

  • n (int): nombre de premières lignes à renvoyer; la valeur par défaut est 5.

Exemple:

df.head(10)
1
Afficher les premières lignes d’un tableau.

À retenir: .head() sert à inspecter, pas à analyser tout le tableau.

.tail()

Documentation officielle

Objectif: afficher les dernières lignes d’un tableau.

Arguments principaux:

  • n (int): nombre de dernières lignes à renvoyer; la valeur par défaut est 5.

Exemple:

df.tail(10)
1
Afficher les dix dernières lignes sans modifier le tableau.

À retenir: .tail() complète .head() lorsque l’ordre du fichier peut révéler un problème d’importation ou de tri.

.idxmax()

Documentation officielle

Objectif: trouver l’index de la valeur maximale.

Arguments principaux:

  • axis (int): 0 recherche l’étiquette de la valeur maximale dans chaque colonne.

Exemple:

i_max = df[["max_water_height_m"]].idxmax().iloc[0]
ligne_max = df.loc[i_max]
1
Trouver l’index de la valeur maximale.

À retenir: .idxmax() renvoie l’index, pas la valeur maximale elle-même.

.iloc[]

Documentation officielle

Objectif: sélectionner des lignes ou colonnes selon leur position numérique.

Arguments principaux:

  • rows (int ou slice): position(s) numériques des lignes, par exemple 0 ou :;
  • columns (int ou slice): position(s) numériques des colonnes, placées après la virgule.

Exemple:

rho = df[["landslide_volume_m3", "max_water_height_m"]].corr(method="spearman").iloc[0, 1]
1
Sélectionner des lignes ou colonnes selon leur position numérique.

À retenir: .iloc[] utilise des positions, pas des noms de lignes ou de colonnes.

.info()

Documentation officielle

Objectif: résumer la structure du tableau.

Arguments principaux:

  • verbose (bool): True affiche le détail de toutes les colonnes;
  • show_counts (bool): True affiche le nombre de valeurs non manquantes par colonne.

Exemple:

df.info()
1
Résumer la structure du tableau.

À retenir: c’est souvent l’une des premières commandes à lancer après un import.

.index

Documentation officielle

Objectif: obtenir les labels des lignes d’un DataFrame.

Arguments principaux:

  • Aucun argument: .index est un attribut qui renvoie les étiquettes des lignes sous la forme d’un Index.

Exemple:

df.index
1
Obtenir les labels des lignes d’un DataFrame.

À retenir: l’index identifie les lignes. Il peut s’agir d’une numérotation automatique ou de labels définis avec .set_index().

len()

Documentation officielle

Objectif: compter le nombre de lignes d’un DataFrame.

Arguments principaux:

  • obj (DataFrame, Series, list ou str): objet dont compter le nombre d’éléments.

Exemple:

n = len(df)
1
Compter le nombre de lignes d’un DataFrame.

À retenir: len(df) compte les lignes, pas les tsunamis uniques.

print()

Documentation officielle

Objectif: afficher une valeur ou un message dans la sortie d’une cellule.

Arguments principaux:

  • objects (tout type Python): un ou plusieurs objets à afficher;
  • sep (str): texte placé entre plusieurs objets;
  • end (str): texte ajouté à la fin de l’affichage, "\n" par défaut.

Exemple:

print("Nombre de provinces :", len(df))
1
Afficher un message et le résultat d’un calcul.

À retenir: print() facilite la lecture d’un résultat, mais ne modifie pas les données.

.loc[]

Documentation officielle

Objectif: sélectionner des lignes ou colonnes selon leur nom ou leur index.

Arguments principaux:

  • rows (étiquette, Series booléenne ou slice): lignes sélectionnées par leur nom ou par une condition;
  • columns (str ou list[str]): colonne(s) sélectionnées après la virgule.

Exemple:

i_max = df[["max_water_height_m"]].idxmax().iloc[0]
ligne_max = df.loc[i_max]
1
Sélectionner des lignes ou colonnes selon leur nom ou leur index.

À retenir: .loc[] utilise les étiquettes d’index et les noms de colonnes, contrairement à .iloc[].

.max()

Documentation officielle

Objectif: trouver la valeur maximale dans une ou plusieurs colonnes.

Arguments principaux:

  • numeric_only (bool): True limite le calcul aux colonnes numériques d’un DataFrame;
  • skipna (bool): True ignore les valeurs manquantes.

Exemple:

df[["max_water_height_m", "landslide_volume_m3"]].max()
1
Trouver la valeur maximale dans une ou plusieurs colonnes.

À retenir: .max() renvoie la valeur maximale; .idxmax() renvoie l’index où elle se trouve.

.mean()

Documentation officielle

Objectif: calculer une moyenne.

Arguments principaux:

  • numeric_only (bool): True limite le calcul aux colonnes numériques d’un DataFrame;
  • skipna (bool): True ignore les valeurs manquantes.

Exemple:

df[["max_water_height_m", "landslide_volume_m3"]].mean()
1
Calculer une moyenne.

À retenir: la moyenne est sensible aux valeurs extrêmes.

.median()

Documentation officielle

Objectif: calculer une médiane.

Arguments principaux:

  • numeric_only (bool): True limite le calcul aux colonnes numériques d’un DataFrame;
  • skipna (bool): True ignore les valeurs manquantes.

Exemple:

df[["max_water_height_m", "landslide_volume_m3"]].median()
1
Calculer une médiane.

À retenir: la médiane est souvent plus robuste que la moyenne quand il existe des valeurs extrêmes.

.min()

Documentation officielle

Objectif: trouver la valeur minimale dans une ou plusieurs colonnes.

Arguments principaux:

  • numeric_only (bool): True limite le calcul aux colonnes numériques d’un DataFrame;
  • skipna (bool): True ignore les valeurs manquantes.

Exemple:

df[["max_water_height_m", "landslide_volume_m3"]].min()
1
Trouver la valeur minimale dans une ou plusieurs colonnes.

À retenir: utile pour vérifier les valeurs impossibles, par exemple une hauteur négative.

.mul()

Documentation officielle

Objectif: multiplier les valeurs par un nombre ou par un autre tableau.

Arguments principaux:

  • other (float, Series ou DataFrame): valeur ou objet aligné par lequel multiplier les données.

Exemple:

pourcentages = df[["landslide_volume_m3", "max_water_height_m"]].notna().mean().mul(100)
1
Multiplier les valeurs par un nombre ou par un autre tableau.

À retenir: dans le cours, .mul(100) sert surtout à passer d’une fraction à un pourcentage.

.notna()

Documentation officielle

Objectif: repérer les valeurs disponibles, c’est-à-dire non manquantes.

Arguments principaux:

  • Aucun argument: la méthode teste chaque valeur et renvoie des booléens, avec True pour une valeur présente.

Exemple:

disponibilite = df[["landslide_volume_m3", "max_water_height_m"]].notna().mean()
1
Repérer les valeurs disponibles, c’est-à-dire non manquantes.

À retenir: combiné avec .mean(), .notna() permet de calculer une fraction de données disponibles.

.nunique()

Documentation officielle

Objectif: compter le nombre de valeurs différentes.

Arguments principaux:

  • dropna (bool): True exclut les valeurs manquantes du nombre de valeurs uniques;
  • axis (int): 0 effectue le comptage séparément dans chaque colonne d’un DataFrame.

Exemple:

df[["landslide_id", "tsunami_id"]].nunique()
1
Compter le nombre de valeurs différentes.

À retenir: indispensable pour distinguer le nombre de lignes, de glissements et de tsunamis.

.quantile()

Documentation officielle

Objectif: calculer un quantile.

Arguments principaux:

  • q (float ou list[float]): quantile(s) compris entre 0 et 1; 0.5 correspond à la médiane;
  • numeric_only (bool): True limite le calcul aux colonnes numériques d’un DataFrame.

Exemple:

df[["max_water_height_m"]].quantile(0.75)
1
Calculer un quantile.

À retenir: les quantiles permettent de décrire la dispersion sans dépendre seulement de la moyenne.

pd.read_csv()

Documentation officielle

Objectif: lire un fichier texte tabulaire et le transformer en DataFrame.

Arguments principaux:

  • filepath_or_buffer (str): chemin du fichier CSV à lire;
  • sep (str): caractère séparant les colonnes, "," par défaut;
  • na_values (str ou list): valeurs supplémentaires à interpréter comme manquantes;
  • dtype (dict): type imposé à certaines colonnes, sous la forme {"colonne": "type"}.

Exemple:

df = pd.read_csv("data/Dohmen_et-al_landslides_clean.csv")
1
Lire un fichier texte tabulaire et le transformer en DataFrame.

À retenir: toujours inspecter le résultat avec .head() et .info() après l’import.

.reset_index()

Documentation officielle

Objectif: transformer l’index en colonne ordinaire et recréer un index simple.

Arguments principaux:

  • drop (bool): True supprime l’ancien index au lieu de le transformer en colonne;
  • names (str): nom donné à la colonne créée à partir de l’index.

Exemple:

resume = resume.reset_index()
1
Transformer l’index en colonne ordinaire et recréer un index simple.

À retenir: utile après un groupby() ou un value_counts() pour retrouver un tableau classique.

.round()

Documentation officielle

Objectif: arrondir les valeurs numériques pour l’affichage.

Arguments principaux:

  • decimals (int ou dict[str, int]): nombre de décimales appliqué à toutes les valeurs ou séparément à chaque colonne.

Exemple:

resume.round(2)
1
Arrondir les valeurs numériques pour l’affichage.

À retenir: arrondir améliore la lisibilité, mais il vaut mieux garder les valeurs non arrondies pour les calculs.

.set_index()

Documentation officielle

Objectif: utiliser une ou plusieurs colonnes comme labels des lignes.

Arguments principaux:

  • keys (str ou list[str]): colonne(s) à utiliser comme nouvel index;
  • drop (bool): True retire ces colonnes du tableau après leur transfert dans l’index;
  • inplace (bool): False renvoie un nouveau tableau sans modifier l’original.

Exemple:

volcans = df.set_index("Name")
1
Utiliser une ou plusieurs colonnes comme labels des lignes.

À retenir: choisissez comme index une colonne dont les valeurs identifient clairement les observations.

.shape

Documentation officielle

Objectif: connaître la taille d’un DataFrame.

Arguments principaux:

  • Aucun argument: .shape est un attribut qui renvoie un tuple[int, int] contenant le nombre de lignes et de colonnes.

Exemple:

df.shape
1
Connaître la taille d’un DataFrame.

À retenir: le résultat est un couple (nombre_de_lignes, nombre_de_colonnes).

.sort_values()

Documentation officielle

Objectif: trier les lignes selon une ou plusieurs colonnes.

Arguments principaux:

  • by (str ou list[str]): colonne(s) utilisées successivement pour trier les lignes;
  • ascending (bool ou list[bool]): True trie par ordre croissant et False par ordre décroissant.

Exemple:

df2 = df.sort_values("max_water_height_m", ascending=False)
1
Trier les lignes selon une ou plusieurs colonnes.

À retenir: trier ne change pas le sens scientifique des données, mais rend certains événements plus faciles à inspecter.

Méthodes de texte .str

Documentation officielle

Objectif: rechercher, normaliser ou remplacer du texte dans une colonne.

Arguments principaux:

  • .str.contains(pat) (str): teste si chaque valeur contient le texte ou motif régulier fourni;
  • .str.extract(pat) (str): extrait la partie correspondant à une expression régulière;
  • .str.lower(): ne reçoit aucun argument et convertit les textes en minuscules;
  • .str.replace(pat, repl) (str, str): remplace le texte ou motif pat par repl.

Exemple:

df["pays_minuscule"] = df["country"].str.lower()
df[df["event_label"].str.contains("Bay", na=False)]
1
Rechercher, normaliser ou remplacer du texte dans une colonne.

À retenir: les méthodes .str s’appliquent aux valeurs textuelles d’une colonne. Pour .str.contains(), na=False évite qu’une valeur manquante produise un masque indéterminé.

.sum()

Documentation officielle

Objectif: additionner les valeurs.

Arguments principaux:

  • numeric_only (bool): True limite la somme aux colonnes numériques d’un DataFrame;
  • skipna (bool): True ignore les valeurs manquantes.

Exemple:

df[["is_valid_entry", "is_multiple_landslide_tsunami"]].sum()
1
Additionner les valeurs.

À retenir: sur des colonnes booléennes, .sum() compte le nombre de True.

.std()

Documentation officielle

Objectif: calculer l’écart-type empirique d’une série numérique.

Arguments principaux:

  • skipna (bool): True ignore les valeurs manquantes;
  • ddof (int): correction des degrés de liberté; 1 produit l’écart-type d’échantillon avec le dénominateur \(n-1\).

Exemple:

ecart_type = df["hauteur"].std()
1
Mesurer la dispersion des hauteurs autour de leur moyenne dans l’unité originale.

À retenir: l’écart-type décrit la variabilité des observations; il ne doit pas être confondu avec l’erreur-type d’une estimation.

.to_list() / .tolist()

Documentation officielle

Objectif: convertir des noms de colonnes ou des valeurs pandas en liste Python.

Arguments principaux:

  • Aucun argument: la méthode convertit les valeurs de la Series ou du tableau NumPy en list Python.

Exemple:

colonnes = df.columns.tolist()
1
Convertir des noms de colonnes ou des valeurs pandas en liste Python.

À retenir: utile pour afficher ou réutiliser une liste de noms de colonnes.

.value_counts()

Documentation officielle

Objectif: compter les occurrences de valeurs ou de combinaisons de valeurs.

Arguments principaux:

  • subset (list[str]): colonnes utilisées pour compter les combinaisons dans un DataFrame;
  • normalize (bool): True renvoie des proportions plutôt que des effectifs;
  • dropna (bool): False conserve les valeurs manquantes dans le comptage;
  • sort (bool): True classe les résultats par fréquence décroissante.

Exemple:

df[["water_body"]].value_counts(dropna=False)
1
Compter les occurrences de valeurs ou de combinaisons de valeurs.

À retenir: dans le cours, on privilégie df[["water_body"]].value_counts() pour garder l’habitude de partir d’un DataFrame, même lorsqu’une seule colonne est comptée.

.between()

Documentation officielle

Objectif: tester si chaque valeur se trouve dans un intervalle inclusif.

Arguments principaux:

  • left (float): borne inférieure de l’intervalle;
  • right (float): borne supérieure de l’intervalle;
  • inclusive (str): "both" inclut les deux bornes.

Exemple:

df["total"].between(90, 102)
1
Tester si chaque valeur se trouve dans un intervalle inclusif.

À retenir: .between() produit un masque booléen utilisable directement pour filtrer les lignes.

.isin()

Documentation officielle

Objectif: tester si chaque valeur appartient à une liste de valeurs retenues.

Arguments principaux:

  • values (list, set ou Series): ensemble des valeurs considérées comme appartenant à la sélection.

Exemple:

df[df["eruption"].isin(groupes)]
1
Tester si chaque valeur appartient à une liste de valeurs retenues.

À retenir: .isin() simplifie un filtre contenant plusieurs catégories possibles.

.sample()

Documentation officielle

Objectif: sélectionner aléatoirement des lignes.

Arguments principaux:

  • n (int): nombre de lignes à tirer;
  • frac (float): fraction des lignes à tirer, utilisée à la place de n;
  • random_state (int): graine rendant le tirage reproductible.

Exemple:

test = df.sample(frac=0.2, random_state=42)
1
Réserver de manière reproductible 20 % des observations.

À retenir: une graine reproduit le tirage; elle ne garantit pas que le sous-échantillon représente parfaitement la population.

.to_csv()

Documentation officielle

Objectif: enregistrer un DataFrame dans un fichier CSV afin de réutiliser une table préparée.

Arguments principaux:

  • path_or_buf (str): chemin et nom du fichier à créer;
  • index (bool): False n’enregistre pas l’index comme colonne supplémentaire;
  • columns (list[str]): colonnes à exporter et ordre dans lequel les écrire.

Exemple:

df.to_csv(
    "data/echantillon.csv",
    index=False,
)
1
Enregistrer le tableau df dans un fichier CSV.
2
Choisir un nom décrivant le contenu du fichier.
3
Ne pas ajouter l’index de pandas aux variables scientifiques.

À retenir: sauvegarder une table préparée évite de répéter silencieusement des filtres ou des transformations dans une analyse ultérieure. Le nom du fichier doit rendre son contenu et son niveau de préparation explicites.