Datas e séries temporais com pandas

Uma data é mais útil quando o pandas sabe que ela é uma data. Uma série temporal associa observações a momentos ou intervalos de tempo. Leituras horárias de energia formam uma série regular; pedidos que chegam em intervalos desiguais formam uma série irregular. Um texto como “12/31/2024” pode ser ordenado depois de “03/01/2025”, embora dezembro tenha vindo antes. Strings ISO completas e consistentes são ordenadas corretamente, mas valores de data e hora também permitem seleção por calendário e aritmética.

Escolha o objeto de tempo adequado

O Python fornece datetime, date e timedelta. No pandas, um Timestamp contém um momento, uma coluna de datas e horas tem um tipo de dados datetime64[unit], e um DatetimeIndex contém rótulos de linha de data e hora. NaT indica uma data ou hora ausente. Detecte-o com pd.isna(); subtrair uma data ou hora ausente produz outra data ou hora ausente.

A unidade em datetime64[us] é microssegundos, a resolução de armazenamento. Outras unidades incluem segundos (s), milissegundos (ms) e nanossegundos (ns). O pandas 3 normalmente interpreta texto com resolução de microssegundos, usando nanossegundos quando o texto precisa deles. Uma resolução mais fina usa mais do intervalo de inteiros: datas em nanossegundos vão apenas de 1677 a 2262.

Calcule o tempo decorrido

import pandas as pd
start = pd.Timestamp("2025-03-10 18:00")
end = pd.Timestamp("2025-03-14 09:30")
elapsed = end - start
hours = elapsed / pd.Timedelta(hours=1)

elapsed é 3 dias, 15 horas e 30 minutos. Os três dias contribuem com 72 horas, então hours é 87,5. elapsed.total_seconds() fornece 315.000. Seu atributo .days fornece apenas 3; ele é o componente de dias inteiros, não a duração completa em dias. Construa durações com pd.Timedelta(hours=36) ou interprete várias com pd.to_timedelta(["1h", "90min"]).

Subtrair uma marca temporal de uma coluna inteira de datas e horas produz durações linha a linha. Use .dt.days para componentes de dias inteiros ou divida a coluna de durações por um Timedelta de uma unidade para obter totais fracionários.

Leia componentes do calendário e arredonde horários

Em uma coluna, .dt.year, .dt.month, .dt.hour e .dt.quarter extraem componentes do calendário. .dt.day_of_week numera segunda-feira como 0 até domingo como 6; .dt.day_name() fornece um nome. 14 de março de 2025 é sexta-feira, número 4. Um índice usa esses atributos diretamente: df.index.month. As grafias day_of_week e day_of_year substituem grafias antigas marcadas como obsoletas no pandas 3.1.

Um dia da semana pode se tornar uma chave de agrupamento: df.groupby(df["timestamp"].dt.day_name())["kwh"].mean(). Agrupar pelo número do mês combina esse mês de anos diferentes; um período mensal mantém cada ano separado.

Para 09:37, .dt.floor("h") fornece 09:00, .dt.ceil("h") fornece 10:00 e .dt.round("15min") fornece 09:30. .dt.normalize() define os horários como meia-noite e mantém os valores de data e hora. .dt.date produz objetos de data do Python e perde recursos de uma coluna de datas e horas.

Mantenha explícitas as unidades numéricas

astype("int64") retorna contagens na própria unidade da coluna. Uma contagem em microssegundos é 1.000 vezes menor que a contagem em nanossegundos para o mesmo momento. Se um cálculo externo precisar de nanossegundos, use s.dt.as_unit("ns").astype("int64"); um Timestamp ou índice usa .as_unit("ns") diretamente. Para tempo decorrido, a aritmética de Timedelta evita essa armadilha de unidade.

A interpretação dá ao texto um significado de calendário. Antes de converter uma coluna de datas, estabeleça seu formato e verifique se ela contém deslocamentos, entradas inválidas ou valores ausentes. ISO 8601 escreve o ano primeiro, como em “2025-03-14T09:30:00”, e evita a ambiguidade entre dia e mês.

Informe o formato de origem

“03/04/2025” pode significar 4 de março ou 3 de abril. pd.to_datetime("03/04/2025") lê o mês primeiro; dayfirst=True lê o dia primeiro. Um formato conhecido é mais claro:

raw = pd.Series(["14/03/2025 18:45", "15/03/2025 09:00"])
parsed = pd.to_datetime(raw, format="%d/%m/%Y %H:%M")

%Y é um ano de quatro dígitos, %m um mês e %d um dia. %H é uma hora em relógio de 24 horas, %M um minuto e %S um segundo. Use %I com %p para um relógio de 12 horas e AM/PM. %b e %B leem nomes abreviados e completos de meses. %M maiúsculo significa minutos, portanto não pode substituir %m minúsculo para meses.

Sem format, o pandas infere um formato a partir da primeira entrada não ausente e o aplica à coluna. Com “03/04/2025” primeiro, um “13/04/2025” posterior falha sob a inferência de mês primeiro. Reordenar as linhas pode mudar o formato inferido. format="ISO8601" trata variantes ISO. format="mixed" interpreta as entradas individualmente, mas não resolve uma convenção ambígua na origem; limpe ou verifique essa convenção primeiro.

Inspecione conversões que falharam

raw = pd.Series(["2025-01-15", "not a date", None])
parsed = pd.to_datetime(raw, format="%Y-%m-%d", errors="coerce")
failed = parsed.isna() & raw.notna()

O resultado contém 15 de janeiro e dois valores NaT. parsed.isna().sum() é 2 porque inclui a entrada originalmente ausente. failed.sum() é 1 porque apenas “not a date” estava presente e falhou. Inspecione raw[failed] antes de decidir corrigir ou remover o valor. A coerção permite que um carregamento continue, mas também oculta erros de digitação, como um mês impossível. O padrão errors="raise" interrompe a operação em uma entrada inválida; o pandas 3 removeu errors="ignore".

Interprete arquivos e marcas temporais numéricas

pd.read_csv("meter.csv", parse_dates=["timestamp"], index_col="timestamp") solicita a interpretação de datas e horas e um índice temporal. Verifique os tipos de dados resultantes após o carregamento. Colunas de texto no pandas 3 usam o tipo str; versões anteriores normalmente mostram object.

