Fonction Pandas DataFrame.rolling()

La fonction DataFrame.rolling() de Python Pandas fournit une fenêtre glissante pour les opérations mathématiques. Appeler rolling() seul ne calcule rien : la fonction renvoie un objet Rolling qui définit les fenêtres glissantes, puis une méthode d’agrégation comme sum(), mean() ou std() réduit chaque fenêtre à une ligne de résultats. Comme une fenêtre se termine normalement à la ligne courante, le résultat conserve le même index que le DataFrame d’origine, ce qui fait de rolling() la méthode standard pour construire des sommes glissantes, des moyennes mobiles et d’autres statistiques courantes.

Syntaxe de pandas.DataFrame.rolling()

DataFrame.rolling(
    window, min_periods=None, center=False, win_type=None, on=None,
    closed=None, step=None, method='single'
)

Paramètres

Retour

Elle renvoie un objet fenêtre Rolling. Appeler une méthode d’agrégation dessus renvoie un DataFrame avec le même index que l’entrée.

La signature ci-dessus est la signature actuelle. Le paramètre axis que montrent les anciens tutoriels n’existe plus, car une fenêtre glissante se déplace toujours le long de l’index ; le passer lève un TypeError, comme le montre la section d’erreurs ci-dessous.

Exemple : somme glissante avec une fenêtre fixe de 2

La forme la plus courante utilise une fenêtre entière qui compte les lignes. Dans cet exemple, rolling(2).sum() ajoute chaque ligne à la ligne juste au-dessus.

import pandas as pd

dataframe = pd.DataFrame({
    'Attendance': {0: 60, 1: 100, 2: 80, 3: 78, 4: 95},
    'Obtained Marks': {0: 90, 1: 75, 2: 82, 3: 64, 4: 45},
})
print("The Original DataFrame is:")
print(dataframe)
print("The Rolling Sum With a Window of 2 is:")
print(dataframe.rolling(2).sum())

Production :

The Original DataFrame is:
   Attendance  Obtained Marks
0          60              90
1         100              75
2          80              82
3          78              64
4          95              45
The Rolling Sum With a Window of 2 is:
   Attendance  Obtained Marks
0         NaN             NaN
1       160.0           165.0
2       180.0           157.0
3       158.0           146.0
4       173.0           109.0

La ligne 0 n’a aucune ligne au-dessus d’elle, donc sa fenêtre ne contient qu’une seule observation — moins que les deux exigées par min_periods par défaut — et le résultat est NaN. À partir de la ligne 1, chaque valeur est la somme de la ligne courante et de la ligne précédente : 60 + 100 = 160, 100 + 80 = 180, et ainsi de suite. Les colonnes entières deviennent des flottants à cause de ce premier NaN.

Exemple : moyenne glissante et min_periods

La même fenêtre fonctionne avec n’importe quelle agrégation. Ici, rolling(3).mean() calcule la moyenne de la ligne courante et des deux lignes au-dessus. Avec min_periods par défaut, les deux premières lignes ne peuvent pas remplir une fenêtre de trois lignes et restent à NaN. Régler min_periods=1 indique à pandas de travailler avec le nombre d’observations disponibles au début, donc le résultat est défini dès la première ligne.

import pandas as pd

dataframe = pd.DataFrame({
    'Attendance': {0: 60, 1: 100, 2: 80, 3: 78, 4: 95},
    'Obtained Marks': {0: 90, 1: 75, 2: 82, 3: 64, 4: 45},
})
print("The Rolling Mean With a Window of 3 is:")
print(dataframe.rolling(3).mean())
print("The Rolling Mean With a Window of 3 and min_periods=1 is:")
print(dataframe.rolling(3, min_periods=1).mean())

Production :

The Rolling Mean With a Window of 3 is:
   Attendance  Obtained Marks
0         NaN             NaN
1         NaN             NaN
2   80.000000       82.333333
3   86.000000       73.666667
4   84.333333       63.666667
The Rolling Mean With a Window of 3 and min_periods=1 is:
   Attendance  Obtained Marks
