Função Pandas DataFrame.rolling()

A função DataFrame.rolling() do Python Pandas fornece uma janela rolante para operações matemáticas. Chamar rolling() sozinha não calcula nada: ela retorna um objeto Rolling que define as janelas móveis, e um método de agregação como sum(), mean() ou std() reduz então cada janela a uma linha de resultados. Como uma janela normalmente termina na linha atual, o resultado mantém o mesmo índice do DataFrame original, o que torna rolling() a forma padrão de construir somas acumuladas móveis, médias móveis e outras estatísticas em execução.

Sintaxe 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

Retorna um objeto de janela Rolling. Chamar um método de agregação sobre ele retorna um DataFrame com o mesmo índice da entrada.

A assinatura acima é a atual. O parâmetro axis que os tutoriais mais antigos mostram não existe mais, porque uma janela rolante sempre se move ao longo do índice; passá-lo gera um TypeError, como mostrado na seção de erros abaixo.

Exemplo: soma rolante com uma janela fixa de 2

A forma mais comum usa uma janela inteira que conta linhas. Neste exemplo, rolling(2).sum() soma cada linha à linha diretamente acima dela.

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

Resultado:

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

A linha 0 não tem nenhuma linha acima dela, portanto sua janela contém uma única observação — menos do que as duas que o min_periods padrão exige — e o resultado é NaN. A partir da linha 1, cada valor é a soma da linha atual com a anterior: 60 + 100 = 160, 100 + 80 = 180, e assim por diante. As colunas inteiras se tornam floats por causa desse primeiro NaN.

Exemplo: média rolante e min_periods

A mesma janela funciona com qualquer agregação. Aqui, rolling(3).mean() calcula a média da linha atual e das duas linhas acima dela. Com o min_periods padrão, as duas primeiras linhas não conseguem preencher uma janela de três linhas e permanecem NaN. Definir min_periods=1 diz ao pandas para trabalhar com quantas observações estiverem disponíveis no início, de modo que o resultado é definido desde a primeira linha.

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

Resultado:

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

As duas saídas coincidem a partir do índice 2. A diferença está no topo: min_periods=1 informa adicionalmente 60.00 para a primeira linha (esse valor sozinho) e 80.00 para a segunda (a média dos dois primeiros valores). Observe que min_periods conta as observações que não são NaN, o que também o torna o principal controle para lacunas dentro dos dados, como mostra o último exemplo.

Exemplo: soma rolante sobre uma janela baseada em tempo

window também pode ser um deslocamento de tempo como '3D'. A janela então cobre um intervalo de tempo em vez de um número fixo de linhas, de modo que os registros só contribuem quando caem dentro do intervalo, não importa o quão irregularmente estejam espaçados. Quando as datas estão em uma coluna em vez de no índice, nomeie essa coluna com on. As vendas abaixo não têm registros para 2026-01-04 e 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())

Resultado:

        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, a janela de três dias recua para além de 2026-01-02, portanto contém apenas as vendas de 2026-01-03 e 2026-01-05: 150 + 90 = 240. O 2026-01-04 ausente não contribui em nada e não desloca o intervalo do jeito que uma linha extra deslocaria uma janela fixa. Observe que a primeira linha já tem um resultado: uma janela baseada em tempo usa min_periods=1 por padrão, o padrão oposto ao das janelas fixas.

Exemplo: centralizar os rótulos com center e excluir a linha atual com closed

Dois parâmetros mudam o local ao qual um resultado pertence. Com center=True, o valor agregado é colocado na linha central de sua janela em vez de na última, que é o que você quer quando uma média móvel deve se alinhar aos dados que ela suaviza; a primeira e a última linha perdem seu resultado, porque nenhuma janela completa está centrada nelas. closed controla qual extremidade do intervalo é incluída: com closed='left', a janela de uma linha cobre as linhas anteriores a ela e a própria linha fica fora de sua estatí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())

Resultado:

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

A média centrada no índice 1 é 12.0 — a média de 10, 12 e 14 — e ela fica na linha central dessa janela. As somas com closed='left' mostram o familiar padrão 36, 42, 48 deslocado uma linha para baixo: no índice 3, a janela contém as linhas de 0 a 2 (10 + 12 + 14 = 36), porque a própria linha 3 está excluída.

Erros comuns e casos limites

Três comportamentos surpreendem os usuários com mais frequência, e cada um deles é visível em um pequeno exemplo.

Valores ausentes dentro da janela

Como min_periods conta as observações que não são NaN, um único valor ausente esvazia cada janela fixa que o contém, além da janela seguinte a ela. Reduzir min_periods faz a agregação usar os valores que existem.

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

Resultado:

   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

Com as configurações padrão, apenas a última soma, 70 + 90, sobrevive. Com min_periods=1, a janela no índice 2 contém um valor válido, portanto sua soma é 70: a entrada ausente é ignorada em vez de propagada. Nenhum dos dois comportamentos repara os dados — escolha entre eles com base em se uma janela parcial faz sentido para a sua estatística.

Argumentos inválidos geram ValueError

rolling() valida seus argumentos antes de qualquer cálculo. Uma janela negativa falha imediatamente:

import pandas as pd

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

Resultado:

ValueError: window must be an integer 0 or greater

Um valor closed desconhecido falha da mesma forma, com ValueError: closed must be 'right', 'left', 'both' or 'neither', e uma janela fracionária como 2.5 é rejeitada com a mesma mensagem da janela negativa. Observe que window=0 é aceito, mas é degenerado: cada janela está vazia, portanto sum() retorna 0.0 para cada linha.

Colunas não numéricas geram DataError

As agregações aceitam apenas dados numéricos. Aplicar uma janela rolante a um DataFrame que ainda contém uma coluna de texto gera um erro:

import pandas as pd

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

Resultado:

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

Selecione as colunas numéricas antes de aplicar a janela — por exemplo, mixed[['Value']].rolling(2).sum() — ou remova primeiro as colunas de rótulos.

Pontos para ter em mente

• rolling() por si só retorna um objeto Rolling; nada é calculado até que um método de agregação seja chamado. O resultado sempre carrega o índice da entrada, portanto pode ser atribuído diretamente como uma nova coluna.
• Colunas inteiras se tornam floats assim que um NaN aparece na saída, porque NaN não tem representação inteira.
• Para cálculos agrupados, chame rolling() em um objeto groupby, como em df.groupby('key').rolling(2).sum(): a janela então recomeça em cada grupo em vez de cruzar os limites dos grupos.
• Janelas ponderadas por meio de win_type são destinadas a dados do tipo sinal; para dados comerciais comuns, as agregações não ponderadas dos exemplos acima são o padrão correto.