Una strings separadas de data e hora com um espaço antes da interpretação. Colunas chamadas year, month e day podem ser reunidas diretamente com pd.to_datetime(df[["year", "month", "day"]]).

Para contagens Unix, especifique a unidade. pd.to_datetime(1735689600, unit="s", utc=True) fornece meia-noite UTC em 1º de janeiro de 2025. A contagem em milissegundos é 1735689600000 com unit="ms". Usar a unidade errada altera o momento interpretado.

Formate apenas para apresentação

parsed.dt.strftime("%d %b %Y") escreve textos como “15 Jan 2025”. O método .isoformat() de um Timestamp escreve uma string ISO. Nomes de meses e dias da semana seguem a configuração regional do sistema; os exemplos exibidos usam inglês. Mantenha datas e horas durante a análise e formate na exportação, pois strings deixam de permitir aritmética de datas.

Um índice temporal útil é interpretado, ordenado e verificado. Uma tabela pode conter vários eventos no mesmo momento, dias ausentes ou lotes fora de ordem. Cada condição altera o significado dos cálculos posteriores.

Construa rótulos de linha de data e hora

df["timestamp"] = pd.to_datetime(df["timestamp"], format="%Y-%m-%d %H:%M")
df = df.set_index("timestamp").sort_index()

set_index() move a coluna para os rótulos de linha; ele não interpreta texto. Inspecione df.index.dtype para verificar se é um tipo de data e hora e df.index.is_monotonic_increasing para verificar a ordem cronológica. Horários vizinhos iguais são permitidos em um índice crescente, então essa verificação não estabelece a unicidade.

Um DatetimeIndex permite seleção por data e reamostragem temporal. Rótulos de texto não se tornam um índice temporal apenas porque parecem datas. Você também pode deixar marcas temporais em uma coluna: df.resample("D", on="timestamp") usa essa coluna sem alterar o índice. Um PeriodIndex é outra representação de série temporal quando as linhas descrevem intervalos como meses.

Decida o significado de horários repetidos

df.index.is_unique informa se todos os rótulos são diferentes. df.index.duplicated() marca rótulos repetidos após o primeiro. Suponha que duas leituras, 3 e 5, compartilhem 1º de janeiro e uma leitura de 4 pertença a 2 de janeiro. Calcular a média das leituras duplicadas com df.groupby(level=0).mean() produz 4,0 em ambas as datas.

Essa operação é uma decisão sobre os dados. Se as linhas forem compras separadas, somar pode ser adequado. Se uma importação duplicou um registro, manter a última cópia com df[~df.index.duplicated(keep="last")] pode ser adequado. Não exclua transações válidas apenas para tornar um índice único. Operações que colocam um valor em cada rótulo de destino, incluindo reindex() e asfreq(), exigem rótulos de origem únicos.

Distinga frequência armazenada de inferida

Um índice criado por pd.date_range() normalmente contém .freq. Marcas temporais interpretadas frequentemente têm .freq igual a None, mesmo quando ocorrem em dias consecutivos. pd.infer_freq(df.index) examina pelo menos três marcas temporais e retorna um código como “D” ou “ME” se encontrar um padrão regular. Espaçamento irregular retorna None.

Metadados de frequência não são uma verificação de completude. Para procurar linhas diárias ausentes, construa o calendário esperado:

calendar = pd.date_range(df.index.min(), df.index.max(), freq="D")
missing = calendar.difference(df.index)

Um dia ausente não tem linha. Ele difere de uma linha presente que contém NaN. Um calendário limitado ao mínimo e ao máximo observados não pode revelar datas ausentes fora desse intervalo; use o início e o fim planejados do período de relatório quando forem conhecidos.

Prepare-se para operações posteriores

A ordenação torna as fatias previsíveis e é necessária para janelas móveis baseadas no tempo. Linhas ausentes importam mesmo quando um cálculo é bem-sucedido: shift(1) significa uma linha para trás, e rolling(7) significa sete linhas. Nenhum dos dois verifica se cada linha representa um dia. Em uma tabela no formato longo, mantenha também a chave da série, como sensor ou loja, para que operações posteriores possam ser executadas separadamente por série.

Quando o índice contém datas e horas ordenadas, strings de data se tornam seletores úteis. Sua precisão controla quanto tempo elas representam: um ano, um mês, um dia ou um minuto específico.

Selecione um período completo do calendário

Para dados diários de janeiro a março de 2025, ts.loc["2025"] seleciona todos os 90 dias. ts.loc["2025-02"] seleciona os 28 dias de fevereiro. Em dados horários, uma string de dia seleciona o dia inteiro, não apenas a meia-noite.

Use .loc também em um DataFrame:

february = df.loc["2025-02", "kwh"]
spring_onward = df.loc["2025-03-01":]

df["2025-02"] pede uma coluna com esse nome. A presença de um índice temporal não transforma a seleção de colunas por colchetes em seleção de linhas.

Interprete o extremo com precisão

Uma fatia por rótulos inclui ambos os extremos. ts.loc["2025-01-30":"2025-02-02"] inclui 30 e 31 de janeiro e 1º e 2 de fevereiro. Uma fatia por posições como ts.iloc[0:4] para antes da posição 4.

O fim de uma fatia por string parcial inclui todo o período nomeado. Em dados horários, df.loc[:"2025-06-01"] inclui todo o dia 1º de junho. df.loc[:"2025-06-01 00:00"] para à meia-noite. Da mesma forma, uma fatia terminada em “2025-02” inclui todo o mês de fevereiro. Escolher uma string mais precisa muda o limite, então escreva o ponto de corte conforme a pergunta.

ts.truncate(before="2025-03-01") mantém de 1º de março em diante. Seu argumento after= corta o outro extremo. Ordenar primeiro evita falhas que podem ocorrer quando fatias por strings de data encontram rótulos não ordenados.

Selecione condições recorrentes do calendário

Atributos do calendário produzem máscaras booleanas:

weekends = df[df.index.day_of_week >= 5]
evening_march = df[(df.index.month == 3) & (df.index.hour >= 18)]

Segunda-feira é 0, então sábado e domingo são 5 e 6. Cada condição precisa de parênteses quando combinada com & ou |. Com uma coluna de datas e horas, use df["timestamp"].dt.day_of_week em vez de um atributo do índice. A máscara de dia da semana seleciona um padrão recorrente do calendário; isso difere da seleção de um intervalo contínuo de datas.