0   60.000000       90.000000
1   80.000000       82.500000
2   80.000000       82.333333
3   86.000000       73.666667
4   84.333333       63.666667

Les deux sorties concordent à partir de l’index 2. La différence se situe au début : min_periods=1 rapporte en plus 60.00 pour la première ligne (cette valeur seule) et 80.00 pour la deuxième (la moyenne des deux premières valeurs). Notez que min_periods compte les observations qui ne sont pas NaN, ce qui en fait aussi le principal réglage pour les trous dans les données, comme le montre le dernier exemple.

Exemple : somme glissante sur une fenêtre temporelle

window peut aussi être un décalage temporel tel que '3D'. La fenêtre couvre alors un intervalle de temps plutôt qu’un nombre fixe de lignes, donc les enregistrements ne contribuent que s’ils tombent dans l’intervalle, quelle que soit l’irrégularité de leur espacement. Lorsque les dates se trouvent dans une colonne plutôt que dans l’index, nommez cette colonne avec on. Les ventes ci-dessous n’ont aucun enregistrement pour 2026-01-04 et 2026-01-07.

import pandas as pd

sales = pd.DataFrame({
    'Date': pd.to_datetime(['2026-01-01', '2026-01-02', '2026-01-03',
                            '2026-01-05', '2026-01-06', '2026-01-08']),
    'Sales': [120, 80, 150, 90, 200, 60],
})
print(sales)
print("The Rolling Sum Over the Previous 3 Days is:")
print(sales.rolling('3D', on='Date').sum())

Production :

        Date  Sales
0 2026-01-01    120
1 2026-01-02     80
2 2026-01-03    150
3 2026-01-05     90
4 2026-01-06    200
5 2026-01-08     60
The Rolling Sum Over the Previous 3 Days is:
        Date  Sales
0 2026-01-01  120.0
1 2026-01-02  200.0
2 2026-01-03  350.0
3 2026-01-05  240.0
4 2026-01-06  290.0
5 2026-01-08  260.0

Pour 2026-01-05, la fenêtre de trois jours remonte au-delà de 2026-01-02, elle ne contient donc que les ventes de 2026-01-03 et de 2026-01-05 : 150 + 90 = 240. Le 2026-01-04 manquant ne contribue à rien et ne décale pas l’intervalle comme une ligne supplémentaire décalerait une fenêtre fixe. Remarquez que la première ligne a déjà un résultat : une fenêtre temporelle utilise min_periods=1 par défaut, le défaut opposé à celui des fenêtres fixes.

Exemple : centrer les étiquettes avec center et exclure la ligne courante avec closed

Deux paramètres changent l’endroit où appartient un résultat. Avec center=True, la valeur agrégée est placée sur la ligne centrale de sa fenêtre au lieu de la dernière, ce qui convient lorsqu’une moyenne mobile doit s’aligner sur les données qu’elle lisse ; la première et la dernière ligne perdent leur résultat, car aucune fenêtre complète n’est centrée sur elles. closed contrôle quelle extrémité de l’intervalle est incluse : avec closed='left', la fenêtre d’une ligne couvre les lignes qui la précèdent et la ligne elle-même est exclue de sa propre statistique.

import pandas as pd

temps = pd.DataFrame({'Temperature': [10, 12, 14, 16, 18, 20]})
print("The Centered Rolling Mean With a Window of 3 is:")
print(temps.rolling(3, center=True).mean())
print("The Rolling Sum With a Window of 3 and closed='left' is:")
print(temps.rolling(3, closed='left').sum())

Production :

The Centered Rolling Mean With a Window of 3 is:
   Temperature
0          NaN
1         12.0
2         14.0
3         16.0
4         18.0
5          NaN
The Rolling Sum With a Window of 3 and closed='left' is:
   Temperature
0          NaN
1          NaN
2          NaN
3         36.0
4         42.0
5         48.0

