Función Pandas DataFrame.rolling()

La función DataFrame.rolling() de Python Pandas proporciona una ventana rodante para operaciones matemáticas. Llamar a rolling() por sí solo no calcula nada: devuelve un objeto Rolling que define las ventanas móviles, y un método de agregación como sum(), mean() o std() reduce después cada ventana a una fila de resultados. Como una ventana normalmente termina en la fila actual, el resultado conserva el mismo índice que el DataFrame original, lo que convierte a rolling() en la forma estándar de construir sumas acumuladas móviles, medias móviles y otras estadísticas en curso.

Sintaxis de pandas.DataFrame.rolling()

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

Parámetros

Retorno

Devuelve un objeto de ventana Rolling. Al llamar a un método de agregación sobre él se obtiene un DataFrame con el mismo índice que la entrada.

La firma anterior es la actual. El parámetro axis que muestran los tutoriales antiguos ya no existe, porque una ventana rodante siempre se desplaza a lo largo del índice; pasarlo produce un TypeError, como se muestra en la sección de errores siguiente.

Ejemplo: suma rodante con una ventana fija de 2

La forma más común usa una ventana entera que cuenta filas. En este ejemplo, rolling(2).sum() suma cada fila con la fila directamente superior.

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())

Producción:

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 fila 0 no tiene ninguna fila encima, así que su ventana contiene una sola observación —menos de las dos que exige el min_periods predeterminado— y el resultado es NaN. A partir de la fila 1, cada valor es la suma de la fila actual y la anterior: 60 + 100 = 160, 100 + 80 = 180, y así sucesivamente. Las columnas enteras se convierten en flotantes a causa de ese primer NaN.

Ejemplo: media rodante y min_periods

La misma ventana funciona con cualquier agregación. Aquí, rolling(3).mean() promedia la fila actual y las dos filas superiores. Con el min_periods predeterminado, las dos primeras filas no pueden llenar una ventana de tres filas y permanecen en NaN. Al establecer min_periods=1, pandas trabaja con las observaciones que haya disponibles al principio, de modo que el resultado está definido desde la primera fila.

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())

Producción:

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

Las dos salidas coinciden a partir del índice 2. La diferencia está al principio: min_periods=1 informa además de 60.00 para la primera fila (ese valor solo) y de 80.00 para la segunda (la media de los dos primeros valores). Tenga en cuenta que min_periods cuenta las observaciones que no son NaN, lo que también lo convierte en el control principal para los huecos dentro de los datos, como muestra el último ejemplo.

Ejemplo: suma rodante sobre una ventana basada en tiempo

window también puede ser un desplazamiento temporal como '3D'. En ese caso la ventana cubre un intervalo de tiempo en lugar de un número fijo de filas, de modo que los registros solo contribuyen cuando caen dentro del intervalo, sin importar lo irregularmente espaciados que estén. Cuando las fechas están en una columna en lugar de en el índice, indique esa columna con on. Las ventas siguientes no tienen registros para 2026-01-04 ni para 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())

Producción:

        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

Para 2026-01-05, la ventana de tres días se remonta más allá de 2026-01-02, así que contiene únicamente las ventas de 2026-01-03 y 2026-01-05: 150 + 90 = 240. El 2026-01-04 ausente no aporta nada y no desplaza el intervalo como una fila adicional desplazaría una ventana fija. Observe que la primera fila ya tiene un resultado: una ventana basada en tiempo usa min_periods=1 por defecto, el valor predeterminado opuesto al de las ventanas fijas.

Ejemplo: centrar las etiquetas con center y excluir la fila actual con closed

Dos parámetros cambian el lugar al que pertenece un resultado. Con center=True, el valor agregado se coloca en la fila central de su ventana en lugar de en la última, que es lo que se busca cuando una media móvil debe alinearse con los datos que suaviza; la primera y la última fila pierden su resultado, porque ninguna ventana completa está centrada en ellas. closed controla qué extremo del intervalo se incluye: con closed='left', la ventana de una fila cubre las filas anteriores y la propia fila queda fuera de su estadística.

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())

Producción:

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 media centrada en el índice 1 es 12.0 —la media de 10, 12 y 14— y se sitúa en la fila central de esa ventana. Las sumas con closed='left' muestran el conocido patrón 36, 42, 48 desplazado una fila hacia abajo: en el índice 3 la ventana contiene las filas 0 a 2 (10 + 12 + 14 = 36), porque la propia fila 3 está excluida.

Errores comunes y casos límite

Tres comportamientos sorprenden a los usuarios con más frecuencia, y cada uno se aprecia en un ejemplo pequeño.

Valores ausentes dentro de la ventana

Como min_periods cuenta las observaciones que no son NaN, un solo valor ausente vacía cada ventana fija que lo contiene, además de la ventana siguiente. Reducir min_periods hace que la agregación use los valores que sí existen.

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())

Producción:

   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

Con los ajustes predeterminados, solo sobrevive la última suma, 70 + 90. Con min_periods=1, la ventana del índice 2 contiene un valor válido, así que su suma es 70: la entrada ausente se omite en lugar de propagarse. Ninguno de los dos comportamientos repara los datos: elija entre ellos según si una ventana parcial tiene sentido para su estadística.

Los argumentos no válidos producen ValueError

rolling() valida sus argumentos antes de calcular nada. Una ventana negativa falla de inmediato:

import pandas as pd

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

Producción:

ValueError: window must be an integer 0 or greater

Un valor de closed desconocido falla del mismo modo, con ValueError: closed must be 'right', 'left', 'both' or 'neither', y una ventana fraccionaria como 2.5 se rechaza con el mismo mensaje que la ventana negativa. Tenga en cuenta que window=0 se acepta, pero es degenerado: cada ventana está vacía, por lo que sum() devuelve 0.0 para cada fila.

Las columnas no numéricas producen DataError

Las agregaciones solo aceptan datos numéricos. Aplicar la ventana rodante a un DataFrame que aún contiene una columna de texto produce un error:

import pandas as pd

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

Producción:

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

Seleccione las columnas numéricas antes de aplicar la ventana —por ejemplo, mixed[['Value']].rolling(2).sum()— o elimine primero las columnas de etiquetas.

Aspectos a tener en cuenta

• rolling() por sí solo devuelve un objeto Rolling; no se calcula nada hasta que se llama a un método de agregación. El resultado siempre lleva el índice de la entrada, así que puede asignarse directamente como una columna nueva.
• Las columnas enteras se convierten en flotantes en cuanto aparece un NaN en la salida, porque NaN no tiene representación entera.
• Para cálculos agrupados, llame a rolling() sobre un objeto groupby, como en df.groupby('key').rolling(2).sum(): la ventana se reinicia en cada grupo en lugar de cruzar los límites entre grupos.
• Las ventanas ponderadas mediante win_type están pensadas para datos de tipo señal; para datos comerciales ordinarios, las agregaciones sin ponderar de los ejemplos anteriores son la opción predeterminada adecuada.