Selecione uma janela de horário em cada data

df.between_time("09:00", "17:00") seleciona esses horários todos os dias. Ambos os extremos são incluídos por padrão, fornecendo nove linhas em um dia completo de dados horários. inclusive="left" inclui 09:00 e exclui 17:00, fornecendo oito. df.at_time("12:00") seleciona exatamente o meio-dia de cada dia.

Uma janela de horário pode atravessar a meia-noite. between_time("22:00", "06:00") seleciona linhas do fim da noite e do início da manhã ao longo do índice. Ela não seleciona um intervalo ininterrupto entre duas datas específicas. Em um índice com fuso horário, a seleção por string de data usa o fuso local do índice; converta o índice antes de selecionar um dia de relatório em outro fuso.

Uma variação precisa de um ponto de comparação claro. “Anterior” pode significar a linha observada anterior, o dia de calendário anterior ou o mesmo mês um ano antes. Escolha esse significado antes de calcular uma defasagem ou taxa de crescimento.

Coloque valores anteriores ao lado dos atuais

Para contagens de visitantes 200, 210 e 189 de 3 a 5 de março, s.shift(1) fornece NaN, 200 e 210. Ele move os valores uma linha para baixo e mantém os rótulos. A nova primeira posição fica ausente porque não existe observação anterior. shift(-1) fornece 210, 189 e NaN: uma antecipação que traz o próximo valor para a linha atual.

df["previous"] = df["visitors"].shift(1)
df["change"] = df["visitors"].diff()
df["growth"] = df["visitors"].pct_change()

diff() subtrai o valor anterior, fornecendo NaN, 10 e −21. pct_change() divide o valor atual pelo anterior e subtrai 1, fornecendo NaN, 0,05 e −0,10. São frações: 0,05 significa 5%, não 0,05%. A saída em ponto flutuante pode ter pequenos dígitos extras; arredonde para exibição após calcular.

Escolha a defasagem em linhas ou em tempo

pct_change(7) compara com sete linhas antes. Isso corresponde ao mesmo dia da semana anterior somente quando há exatamente uma linha por dia, sem lacunas. Em uma série mensal completa, pct_change(12) fornece a variação em relação ao ano anterior.

shift(1, freq="D") desloca as marcas temporais um dia para a frente e mantém os valores associados a esses rótulos deslocados. Ele mantém todos os valores. A aritmética com a original então alinha por data:

previous_day = s.shift(1, freq="D")
daily_change = s - previous_day

Se a origem tiver observações apenas na segunda e na quinta-feira, um shift(1) simples compara quinta-feira com segunda-feira. Um deslocamento de data permite comparar com quarta-feira; se quarta-feira estiver ausente, a variação diária de quinta-feira fica ausente. Preencher essa lacuna é uma decisão separada sobre os dados.

Espere que a aritmética alinhe os rótulos

Duas Series se combinam por marca temporal, não por posição da linha. Some os valores 200, 210 e 189 em 3, 4 e 5 de março aos valores 1 e 1 em 4 e 7 de março. Apenas 4 de março tem duas observações, então sua soma é 211. A união das datas é 3, 4, 5 e 7 de março; os outros resultados estão ausentes.

Use s.add(other, fill_value=0) quando uma observação ausente realmente significar zero, como em uma contagem de eventos verificada. Isso não é uma correção geral para leituras ausentes de sensores.

Reinicie as comparações por série

Ordene uma tabela no formato longo pela chave da série e pela data e, depois, calcule dentro dos grupos. df.groupby("store")["sales"].pct_change() compara cada loja apenas com ela mesma. Para a loja A vendendo 100 e depois 110 e a loja B vendendo 50 e depois 40, as taxas de crescimento são ausente, 0,10, ausente e −0,20. Um cálculo simples em toda a coluna compararia a primeira venda de B com a última venda de A. Esse resultado numérico descreveria uma troca de lojas, não crescimento ao longo do tempo.

Uma sequência regular de datas é um calendário que você pode gerar em vez de digitar cada rótulo. Ela pode rotular dados de teste, definir uma grade esperada para relatórios ou revelar observações ausentes após a reindexação.

Especifique um início e uma regra

ends = pd.date_range("2025-01-01", periods=4, freq="ME")

As quatro marcas temporais são 31 de janeiro, 28 de fevereiro, 31 de março e 30 de abril. “ME” significa fim do mês, então a primeira data é o primeiro fim de mês igual ou posterior ao início. Uma frequência regular pode seguir uma regra de calendário mesmo quando os intervalos de tempo decorrido têm durações diferentes.

Normalmente, informe dois entre start, end e periods, além de freq. Sem uma frequência explícita, o padrão é um dia de calendário. periods é uma contagem de marcas temporais, não de intervalos entre elas: quatro marcas temporais horárias contêm três intervalos.

Interprete códigos comuns

Múltiplos expressam intervalos mais amplos: “15min”, “2h” e “90min”. Começar às 08:00 com quatro períodos de “90min” fornece 08:00, 09:30, 11:00 e 12:30. “1h30min” expressa o mesmo espaçamento.

As frequências de marcas temporais do pandas 3 usam “ME”, “QE”, “YE”, “BME”, “h”, “min”, “s”, “ms” e “us”. Os códigos antigos “M”, “Q”, “Y” ou “A”, “BM”, “H”, “T”, “S”, “L” e “U” não funcionam mais nessas operações com marcas temporais. Períodos mensais ainda usam “M” porque um período descreve um intervalo.

Siga âncoras e dias úteis

Uma sequência ancorada não força o início informado a aparecer na saída. Começar em 15 de janeiro de 2025 com freq="MS" fornece 1º de fevereiro primeiro. Em janeiro de 2025, “W-MON” fornece 6, 13, 20 e 27 de janeiro; “W” simples fornece domingos. “WOM-3FRI” significa a terceira sexta-feira de cada mês.

“B” pula fins de semana, mas não conhece feriados locais. Março de 2025 contém 21 datas de segunda a sexta-feira. Um calendário personalizado pode excluir um feriado informado:

pd.bdate_range("2025-03-01", "2025-03-31",
               freq="C", holidays=["2025-03-17"])

Essa sequência contém 20 datas. A lista de feriados é explícita; um país não é inferido a partir de um fuso horário ou idioma.

Conte os extremos com cuidado