La moyenne centrée à l’index 1 vaut 12.0 — la moyenne de 10, 12 et 14 — et elle se trouve sur la ligne centrale de cette fenêtre. Les sommes avec closed='left' montrent le motif familier 36, 42, 48 décalé d’une ligne vers le bas : à l’index 3, la fenêtre contient les lignes 0 à 2 (10 + 12 + 14 = 36), car la ligne 3 elle-même est exclue.

Erreurs courantes et cas limites

Trois comportements surprennent le plus souvent les utilisateurs, et chacun se voit dans un petit exemple.

Valeurs manquantes à l’intérieur de la fenêtre

Comme min_periods compte les observations qui ne sont pas NaN, une seule valeur manquante vide chaque fenêtre fixe qui la contient, ainsi que la fenêtre qui la suit. Abaisser min_periods fait travailler l’agrégation avec les valeurs qui existent.

import pandas as pd

scores = pd.DataFrame({'Score': [50.0, None, 70.0, 90.0]})
print(scores)
print("The Rolling Sum With a Window of 2 is:")
print(scores.rolling(2).sum())
print("The Rolling Sum With a Window of 2 and min_periods=1 is:")
print(scores.rolling(2, min_periods=1).sum())

Production :

   Score
0   50.0
1    NaN
2   70.0
3   90.0
The Rolling Sum With a Window of 2 is:
   Score
0    NaN
1    NaN
2    NaN
3  160.0
The Rolling Sum With a Window of 2 and min_periods=1 is:
   Score
0   50.0
1   50.0
2   70.0
3  160.0

Avec les réglages par défaut, seule la dernière somme, 70 + 90, survit. Avec min_periods=1, la fenêtre à l’index 2 contient une valeur valide, donc sa somme est 70 : l’entrée manquante est ignorée au lieu d’être propagée. Aucun des deux comportements ne répare les données — choisissez entre eux selon qu’une fenêtre partielle a un sens pour votre statistique.

Les arguments invalides lèvent ValueError

rolling() valide ses arguments avant tout calcul. Une fenêtre négative échoue immédiatement :

import pandas as pd

temps = pd.DataFrame({'Temperature': [10, 12, 14, 16, 18, 20]})
print(temps.rolling(-1).sum())

Production :

ValueError: window must be an integer 0 or greater

Une valeur closed inconnue échoue de la même façon, avec ValueError: closed must be 'right', 'left', 'both' or 'neither', et une fenêtre fractionnaire telle que 2.5 est rejetée avec le même message que la fenêtre négative. Notez que window=0 est accepté mais dégénéré : chaque fenêtre est vide, donc sum() renvoie 0.0 pour chaque ligne.

Les colonnes non numériques lèvent DataError

Les agrégations n’acceptent que les données numériques. Appliquer une fenêtre glissante à un DataFrame qui contient encore une colonne de texte lève une erreur :

import pandas as pd

mixed = pd.DataFrame({'Name': ['A', 'B', 'C'], 'Value': [1, 2, 3]})
print(mixed.rolling(2).sum())

Production :

pandas.errors.DataError: Cannot aggregate non-numeric type: str

Sélectionnez les colonnes numériques avant d’appliquer la fenêtre — par exemple mixed[['Value']].rolling(2).sum() — ou supprimez d’abord les colonnes d’étiquettes.

Points à retenir

• rolling() seul renvoie un objet Rolling ; rien n’est calculé tant qu’une méthode d’agrégation n’est pas appelée. Le résultat porte toujours l’index de l’entrée, donc il peut être assigné directement comme nouvelle colonne.
• Les colonnes entières deviennent des flottants dès qu’un NaN apparaît dans la sortie, car NaN n’a pas de représentation entière.
• Pour les calculs groupés, appelez rolling() sur un objet groupby, comme dans df.groupby('key').rolling(2).sum() : la fenêtre redémarre alors à chaque groupe au lieu de franchir les limites des groupes.
• Les fenêtres pondérées via win_type sont destinées aux données de type signal ; pour des données métier ordinaires, les agrégations non pondérées des exemples ci-dessus sont le bon choix par défaut.