Os pontos de início e fim que coincidem com a frequência são incluídos por padrão. Uma sequência horária da meia-noite de 1º de janeiro até a meia-noite de 2 de janeiro fornece 25 marcas temporais. Use periods=24 para exatamente 24 leituras horárias, ou inclusive="left" para excluir o fim. normalize=True redefine os horários de início e fim para a meia-noite. Adicione tz="Asia/Tokyo" quando os rótulos gerados precisarem conter um fuso.

“Um mês depois” é uma instrução de calendário. “Trinta dias depois” é tempo decorrido. Os resultados podem ser diferentes porque meses e anos não têm todos o mesmo número de dias.

Separe duração de deslocamento no calendário

Um Timedelta adiciona uma quantidade fixa de tempo decorrido. Um DateOffset segue componentes do calendário. A partir de 31 de janeiro de 2025:

t = pd.Timestamp("2025-01-31")
t + pd.DateOffset(months=1)   # February 28
t + pd.Timedelta(days=30)    # March 2

Para o DateOffset, primeiro avance para fevereiro e depois mantenha o dia 31 se ele existir. Como não existe, o pandas ajusta para o último dia válido de fevereiro. A partir de 31 de janeiro de 2024, o resultado é 29 de fevereiro porque é um ano bissexto. pd.Timedelta(months=1) é inválido: um mês não tem uma única duração fixa.

A mesma distinção se aplica a anos. A partir de 1º de janeiro de 2024, 365 dias decorridos terminam em 31 de dezembro de 2024. pd.DateOffset(years=1) termina em 1º de janeiro de 2025. Use a unidade indicada pela pergunta real em vez de substituí-la por um número conveniente de dias.

Desloque para uma âncora de calendário

pd.offsets.MonthEnd(1) desloca para o próximo fim de mês. Começando em 15 de janeiro de 2025, fornece 31 de janeiro. Começando em 31 de janeiro, fornece 28 de fevereiro. A contagem de um significa avançar para uma âncora, então uma data que já corresponde também se desloca.

MonthEnd(0) desloca uma data para a frente até o fim de seu mês atual, mas mantém inalterada uma data que já é fim de mês. É útil para rotular cada observação pelo fim de seu mês:

month_labels = df.index + pd.offsets.MonthEnd(0)

Um deslocamento também tem rollforward() e rollback(). Para 15 de janeiro, a âncora de MonthEnd mais próxima à frente é 31 de janeiro e a mais próxima atrás é 31 de dezembro de 2024. Essas operações selecionam a âncora válida mais próxima em uma direção.

Avance por dias úteis

14 de março de 2025 é sexta-feira. Somar pd.offsets.BDay(1) fornece segunda-feira, 17 de março. Somar um dia decorrido fornece sábado, 15 de março. Uma regra padrão de dias úteis pula fins de semana; para feriados, é necessário fornecer explicitamente um calendário personalizado.

Strings de frequência são nomes curtos para objetos de deslocamento: “ME” corresponde a MonthEnd, “B” a BusinessDay e “W-MON” a uma semana ancorada na segunda-feira. Isso permite que o mesmo significado de calendário determine uma sequência, uma regra de reamostragem ou um deslocamento de data.

Mantenha o horário desejado durante o horário de verão

No pandas 3, pd.offsets.Day(1) significa um dia de calendário e mantém o horário do relógio local. pd.Timedelta(days=1) adiciona exatamente 24 horas. A partir do meio-dia de 29 de março de 2025 em Amsterdã, o deslocamento de calendário termina ao meio-dia de 30 de março, após apenas 23 horas decorridas. O Timedelta termina às 13:00. Um compromisso local recorrente e um tempo de funcionamento medido de um equipamento precisam, portanto, de operações diferentes.

Um total mensal de vendas pertence a um mês inteiro. É possível rotulá-lo com uma marca temporal, mas um Period declara seu intervalo diretamente. Um período combina um valor com uma frequência, então “2025-03” com frequência “M” significa todo o mês de março de 2025.

Represente e desloque intervalos

march = pd.Period("2025-03", freq="M")
months = pd.period_range("2025-01", "2025-04", freq="M")

months é um PeriodIndex de quatro itens com tipo de dados period[M]. O start_time de março é 1º de março à meia-noite; seu end_time é 31 de março às 23:59:59,999999 na resolução de microssegundos. Um fim é o último momento, não a meia-noite no início do último dia.

A aritmética de períodos se desloca na própria unidade do período. march + 1 é abril de 2025. Junho menos março na frequência mensal fornece um deslocamento de três fins de mês, cujo .n é 3. Um período mensal também conhece .days_in_month: fevereiro de 2025 tem 28 dias.

Converta momentos em intervalos e vice-versa

monthly_labels = df.index.to_period("M")
column_labels = df["date"].dt.to_period("M")
start_labels = monthly_labels.to_timestamp()
end_labels = monthly_labels.to_timestamp(how="end")

Toda marca temporal em março é associada ao mesmo período mensal. Converter esse período de volta fornece seu início por padrão ou seu fim quando solicitado. Isso não recupera o dia e o horário originais de uma observação: a conversão para período descartou esse detalhe.

Mantenha separadas as famílias de códigos. Um intervalo mensal usa “M” em Period e period_range. Uma marca temporal de fim de mês usa “ME” em date_range e na reamostragem de datas e horas. Os dois nomes descrevem tipos diferentes de rótulos.

Altere a frequência de um período

O método .asfreq() de um período seleciona um período que o contém ou está contido nele em outra frequência. march.asfreq("D", how="start") fornece 1º de março como período diário; how="end" fornece 31 de março. Um período anual convertido para “M” com how="start" fornece janeiro.

Isso seleciona um período de limite; não distribui um total mensal entre os dias. Para uma série com PeriodIndex, a reamostragem pode agregar intervalos mensais em intervalos trimestrais. As contagens dos dias de cada mês de 2025 somam totais trimestrais de 90, 91, 92 e 92.

Interprete rótulos de trimestres fiscais

Um trimestre fiscal é nomeado dentro de um ano fiscal cujo mês de término é explícito. Com “Q-JUN”, o ano fiscal de 2025 termina em junho de 2025. Seu primeiro trimestre, portanto, vai de julho a setembro de 2024:

q = pd.Period("2025Q1", freq="Q-JUN")

Com “Q-MAR”, 10 de maio de 2025 está em 2026Q1 porque esse ano fiscal termina em março de 2026. O ano em um rótulo fiscal não precisa corresponder ao ano do calendário de seu primeiro dia. Para filtros de marcas temporais, selecionar horários anteriores ao início do próximo período costuma ser mais claro do que construir a última fração de segundo do período atual.

A reamostragem temporal responde a perguntas como “Quanta energia foi usada a cada dia?” ou “Qual foi a temperatura média em cada mês?”. Ela agrupa observações em intervalos de tempo e depois aplica uma agregação.

Escolha uma estatística adequada à quantidade

daily = df.resample("D").agg({"kwh": "sum", "temp_c": "mean"})

Energia em kWh e chuva em mm se somam ao longo do tempo. Temperatura é um nível, então uma média a descreve de forma mais útil que uma soma. last() é adequado para um saldo de fechamento, enquanto max() encontra um máximo. Vendas diárias podem ser somadas para obter o total mensal ou ter sua média calculada para obter a venda média por dia observado; a pergunta decide.

resample() retorna um Resampler até que você chame uma agregação como sum(), mean(), count() ou agg(). Use on="date" quando as datas e horas estiverem em uma coluna em vez do índice.

Interprete intervalos do calendário e cobertura parcial

Uma série diária de valores iguais a um de 1º de janeiro a 30 de abril de 2025 fornece totais mensais de 31, 28, 31 e 30 com resample("ME").sum(). “MS” fornece os mesmos totais mensais com rótulos de início. A reamostragem por fim de trimestre fornece 90 para janeiro a março e 30 para um segundo trimestre que contém apenas abril. Um rótulo de 30 de junho não comprova que maio e junho foram observados.

Os intervalos semanais “W” terminam no domingo. Valores diários de 1 a 14 a partir de segunda-feira, 3 de março, somam 28 para a semana rotulada com 9 de março e 77 para a semana rotulada com 16 de março. “W-MON” termina na segunda-feira; o primeiro intervalo contém então apenas 3 de março. Verifique o dia da semana da âncora antes de tratar um rótulo como o início de uma semana.

Separe pertencimento de rotulagem

closed controla qual limite pertence a um intervalo. label controla a marca temporal exibida no resultado. Para a maioria das regras, incluindo “5min”, “h”, “D” e “MS”, ambos são “left” por padrão.

Valores de 0 a 9, um por minuto a partir de 00:00, produzem duas somas padrão de cinco minutos: 10 rotulado como 00:00 e 35 rotulado como 00:05. O primeiro intervalo contém de 00:00 a 00:04. Com closed="right", label="right", os resultados são 0 em 00:00, 15 em 00:05 e 30 em 00:10. O intervalo do meio contém de 00:01 a 00:05. Alterar apenas o rótulo não alteraria o pertencimento.

Regras de fim como “ME”, “QE”, “YE”, “W” e “BME” usam fechamento e rótulos à direita por padrão. Intervalos fixos normalmente se alinham a partir da meia-noite do primeiro dia, então limites de 15 minutos são 00:00, 00:15 e assim por diante.

Distinga intervalos vazios de zeros reais

O sum() de um dia vazio é 0, count() é 0 e mean() é NaN. Use sum(min_count=1) para preservar a ausência quando não houver leitura disponível. Assim, um zero registrado e uma leitura ausente continuam distinguíveis.

Para vários resumos de uma série, .ohlc() fornece abertura, máxima, mínima e fechamento: o primeiro, o maior, o menor e o último valor observado em cada intervalo. Leituras 10, 12 e 11 fornecem abertura 10, máxima 12, mínima 10 e fechamento 11. A abertura e o fechamento dependem da ordem temporal, não do tamanho numérico.

Uma grade mais fina cria posições, não medições. Antes de preenchê-las, decida se cada valor representa um estado, uma contagem, uma medição que varia suavemente ou um total em um intervalo.

Revele as novas posições

s = pd.Series([10.0, 16.0],
              index=pd.to_datetime(["2025-06-01", "2025-06-04"]))
daily = s.asfreq("D")

O resultado diário é 10, NaN, NaN, 16. Aqui, s.resample("D").asfreq() fornece a mesma grade. Os valores são mantidos nas marcas temporais correspondentes; as novas datas não contêm observações originais.

Preencha conforme o significado

Uma configuração de termostato permanece até alguém alterá-la, então o preenchimento com o último valor válido é útil. Um nível de água que varia suavemente pode justificar a interpolação. Zero é adequado a uma contagem de eventos somente quando o registro ausente significa que não houve evento. Uma falha do sensor não comprova uma medição igual a zero.

O exemplo de interpolação usa uma grade diária regular. A variação total é 6 em três passos de um dia, então cada passo adiciona 2. Os dois valores intermediários são estimativas, não medições recuperadas.

O preenchimento com o próximo valor válido usa informações futuras. Ele não pode descrever o que um observador sabia em cada momento anterior. O preenchimento com o último valor válido respeita essa direção temporal, mas lacunas longas ainda podem tornar desatualizado um estado propagado. daily.ffill(limit=1) preenche uma posição após uma leitura, fornecendo 10, 10, NaN, 16 neste exemplo.

Use limites explícitos para o relatório

asfreq("D") abrange da primeira à última marca temporal de origem. Reindexe quando o calendário precisar ir além:

calendar = pd.date_range("2025-06-01", "2025-06-05", freq="D")
complete = s.reindex(calendar)

Agora 5 de junho também está visível. fill_value=0 na reindexação preenche rótulos recém-criados, o que é útil para dias confirmados sem eventos. Ele não substitui valores ausentes que já existiam na origem. Tanto a reindexação quanto asfreq() precisam de rótulos de origem únicos.

Separe amostragem de agregação

asfreq() seleciona valores nas marcas temporais de destino. Ele não resume as observações entre elas. Em 48 valores horários numerados de 0 a 47, asfreq("D") seleciona as leituras da meia-noite 0 e 24. resample("D").sum() fornece 276 e 852 ao somar todos os valores horários de cada dia.

Um total mensal não pode ser propagado para todos os dias e depois somado: isso contaria o mesmo total repetidamente. Uma alocação diária igual exige dividir pelo número de dias do mês. Essa é uma hipótese de alocação, diferente de propagar um estado ou estimar uma medição que varia suavemente.

Uma tabela no formato longo pode conter muitas séries em uma única coluna de valores. Uma chave de loja distingue lojas, e uma chave de sensor distingue sensores. Agrupe por essa identidade e pelo tempo quando a pergunta exigir um histórico separado para cada série.

Combine uma chave de série com uma regra temporal

monthly = df.groupby([
    "store", pd.Grouper(key="date", freq="ME")
])["sales"].sum()

pd.Grouper coloca uma regra de intervalos de agrupamento temporal dentro de groupby. key= nomeia uma coluna de datas e horas; level= pode nomear um nível de índice de datas e horas. O resultado tem um nível de índice para loja e outro para fim de mês. Selecionar a coluna numérica mantém a agregação focada nas vendas.

Suponha que a loja A venda 100 em 5 de janeiro, 150 em 20 de janeiro e 120 em 3 de fevereiro. A loja B vende 80 em 11 de janeiro, 90 em 14 de fevereiro e 60 em 25 de fevereiro. O resultado agrupado é A: janeiro 250, fevereiro 120; B: janeiro 80, fevereiro 150. Reamostrar a tabela inteira sem a chave de loja combinaria as lojas em janeiro 330 e fevereiro 270.

Reamostre dentro de cada grupo

Uma segunda forma transforma primeiro a data no índice:

monthly = (df.set_index("date")
             .groupby("store")["sales"]
             .resample("ME").sum())

Ela produz os mesmos totais para combinações observadas de loja e mês. As duas formas diferem quando uma loja não tem linhas em um mês intermediário. Se A aparecer apenas em janeiro e março, a reamostragem por grupo cria um intervalo de fevereiro entre a primeira e a última data de A; sum() comum fornece zero ali. Agrupar por loja e por um Grouper mantém as combinações que contêm linhas, então a combinação de fevereiro de A fica ausente.

Uma combinação ausente, um intervalo vazio resumido como zero e uma medição ausente são estados de dados diferentes. Decida qual deles o relatório deve mostrar. Use reindexação explícita quando todas as lojas precisarem compartilhar um calendário mais amplo que seu intervalo observado. Use min_count=1 com uma soma quando um intervalo vazio deve permanecer ausente.

Remodele para comparação

monthly.unstack("store") move o nível de loja para colunas e deixa os meses nas linhas. No exemplo, janeiro tem A = 250 e B = 80; fevereiro tem A = 120 e B = 150. Uma combinação ausente de loja e mês se torna NaN; unstack("store", fill_value=0) substitui combinações ausentes por zero quando esse significado é adequado.

Mantenha anos separados quando necessário

Um Grouper temporal com “ME” mantém janeiro de 2024 e janeiro de 2025 separados. Agrupar por df["date"].dt.month mantém apenas os números dos meses e reúne os dois janeiros. A primeira forma responde “O que aconteceu a cada mês?”. A segunda permite uma comparação sazonal, como a média de vendas de janeiro ao longo dos anos. A escolha depende da identidade temporal que você precisa preservar.

Uma janela móvel resume repetidamente um grupo móvel de linhas. A cada nova linha, a janela ganha o valor atual e, em algum momento, descarta o mais antigo. O comprimento da janela controla quanto da variação de curto prazo é suavizado.

Examine uma janela por vez

Para os valores 4, 8, 6, 10 e 12:

s = pd.Series([4, 8, 6, 10, 12])
s.rolling(3).mean()

A primeira janela completa é [4, 8, 6], com total 18 e média 6. A próxima é [8, 6, 10], com média 8. A última é [6, 10, 12], com média de aproximadamente 9,333. Os resultados padrão são NaN, NaN, 6, 8 e 9,333 porque as duas primeiras linhas ainda não têm três observações.

Controle os requisitos de dados e o posicionamento

min_periods define a contagem necessária de valores não ausentes. Para uma janela por contagem de linhas, o padrão é o tamanho completo da janela. Com min_periods=1, as primeiras médias usam um valor e depois dois: 4 e 6. Suas amostras menores as tornam menos estáveis que as médias posteriores de três valores.

Valores ausentes ainda ocupam posições de linha. Em [4, NaN, 6, 10, 12], uma janela de três linhas que contém o valor ausente tem apenas duas observações válidas. min_periods=2 permite a média de [4, NaN, 6], que é 5; o padrão não permite.

Os resultados normalmente pertencem à última linha da janela. Com center=True, as mesmas três médias de janelas completas aparecem nas linhas do meio, fornecendo NaN, 6, 8, 9,333, NaN. Um valor centralizado usa observações posteriores em relação ao seu rótulo. Use janelas com término na observação atual para descrever o que era conhecido em cada momento.

Resuma mais do que a média

As mesmas janelas permitem sum(), max(), min() e std(). O pandas usa o desvio padrão amostral por padrão: [4, 8, 6] tem desvio padrão 2. Uma função personalizada pode calcular uma amplitude:

s.rolling(3).apply(lambda v: v.max() - v.min(), raw=True)

As amplitudes das janelas completas são 4, 4 e 6. raw=True passa valores de array para a função. Duas séries alinhadas também podem compartilhar uma janela: a.rolling(3).corr(b) mede a correlação entre as últimas três observações pareadas, de modo que a relação pode variar ao longo do tempo.

Escolha um comprimento e um agrupamento significativos

Com uma linha diária completa por dia, uma média de sete linhas contém cada dia da semana uma vez e elimina pela média um componente semanal fixo e repetitivo. Uma média de doze linhas faz o mesmo para um componente anual fixo em dados mensais completos. Janelas mais longas suavizam mais, mas respondem mais tarde a mudanças de direção; uma média de n linhas com término na observação atual tem aproximadamente meia janela de atraso, cerca de (n − 1) / 2 linhas.

Linhas não são dias. Sete leituras com lacunas podem cobrir mais de uma semana. Use uma janela de tempo quando a pergunta indicar tempo decorrido. Em uma tabela no formato longo, ordene cada série no tempo e execute janelas dentro de seu grupo: df.groupby("store")["sales"].rolling(2).sum(). Isso impede que uma janela passe dos dados de uma loja para os de outra.

Eventos irregulares pedem janelas definidas pelo tempo. “Pedidos nos últimos três dias” deve manter a mesma duração mesmo quando há muitos pedidos em um dia e nenhum no dia seguinte.

Defina uma janela de tempo decorrido

s = pd.Series([5, 3, 4, 6], index=pd.to_datetime([
    "2025-05-01", "2025-05-02", "2025-05-05", "2025-05-06"
]))
s.rolling("3D").sum()

Os resultados são 5, 8, 4 e 10. Ao contrário de rolling(3), a string “3D” define um intervalo de três dias. O número de linhas dentro desse intervalo pode variar. Ordene o DatetimeIndex primeiro; janelas de tempo exigem horários em ordem monotônica. Um DataFrame pode usar uma coluna ordenada de datas e horas com on="date".

Verifique o limite antes de somar

Por padrão, a janela inclui o horário atual e exclui o instante exatamente três dias antes. À meia-noite de 5 de maio, o intervalo vai de depois da meia-noite de 2 de maio até a meia-noite de 5 de maio. A leitura de 2 de maio está exatamente no limite excluído, então apenas o valor 4 de 5 de maio contribui.

Em 6 de maio, a janela começa logo após 3 de maio e inclui os valores 4 e 6, totalizando 10. Com closed="both", a janela de 5 de maio também inclui 2 de maio e totaliza 7. A escolha de um limite pode alterar um resultado mesmo quando os dados e a duração permanecem os mesmos.

Uma janela de duas linhas nessa série fornece NaN, 8, 7 e 10. Em 5 de maio, ela inclui a linha anterior de 2 de maio. Isso responde a “as últimas duas leituras”, uma pergunta diferente de “os últimos três dias”.

Defina uma exigência de dados

O min_periods de uma janela de tempo é 1 por padrão. A primeira observação pode, portanto, produzir um resultado imediatamente. s.rolling("3D").count() fornece 1, 2, 1 e 2 leituras, revelando a variação na quantidade de dados que sustenta o resultado. Uma média baseada em uma leitura e uma média baseada em muitas são cálculos válidos, mas têm sustentações diferentes nos dados.

Com min_periods=2, as somas são NaN, 8, NaN, 10. A duração não mudou; o cálculo agora exige pelo menos duas observações não ausentes dentro dessa duração. Um intervalo de tempo mais amplo não garante, por si só, mais observações.

Use durações fixas e separe séries

Janelas móveis baseadas no tempo exigem uma duração fixa como “30min”, “24h” ou “7D”. Uma regra de fim de mês como “1ME” tem duração variável e não pode definir esse tipo de janela móvel. Use uma duração fixa declarada como “30D” se essa for a regra desejada, ou primeiro agregue em intervalos mensais quando a pergunta tratar de meses do calendário.

Para históricos separados de clientes, df.groupby("customer").rolling("30D", on="date")["amount"].sum() mantém juntas as transações de cada cliente. Os horários devem estar ordenados dentro de cada cliente. O resultado adiciona a chave do grupo como nível do índice, preservando qual série cada janela descreve.

Algumas perguntas precisam de todo o histórico: “Quanto foi acumulado?” ou “Qual é o maior valor até agora?”. Outras devem favorecer observações recentes sem descartar abruptamente o passado. Cálculos expansivos e exponencialmente ponderados atendem a esses objetivos diferentes.

Aumente o histórico uma linha por vez

Para os valores 4, 8, 6, 10 e 12, s.expanding().mean() fornece 4, 6, 6, 7 e 8. O quarto resultado usa os quatro valores: seu total é 28 e sua média é 7. expanding().sum() fornece 4, 12, 18, 28 e 40, igual a cumsum() nessa série completa. expanding().max() fornece 4, 8, 8, 10 e 12, igual a cummax().

Janelas expansivas exigem uma observação por padrão. Elas mantêm todas as observações anteriores com peso igual. Perto do fim de uma série longa, um novo valor contribui com apenas uma pequena parte de todo esse histórico, então uma média acumulada reage lentamente.

Totais acumulados podem recomeçar em um limite:

ytd = df.groupby(df.index.year)["sales"].cumsum()
by_store = df.groupby("store")["sales"].cumsum()

Ordene dentro do histórico relevante antes de acumular. Uma soma acumulada simples sobre lojas intercaladas as mistura.

Meça a distância abaixo de um máximo acumulado

Para 100, 120, 90, 110 e 130, cummax() fornece 100, 120, 120, 120 e 130. Calcule a queda em relação ao máximo acumulado com s / s.cummax() - 1. Em 90, a referência é o máximo anterior de 120, então a queda é −0,25, ou 25% abaixo do máximo. Comparar 90 com o primeiro valor de 100 responderia a uma pergunta diferente. Um novo máximo tem queda zero.

Dê mais peso aos valores recentes

Uma média móvel exponencialmente ponderada, ou EWMA, reduz o peso dos valores mais antigos por um fator constante. O fator de suavização segue $\alpha =2\mathrm{/}(\text{span}+1)$, então span=3 fornece 0,5. Para adjust=False, a atualização é:

Aqui, $x_t$ é a nova observação, $y_{t-1}$ é o valor suavizado anterior e $y_t$ é o resultado atualizado. O primeiro valor suavizado é igual à primeira observação. Depois, cada novo valor recebe peso 0,5 e o valor suavizado anterior recebe peso 0,5:

s.ewm(span=3, adjust=False).mean()

Para 4, 8, 6, 10 e 12, os resultados são 4, 6, 6, 8 e 10. A atualização final calcula a média da nova observação 12 e do valor suavizado anterior 8. Ela não calcula a média apenas das duas observações brutas mais recentes.

Interprete a configuração de ajuste

O padrão adjust=True normaliza pela soma dos pesos disponíveis. Para os mesmos dados, os primeiros resultados são 4, aproximadamente 6,667, 6,286, 8,267 e 10,194. Esse cálculo inicial é diferente da forma recursiva; a diferença diminui conforme mais histórico fica disponível.

Escolha um argumento de decaimento: span, alpha, com ou halflife. Uma EWMA não tem um ponto de corte abrupto em que uma linha antiga desaparece de repente. Uma média móvel tem esse ponto de corte, enquanto uma média expansiva mantém todos os valores anteriores com peso igual. Escolha conforme a influência que mudanças recentes devem ter.

Uma leitura de relógio precisa de uma localização para identificar um momento. “2025-07-01 09:00” é uma marca temporal sem fuso horário. Adicionar “Europe/Amsterdam” faz com que ela tenha fuso horário: em julho, seu deslocamento é +02:00 e ela representa 07:00 UTC. UTC é a referência de tempo compartilhada e não tem mudanças de relógio por horário de verão.

Atribua o fuso do registro

local = pd.Timestamp("2025-07-01 09:00")
aware = local.tz_localize("Europe/Amsterdam")

tz_localize() mantém 09:00 e atribui a esse horário o significado do fuso. Use o local onde a leitura do relógio foi registrada. Chamar a mesma leitura de UTC descreveria um momento diferente, duas horas depois neste exemplo.

Use nomes da IANA como “Europe/Amsterdam”, “America/New_York” e “Asia/Kolkata”. Fusos regionais nomeados mantêm regras históricas de deslocamento e horário de verão. Um deslocamento fixo de +01:00 não mantém. Nomes curtos são inconsistentes: “EST” é fixo em −05:00, enquanto “CET” segue mudanças sazonais. O pandas 3 usa a representação zoneinfo do Python.

Converta um momento já identificado

aware.tz_convert("UTC") fornece 07:00 UTC. Converter esse mesmo instante para Nova York fornece 03:00, para Calcutá 12:30, para Tóquio 16:00 e para Sydney 17:00 em 1º de julho. O horário do relógio muda, mas o momento continua o mesmo.

Converter um valor sem fuso gera um erro porque não se conhece o fuso inicial. Atribuir um fuso a um valor que já tem fuso também gera um erro; use conversão nessa operação. Em colunas, use .dt.tz_localize() e .dt.tz_convert(). Em índices, use os métodos diretamente ou os métodos do DataFrame voltados ao índice.

Leia texto com deslocamento e combine fusos

Um “Z” no final de um texto ISO significa UTC. Para texto com deslocamentos diferentes, interprete com utc=True:

raw = pd.Series(["2025-03-01 10:00+01:00",
                 "2025-04-01 10:00+02:00"])
common = pd.to_datetime(raw, utc=True)

Esses valores se tornam 09:00 e 08:00 UTC. Depois, converta para um fuso regional para relatórios locais. A interpretação de deslocamentos mistos sem utc=True gera um erro no pandas 3.

Duas séries com fuso se alinham pelos momentos reais mesmo quando seus rótulos de fuso diferem. Leituras de Amsterdã às 09:00 e 10:00 e de Londres às 08:00 e 09:00 em julho se referem a instantes correspondentes. O resultado de sua aritmética usa rótulos UTC. Comparações de ordem entre marcas temporais sem e com fuso falham; a igualdade retorna falso.

Remova um fuso de forma deliberada

tz_convert(None) primeiro expressa um valor com fuso em UTC e depois remove o fuso. As 09:00 de Amsterdã se tornam 07:00 sem fuso em julho. tz_localize(None) remove o fuso e mantém 09:00 sem fuso. Essas saídas são diferentes. Mantenha os dados de cálculo com fuso em UTC e depois converta antes de apresentar resultados ou agrupar por dia local.

Relógios locais podem pular ou repetir uma hora. Essas mudanças afetam a interpretação, as durações decorridas e os totais diários. Fusos horários nomeados permitem que o pandas distinga os momentos reais por trás das leituras de relógio local.

Reconheça um horário local pulado

Amsterdã avançou de 02:00 para 03:00 em 30 de março de 2025. A leitura de relógio 02:30 nunca ocorreu. Atribuir-lhe um fuso sem uma política gera um erro:

pd.Timestamp("2025-03-30 02:30").tz_localize(
    "Europe/Amsterdam", nonexistent="shift_forward"
)

O resultado é 03:00+02:00, o primeiro horário válido após a lacuna. nonexistent="NaT" preserva o problema como ausente. "shift_backward" desloca para o último momento válido antes da lacuna. Deslocar um registro altera sua marca temporal, então mantenha a entrada original e documente a política escolhida na análise.

Distinga duas leituras repetidas

Em 26 de outubro de 2025, Amsterdã voltou de 03:00 para 02:00. A leitura local 02:30 ocorreu uma vez com deslocamento +02:00 e uma vez com +01:00. Elas estão separadas por uma hora em UTC.

ambiguous=True seleciona a ocorrência no horário de verão; ambiguous=False seleciona o horário padrão. ambiguous="NaT" marca uma leitura não resolvida como ausente. Uma lista booleana pode escolher por linha. ambiguous="infer" pode usar uma sequência ordenada que contenha a hora repetida, como 01:30, 02:00, 02:30, 02:00, 02:30, 03:00. Uma leitura isolada de relógio em horário repetido não fornece evidência de ordenação suficiente para inferir qual ocorrência era pretendida.

Conte as horas do dia local

O dia da mudança na primavera tem 23 horas e o dia da mudança no outono tem 25. Uma série horária completa reamostrada por dias locais tem, portanto, contagens variáveis. Para informar a energia horária média, divida uma soma diária pelo número real de leituras horárias válidas ou calcule sua média. Dividir todo total por 24 representa incorretamente os dias de mudança.

Um conjunto de dados parcial também pode criar intervalos curtos. Uma série em UTC que começa em 29 de março às 00:00 começa em Amsterdã às 01:00, então falta a meia-noite em seu primeiro dia local, mesmo antes do dia da mudança. Verifique os limites do relatório e as regras do fuso.

Distinga mesmo horário de tempo decorrido igual

t = pd.Timestamp("2025-03-29 12:00", tz="Europe/Amsterdam")
t + pd.offsets.Day(1)       # March 30 at 12:00
t + pd.Timedelta(days=1)    # March 30 at 13:00

O deslocamento de calendário preserva o meio-dia e atravessa apenas 23 horas decorridas. O Timedelta adiciona 24 horas. No outono, um dia de calendário local pode conter 25 horas decorridas.

Escolha o fuso do relatório antes de agrupar

A reamostragem segue o fuso do índice. Para totalizar o consumo pela data local de Amsterdã, primeiro converta um índice UTC com fuso para “Europe/Amsterdam” e depois reamostre para “D”. Reamostrar primeiro em UTC cria limites de dia diferentes que não podem ser corrigidos apenas pela alteração dos rótulos do resultado.

As datas de mudança variam por região: Nova York mudou em 9 de março e 2 de novembro em 2025; Sydney terminou o horário de verão em 6 de abril e o iniciou em 5 de outubro. Tóquio e Calcutá não têm mudanças de horário de verão. Mantenha momentos brutos em UTC e use o fuso local nomeado para relatórios de calendário.