Adicionar variáveis de calendário e de defasagem

Cerca de 31 minutos min de leitura, com 2 exemplos em 8 seções.

Edição 2026.11.11 Exemplos aprovados em 20 de nov de 2026 41 de 41 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.11. Leia o original

Depois deste capítulo, você poderá transformar o histórico horário de um cliente em uma tabela de variáveis, adicionar defasagens e variáveis de calendário e de feriado que uma previsão do dia seguinte tem permissão para usar, medir o que cada variável acrescenta nas mesmas janelas e identificar uma defasagem que lê o dia que está sendo previsto.

Os modelos estatísticos do Capítulo 4 veem apenas uma série. Eles conhecem o seu nível e o seu ritmo diário, e nada além disso: não sabem que 25 de dezembro de 2014 foi feriado público, que uma segunda-feira difere de um domingo, ou que a demanda acompanha a estação do ano. O Capítulo 1 mostrou o que isso custa. A sua linha de base sazonal ingênua teve o pior dia em 26 de dezembro, o dia após o Natal, porque copiou para frente as leituras do feriado. Um modelo de gradient boosting pode receber esses fatos como colunas e, como o fornecedor compra antes de o dia começar, somente as colunas conhecidas no momento de corte podem entrar na sua previsão. Este capítulo acrescenta colunas de calendário e de feriado para o subconjunto de oito clientes e verifica cada uma antes de contá-la. A variável de feriado não corrige a falha de 26 de dezembro, porque 26 de dezembro não é feriado. A variável que corrigiria isso, uma marcação de dia após feriado, também é conhecida com antecedência, mas este capítulo não a constrói, e os seus cortes padrão não pontuam um feriado.

Esta parte ainda não foi traduzida, por isso está em inglês.

Turn history into features

Última alteração na edição 2026.11.11

The table comes first, because every feature in this chapter is a column of it. A feature table has one row for each hour a model must predict. Each row of a feature table holds the value to predict, which the book calls the target, and the features: the readings and facts the model may use for the row's hour. A gradient-boosting model learns a mapping from the columns to the target, one row at a time, so the table is all the model can know.

A row's features must be known at the cutoff of the window that forecasts it, because the forecast is made there. The target is the reading at the hour. The model needs two kinds of row. Training rows are the hours of the history before the cutoff, each with its own features and its own reading as the target. Forecast rows are the 24 hours after the cutoff, with features but no target. The model is fitted on the first kind and predicts the second.

Take the cutoff at 00:00 on Dec 30, 2014. Its forecast rows are the 24 hours of Dec 30, from 00:00 to 23:00, and each has a blank target. Its training rows run back eight weeks, to Nov 4, 2014, one row per client and hour, with the reading as the target. Take the row for Dec 15 at 18:00: its target is the reading at that hour, and its features are readings from earlier hours, such as the reading 24 hours before. No row is a daily total.

Each window's training table is built from the 1,344 hours of history before its cutoff, eight weeks, for each client in SUBSET8. The eight clients are stacked in one table, and the same construction repeats for every decision window and for the three standard cutoffs, Dec 29 to Dec 31, 2014. The first week of history has no reading a week earlier, so it leaves the table: 1,344 hours less 168 hours leaves 1,176 rows per client in each window. One model is fitted per window on that window's history alone, so no training row comes from the days being forecast.

For the lags-only set the columns are the two lags and the target y; the hour of the day arrives with the other calendar columns later in the chapter, and the holiday column after them. MLForecast in mlforecast 1.1.0 takes the series and produces the training rows in fit and the forecast rows in predict. Two of its defaults matter here. A training row whose features are missing is dropped (dropna=True, in mlforecast/core.py), and the first hours of each history drop out because they have no reading a week earlier. Nothing in the library stops a feature from reading the hour it predicts. The rule that stops it is the one you write and check.

Working rule: Build every feature row as if the cutoff were the last reading you have. A feature for a forecast hour must be computable from readings at or before the cutoff of its window. Before any shift test, ask whether the feature is known at the cutoff. Then check it with the shift test from Chapter 3, and do not train on a table you have not checked.

Acrescente defasagens que a previsão possa ver

Última alteração na edição 2026.11.5

Defasagens são as primeiras colunas a acrescentar a essa tabela: leituras anteriores do mesmo cliente. A defasagem de k horas para a hora t é a leitura em t menos k. Defasagens são a maneira mais barata de dar a um modelo o ritmo de uma série: uma defasagem de 24 é a leitura na mesma hora do dia anterior, e uma defasagem de 168 é a leitura na mesma hora de uma semana atrás. O modelo aprende o quanto confiar em cada uma. A defasagem de 168 também lê uma semana inteira para trás, ou seja, o mesmo dia da semana, e por isso carrega o padrão semanal sem precisar de uma coluna de dia da semana.

Saber se uma defasagem é conhecida depende do horizonte. Uma previsão feita às 00:00 cobre as 24 horas a partir do ponto de corte. Chame as horas desse dia de 0 a 23, contadas a partir do ponto de corte. Uma defasagem de k lê a hora j menos k; assim, para a hora-alvo j, ela lê uma leitura anterior ao ponto de corte somente quando j menos k é negativo. Isso precisa valer para todo j de 0 a 23, o que significa que k deve ser 24 ou mais. Uma defasagem de 1 é conhecida na primeira hora, porque lê a última leitura antes do ponto de corte. Para as outras 23 horas, ela lê uma leitura que a previsão não tem.

A tabela abaixo mostra os três tipos de hora-alvo nessa previsão do dia seguinte, para um ponto de corte às 00:00. A hora 0 é a primeira hora após o ponto de corte, e a hora 23 é a última.

Hora-alvo Defasagem 1 lê Defasagem 1 conhecida no ponto de corte Defasagem 24 lê Defasagem 24 conhecida no ponto de corte
00:00 (hora 0) 23:00 do dia anterior sim 00:00 do dia anterior sim
01:00 (hora 1) 00:00 do dia da previsão não 01:00 do dia anterior sim
23:00 (hora 23) 22:00 do dia da previsão não 23:00 do dia anterior sim

As duas defasagens do fornecedor, 24 e 168, são conhecidas em todas as horas da previsão do dia seguinte, de modo que o modelo nunca precisa de uma leitura que ainda não existe. lgbm-feature-sets passa essas duas defasagens para MLForecast, e a biblioteca faz o restante.

A regra do relógio do Capítulo 3 também alcança as defasagens: a hora da falha de 30 de março de 2014 é definida como ausente, de modo que qualquer variável que a leia também fica ausente. No histórico de um ponto de corte de 1º de abril de 2014, lgbm-feature-sets encontra 1 hora mascarada, e 1 linha tem uma defasagem que a lê: a linha 24 horas depois da falha. Antes de o modelo de cada janela ser ajustado, suas horas mascaradas são preenchidas como o Capítulo 3 as preenche, a partir do próprio histórico da janela, e o preenchimento não lê nada posterior ao ponto de corte. Depois de preenchida, a hora passa a ser uma leitura; assim, a linha que a lê mantém seu valor, e o LightGBM nunca recebe um valor ausente vindo de uma defasagem. A regra é uma escolha declarada, não um ótimo medido. A contagem impressa ao lado dela é o que o leitor deve verificar.

Regra prática: Use apenas defasagens pelo menos tão longas quanto o horizonte. Com um horizonte de 24 horas, isso significa 24 horas ou mais, e este livro usa 24 e 168. Uma defasagem mais curta exige uma justificativa, e um modelo que a usa deve passar pelo teste de deslocamento antes que alguém confie em sua pontuação. Mantenha a regra do relógio nas defasagens, conte as linhas cujas defasagens leem uma hora mascarada e conte as horas preenchidas a partir do histórico.

Adicionar características de calendário e de feriados

Última alteração na edição 2026.11.11

Os atrasos são construídos a partir das leituras. As características de calendário, diferentemente dos atrasos, são fatos sobre a própria hora-alvo: sua hora do dia, seu dia da semana e seu mês. Elas são conhecidas com antecedência, porque o relógio as informa antes de existir qualquer leitura. Não precisam de atraso nem de regra de corte. Seu valor em uma hora-alvo não pode depender de nenhuma leitura, de modo que o teste de deslocamento não tem o que detectar.

A demanda do fornecedor segue o dia. A hora do dia repete o que os atrasos já carregam: o ritmo diário. O dia da semana acrescenta o que eles não carregam. Ele informa ao modelo que sábado e domingo diferem dos dias úteis. O mês é a terceira coluna, e é uma coluna fraca com este histórico. Oito semanas de histórico abrangem dois ou três meses do calendário, então month só consegue distinguir algumas semanas do histórico das demais, e, nos cortes padrão, todas as horas previstas caem em dezembro. O livro usa três características de data do mlforecast, nomeadas pelo atributo: hour, dayofweek e month. A coluna do dia da semana já contém o fim de semana, por isso o livro não acrescenta um indicador separado para ele. No pandas, dayofweek conta segunda-feira como 0 e domingo como 6, de modo que sábado e domingo são os dois valores que uma árvore precisa separar do restante. Uma árvore pode dividir isso em um único passo, e é por isso que o dia da semana é barato de testar.

Um feriado público não segue o dia da semana. Um modelo com apenas características de dia da semana lê 25 de dezembro de 2014 como uma quinta-feira comum, e lê um feriado em um domingo como um domingo comum. A característica de feriado responde a isso. Ela é uma função do carimbo de data e hora, is_holiday, no módulo compartilhado examples/lib/features.py, que retorna 1 em um feriado nacional português e 0 nos demais dias. O mlforecast aceita essa função como característica de data e nomeia a coluna com base no nome da função. Os feriados vêm do pacote holidays na versão 0.110.dev20261118063242, sob a licença MIT, por meio de holidays.country_holidays("PT", years=[2013, 2014]). Para os dois anos dos dados, o pacote lista 18 datas. O livro não inclui essa lista. Cada execução a constrói a partir do calendário do pacote.

Os cortes padrão são de 29 a 31 de dezembro de 2014, e nenhuma das suas 72 horas por cliente é feriado. O dia 25 de dezembro da semana reservada está fora deles, portanto o efeito da característica nesse dia não é avaliado neste capítulo. Nos cortes padrão, ela chega às pontuações apenas por meio do histórico de treinamento, que contém os feriados de 8 e 25 de dezembro de 2014.

A lista de feriados é um fato conhecido com antecedência, assim como o dia da semana. Ela vem de um calendário publicado e não das leituras, de modo que não pode vazar uma leitura do dia-alvo. As características de calendário respondem à pergunta da regra prática em cada hora-alvo, por construção, e um atraso só é válido quando tem pelo menos a duração do horizonte.

Regra prática: Acrescente as características de calendário de que o ritmo do caso precisa e mantenha cada uma apenas se ela ajudar nas mesmas janelas, como a próxima seção mede. Para feriados, use um calendário que cubra todos os anos dos seus dados e todos os anos que você vai prever, e imprima quantos feriados ele contém para esses anos. Uma contagem igual a zero para um ano previsto significa que a lista não tem esse ano, e não que o ano não teve feriados.

Escolha nas janelas de decisão

Última alteração na edição 2026.11.11

As janelas de decisão são as janelas sobre as quais o conjunto de atributos é escolhido, nunca os cortes padrão, que são as janelas que o livro reporta. Há dois tipos. O primeiro são quatro cortes comuns, 25 de novembro, 26 de novembro, 2 de dezembro e 3 de dezembro de 2014. O segundo são sete cortes de feriado: os feriados nacionais portugueses de 2014 anteriores a 25 de dezembro cujo histórico de oito semanas está completo, 18 de abril, 20 de abril, 25 de abril, 1 de maio, 10 de junho, 15 de agosto e 8 de dezembro. As janelas comuns não contêm feriado, por isso um atributo de feriado nunca venceria nelas, e as janelas de feriado são onde ele pode vencer. A escolha, portanto, usa todas as janelas de decisão, pois um dos conjuntos contém um atributo de feriado. Os cortes padrão são avaliados após a escolha e impressos ao lado dela. Eles não escolhem nada.

O indicador de feriado atua de duas maneiras. Nas janelas de decisão ele fica ativo nas horas avaliadas, podendo assim alterar uma previsão. Nos cortes padrão nenhum feriado cai em uma hora avaliada, de modo que o indicador só altera essas avaliações por meio do treinamento.

Regra prática: Escolha um atributo sobre janelas que venham antes da semana reservada e que tenham o tipo de dia para o qual o atributo serve: um atributo de feriado precisa de janelas de feriado. Os cortes padrão são reportados ao lado da escolha e nunca usados para fazê-la.

Meça o que cada atributo acrescenta

Última alteração na edição 2026.11.11

Um atributo vale a pena ser mantido quando reduz o erro em janelas que o modelo não usou no treinamento. Para medi-lo, mantenha tudo o mais fixo: as mesmas janelas, o mesmo histórico, as mesmas configurações. Três conjuntos de atributos são ajustados, um de cada vez. O primeiro tem apenas defasagens. O segundo acrescenta os atributos de calendário. O terceiro acrescenta a esses o atributo de feriado. Cada conjunto é ajustado uma vez por janela, com um único modelo para os oito clientes de SUBSET8, e cada um é comparado com o naïve sazonal nas mesmas janelas.

Cada conjunto recebe duas pontuações. O MAE agregado é o MAE sobre todas as horas-cliente das janelas, o número único para o fornecedor como um todo. O MASE médio por cliente é o MASE de cada cliente, com média sobre os oito clientes. O MASE divide o erro de cada cliente por uma escala: o erro absoluto médio que o naïve sazonal comete na amostra, sobre as leituras do próprio cliente. O livro usa uma única função de escala em todo lugar, scoring.book_scale. A escala lê todas as leituras anteriores à primeira janela avaliada do conjunto, 18 de abril de 2014 às 00:00, com as horas de mudança de horário mascaradas, de modo que não depende das janelas avaliadas e não pode vazar informação. Um cliente exige cuidado. MT_115 começa a registrar leituras em 14 de janeiro de 2014, e os zeros anteriores à sua primeira leitura ficam fora de sua escala, porque ela é contada a partir da primeira leitura. O Capítulo 4 ensina essa regra para clientes que começam mais tarde.

lgbm-feature-sets.py Python 3.13.16 · holidays 0.110.dev20261118063242 · lightgbm 4.7.0 · mlforecast 1.1.0 · numpy 2.5.5 · pandas 2.3.3 · statsforecast 2.1.1 · utilsforecast 0.2.17 Aprovado
"""Compare three feature sets for the global LightGBM forecast of SUBSET8 on the decision windows (B-5, B-9, B-10): fourordinary cutoffs and seven 2014 holidays before Dec 25, each fitted scaled and unscaled. The mean MASE lines carry thechoice; the standard-cutoff lines are reported beside it and choose nothing."""import pandas as pdfrom lib.backtest import history_beforefrom lib.electricity import loadfrom lib.features import CALENDAR, PT_HOLIDAYS, is_holiday, rows_reading_missing, score_feature_setsfrom lib.panel import DECISION_CUTOFFS, HOLIDAY_DECISION_CUTOFFSfrom lib.quirks import mask_clock_changesfrom lib.settings import EVAL_CUTOFFS, LEAD, SUBSET8, showLAGS = [24, 168]  # both at least the 24-hour horizon, so each is known at every forecast hour# CALENDAR is hour, dayofweek and month, as mlforecast date features; the holiday set adds is_holiday to themFEATURE_SETS = {"lags_only": [], "with_calendar": CALENDAR, "with_holidays": CALENDAR + [is_holiday]}MODELS = ["SeasonalNaive", *FEATURE_SETS, *[f"unscaled_{name}" for name in FEATURE_SETS]]DECISION = sorted([*DECISION_CUTOFFS, *HOLIDAY_DECISION_CUTOFFS])  # the decision windows; standard cutoffs are not hereraw = load(SUBSET8)# DECISION[0] is the first decision window, Apr 18, 2014: the MASE scale reads only the readings before itforecasts, scored, per_client = score_feature_sets(raw, DECISION, LAGS, FEATURE_SETS, DECISION[0])show("clients", forecasts["unique_id"].nunique())show("decision windows", len(DECISION))show("scored hours", len(scored))show("Portuguese holidays in 2013 and 2014", len(PT_HOLIDAYS))show("holiday hours in the decision windows", int(is_holiday(scored["ds"]).sum()))for model in MODELS:    show(f"MAE {model.replace('unscaled_', 'unscaled ')}", (scored["y"] - scored[model]).abs().mean())for model in MODELS:    show(f"mean MASE {model.replace('unscaled_', 'unscaled ')}", per_client[model].mean(), digits=3)for model in MODELS:    # the prose does not quote this client, so this line is for reference only    show(f"MASE MT_268 {model.replace('unscaled_', 'unscaled ')}", per_client.loc["MT_268", model], digits=3)# The standard cutoffs, reported beside the choice above. Nothing is chosen from them.# The scale here reads the readings before the first standard cutoff, Dec 29, 2014._, _, standard = score_feature_sets(raw, EVAL_CUTOFFS, LAGS, FEATURE_SETS, EVAL_CUTOFFS[0])for model in MODELS:    show(f"standard cutoffs, mean MASE {model.replace('unscaled_', 'unscaled ')}", standard[model].mean(), digits=3)# Clock-change check: the history of a 1 April 2014 cutoff holds the 30 March gap, which the feature rules must reach.march = history_before(mask_clock_changes(load([LEAD])), pd.Timestamp("2014-04-01"))  # the Chapter 3 mask, then the cutshow("masked hours in the history", int(march["y"].isna().sum()))# a row counts when either lag, 24 or 168, reads a masked hourshow("rows whose lag reads a masked hour", rows_reading_missing(march.set_index("ds")["y"], LAGS))
Saídapython lgbm-feature-sets.py
clients: 8
decision windows: 11
scored hours: 2112
Portuguese holidays in 2013 and 2014: 18
holiday hours in the decision windows: 1344
MAE SeasonalNaive: 305.21
MAE lags_only: 280.57
MAE with_calendar: 270.57
MAE with_holidays: 267.40
MAE unscaled lags_only: 304.03
MAE unscaled with_calendar: 271.63
MAE unscaled with_holidays: 280.75
mean MASE SeasonalNaive: 0.934
mean MASE lags_only: 0.886
mean MASE with_calendar: 0.894
mean MASE with_holidays: 0.893
mean MASE unscaled lags_only: 1.115
mean MASE unscaled with_calendar: 1.119
mean MASE unscaled with_holidays: 1.139
MASE MT_268 SeasonalNaive: 0.840
MASE MT_268 lags_only: 0.797
MASE MT_268 with_calendar: 0.758
MASE MT_268 with_holidays: 0.789
MASE MT_268 unscaled lags_only: 0.855
MASE MT_268 unscaled with_calendar: 0.871
MASE MT_268 unscaled with_holidays: 0.936
standard cutoffs, mean MASE SeasonalNaive: 1.162
standard cutoffs, mean MASE lags_only: 1.057
standard cutoffs, mean MASE with_calendar: 1.165
standard cutoffs, mean MASE with_holidays: 1.134
standard cutoffs, mean MASE unscaled lags_only: 1.357
standard cutoffs, mean MASE unscaled with_calendar: 1.494
standard cutoffs, mean MASE unscaled with_holidays: 1.486
masked hours in the history: 1
rows whose lag reads a masked hour: 1

O naïve sazonal é a referência aqui. Seu MAE, agregado sobre 2112 horas avaliadas (oito clientes em 11 janelas de 24 horas cada), é de 305.21 kWh.

Sem escala, o modelo só com defasagens fica atrás do naïve sazonal na visão por cliente. Seu MASE médio por cliente é 1.115, pior que os 0.934 do naïve sazonal. Os clientes diferem muito em porte, de modo que as leituras dos maiores são muitas vezes as dos menores. Um modelo global ajusta uma única perda sobre as linhas de todos os clientes, e aqui essa perda é o erro quadrático em kWh; assim, os erros dos maiores clientes determinam as divisões e os pequenos clientes pesam pouco. Achamos que a causa está na perda, e não na amplitude de um cliente específico. As execuções com escala, abaixo, eliminam a diferença, o que sustenta essa leitura. Trata-se de um julgamento a partir desses números, e não de uma prova.

As execuções com escala padronizam o alvo de cada cliente com LocalStandardScaler do mlforecast (mlforecast/target_transforms.py), que subtrai a média do cliente e divide pelo seu desvio padrão. Ambos vêm do histórico da janela anterior ao ponto de corte, ajustados dentro de fit, e predict apenas desfaz essas transformações. Nenhuma leitura posterior ao ponto de corte define esses valores, de modo que a escala passa no mesmo teste que os atributos. make_forecaster usa scaled=True por padrão, e o Capítulo 6 reaproveita esse padrão.

Com escala, a comparação muda, e apenas as defasagens superam o naïve sazonal na visão por cliente: um MASE médio de 0.886, contra 0.934. Seu MAE agregado é de 280.57 kWh.

O conjunto de calendário não supera o modelo só com defasagens. Ainda assim supera o naïve sazonal: seu MASE médio é 0.894, e seu MAE agregado é de 270.57 kWh.

O indicador de feriado, acrescentado ao conjunto de calendário, reduz a diferença sem eliminá-la: a média é 0.893, e o MAE agregado é de 267.40 kWh.

O Capítulo 4 definiu o AutoETS e o ARIMA como a referência que um modelo de gradient boosting precisa superar. Nos pontos de corte padrão, o modelo só com defasagens também fica abaixo dessa referência: 1.057 contra 1.09 do ARIMA, com os mesmos clientes, pontos de corte e escala.

Pela regra prática, só as defasagens permanecem, e a visão por cliente decide, porque é ela que importa para a previsão de cada cliente. O MASE médio do conjunto de calendário está acima do das defasagens, por isso ele não é mantido. A visão agregada aponta em outra direção aqui: o MAE agregado do conjunto de calendário está abaixo do das defasagens, e o do conjunto de feriados é menor ainda. O capítulo relata ambas, como a regra exige, e não ajusta o modelo para fazer as duas concordarem.

A regra mantém um atributo apenas quando ele reduz o erro do conjunto que estende. O indicador de feriado reduz a média do conjunto de calendário por um fio, pouco demais para contar como ganho, e o conjunto que o contém continua acima do das defasagens. O indicador está ativo em 1344 horas-cliente, um dia inteiro em cada janela de feriado, para cada cliente, de modo que teve sua chance e não conquista um lugar. Por isso o livro entrega ao Capítulo 6 o conjunto só com defasagens. Esse resultado vem de 11 janelas, o que é um teste pequeno.

Regra prática: Mantenha um conjunto de atributos somente quando ele reduzir o MASE médio por cliente em relação ao conjunto que estende, nas mesmas janelas. Informe o MAE agregado ao lado. Não ajuste o modelo para fazer desaparecer uma divergência entre as duas visões.

Detecte um lag que vaza o futuro

Última alteração na edição 2026.11.11

As medições acima supõem que cada variável é conhecida no seu ponto de corte. Um vazamento é uma variável que usa uma leitura que a previsão não pode ter no seu ponto de corte. Na visão do livro, um vazamento é uma provável razão para um backtest parecer melhor do que o modelo será, e ele pode surgir por acidente. Um padrão comum constrói a tabela de variáveis uma única vez a partir da série inteira, de modo que cada hora-alvo carrega o seu lag, e depois avalia as linhas de previsão da tabela como se fossem fora da amostra. Nada falha. A pontuação fica boa demais, e nada nela indica isso.

A biblioteca acrescenta uma segunda armadilha. MLForecast prevê de forma recursiva por padrão. Na previsão recursiva, para um horizonte de 24 horas, MLForecast prevê uma hora, grava essa previsão de volta como a leitura da hora seguinte e repete (_predict_recursive em mlforecast/core.py). Um lag de 1 passa a ler uma previsão para cada hora após a primeira, enquanto o treinamento leu leituras reais para esse lag. Chamar essa incompatibilidade de vazamento é um julgamento do livro. É mais um motivo para escolher lags de 24 ou mais. Com lags de 24 e 168, cada um dos 24 passos lê leituras reais, de modo que a recursão nunca alimenta este modelo com as suas próprias previsões. Com max_horizon definido, a biblioteca treina um modelo por horizonte, e prevê com eles em _predict_multi. A regra não muda com isso: uma variável deve ainda ser conhecida no ponto de corte da janela que ela prevê.

O teste de deslocamento do Capítulo 3 se aplica com uma mudança: compare o lag nas horas-alvo após o ponto de corte, e não nas linhas do histórico. Calcule o lag para cada hora-alvo duas vezes: uma a partir do histórico cortado no ponto de corte, e outra a partir da série inteira. Conte as horas em que os dois diferem. Um lag de 24 concorda em todas as horas-alvo, porque cada uma das 24 horas lê uma leitura anterior ao ponto de corte. Um lag de 1 concorda apenas na primeira hora.

Qual você espera que tenha o menor erro, o modelo com lag de 1 ou o modelo sem ele? Ambos são ajustados às mesmas linhas de treinamento com as mesmas configurações, para cada um dos três pontos de corte padrão. O modelo honesto usa os lags 24 e 168. O modelo com vazamento acrescenta um lag de 1, lido da série inteira para as horas-alvo, que é o que a tabela construída uma única vez faria.

lag-leak-check.py Python 3.13.16 · holidays 0.110.dev20261118063242 · lightgbm 4.7.0 · mlforecast 1.1.0 · numpy 2.5.5 · pandas 2.3.3 · statsforecast 2.1.1 · utilsforecast 0.2.17 Aprovado
"""Shows which lag leaks: a lag of 1 reads the hour before each target hour, which a 24-hour forecast does not have at itscutoff. The rows-differing lines are the shift test, and the two MAE lines show how much the leak flatters the score."""import numpy as npimport pandas as pdfrom lib.electricity import loadfrom lib.features import fit_window_mae, lag_valuesfrom lib.settings import EVAL_CUTOFFS, HORIZON, LEAD, showy = load([LEAD]).set_index("ds")["y"].asfreq("h")  # asfreq gives every hour a row, so a missing hour is NaN, not skippedHONEST, LEAKY = [24, 168], [1, 24, 168]  # HONEST lags are both at least the horizon; LEAKY adds lag 1CUTOFFS = pd.to_datetime(EVAL_CUTOFFS)def shift_test(lag):    """Target hours where the lag differs between the history cut at each cutoff and the whole series, and how many."""    compared = differing = 0    for c in CUTOFFS:        targets = pd.date_range(c, periods=HORIZON, freq="h")  # the 24 hours each forecast must predict        honest = lag_values(y[y.index < c], lag, targets)  # readings before the cutoff only, as the forecast has them        whole = lag_values(y, lag, targets)  # the same lag read from the whole series, as a table built once would read it        same = (honest == whole) | (np.isnan(honest) & np.isnan(whole))  # NaN never equals NaN, so the second term counts two missing readings as the same        compared += len(targets)        differing += int((~same).sum())    return compared, differingshow("cutoffs", len(CUTOFFS))show("rows compared", shift_test(1)[0])  # the first value is the hours compared, the same for every lagfor lag in (1, 24, 168):    show(f"rows differing for lag {lag}", shift_test(lag)[1])show("MAE honest, lags 24 and 168", fit_window_mae(y, HONEST, CUTOFFS, leaky=False))  # the table holds the lags and the hour of day; leaky=False reads the target lags from the cut historyshow("MAE leaky, lags 1, 24 and 168", fit_window_mae(y, LEAKY, CUTOFFS, leaky=True))  # leaky=True reads the whole series
Saídapython lag-leak-check.py
cutoffs: 3
rows compared: 72
rows differing for lag 1: 69
rows differing for lag 24: 0
rows differing for lag 168: 0
MAE honest, lags 24 and 168: 5.36
MAE leaky, lags 1, 24 and 168: 2.87

Somente o lag de 1 falha no teste de deslocamento. Das 72 horas-alvo comparadas, 69 leram um valor diferente do histórico cortado do que da série inteira: todas as horas de cada janela, exceto a primeira. Os lags de 24 e 168 diferem em 0 e 0 linhas. O lag de 1 concorda apenas na primeira hora de cada janela, porque essa hora lê a última leitura antes do ponto de corte, que a previsão de fato possui.

O modelo com vazamento parece quase duas vezes melhor: o seu MAE é de 2.87 kWh, contra 5.36 kWh do modelo honesto. A diferença é o vazamento. O seu lag de 1 lê a hora anterior ao alvo, que, para a maioria das horas-alvo, é uma hora da própria janela de previsão. O modelo honesto nunca vê essa hora, de modo que o seu erro é o que a produção vai mostrar.

Regra prática: Execute o teste de deslocamento em todos os lags e em todas as variáveis de janela antes de um modelo treinar com elas, e trate qualquer linha diferente como vazamento até que você demonstre o contrário. Quando um erro cai bruscamente depois que você acrescenta uma variável, verifique essa variável primeiro, antes de lhe atribuir o mérito.

O que dá errado em produção

Última alteração na edição 2026.11.5

Uma lista de feriados que termina no fim dos dados registra zero para todos os feriados posteriores. A sinalização permanece desligada em todos os dias do ano previsto, e o modelo prevê os feriados como dias comuns. O primeiro feriado aparece como um erro grande no painel. A contagem de feriados impressa pelo exemplo é a verificação: uma lista para um novo ano que imprime zero feriados está sem aquele ano. Uma versão posterior de holidays também pode alterar o seu calendário; por isso, fixe a versão, como o livro faz, e execute a contagem novamente após qualquer atualização.

Um lag menor que o horizonte, herdado de um modelo horário e usado em uma previsão para o dia seguinte, tem bom desempenho no backtest, porque o backtest foi construído a partir de toda a série. Em produção, as horas posteriores leem as previsões do próprio modelo. Compare o erro em tempo real por hora da previsão do dia seguinte com o erro do próprio backtest por hora. Um modelo sem o vazamento deve apresentar aproximadamente o erro que o backtest apresentou em cada hora. Um erro que cresce com a hora do horizonte, além do que o backtest mostrou, é o sinal de realimentação pelas previsões do próprio modelo.

A regra do relógio ainda pode falhar no pipeline. Horas mascaradas deixam algumas variáveis de previsão ausentes, e um pipeline pode descartar essas linhas, ou preencher essas horas, sem avisar. Imprima as horas mascaradas e as linhas que elas afetam sempre que o histórico mudar.

Uma pontuação agregada pode ocultar o cliente típico. Em lgbm-feature-sets, o MAE agregado do modelo somente com lags, sem escalonamento, 304.03 kWh, é inferior ao 305.21 kWh do seasonal naive, mas o seu MASE médio por cliente é 1.115, contra 0.934. O fornecedor compra energia para cada cliente, então o valor por cliente é o que decide a previsão de um cliente. Um fornecedor que informa apenas o MAE agregado venderá a previsão errada aos clientes que o valor agregado oculta. Informe o MASE por cliente ao lado do valor agregado e examine primeiro o pior cliente.

Os resultados também podem depender da máquina. A referência de parâmetros do LightGBM afirma que deterministic produz resultados estáveis para os mesmos dados e os mesmos parâmetros no tipo de dispositivo CPU, e alerta que os resultados podem diferir com outras versões do LightGBM, com binários compilados por outros compiladores, ou em outros sistemas. O livro define deterministic, histogramas por linha, uma thread e uma semente fixa, sob o LightGBM 4.7.0. Essas configurações tornam a saída repetível em uma máquina com um mesmo número de threads: a saída foi idêntica em três execuções na máquina de gravação. Elas não garantem concordância entre máquinas, e o livro não testou isso. As pontuações são citadas arredondadas, e o arredondamento não faz duas máquinas concordarem. Se uma máquina de lançamento imprimir valores diferentes, a saída registrada precisa de um novo registro, e o texto precisa da mesma verificação.

Regra prática: Verifique novamente a contagem de feriados para cada ano previsto, as horas mascaradas e as linhas que elas atingem, e o tamanho dos lags sempre que os dados ou uma biblioteca mudarem. Execute o teste de deslocamento em cada lag, e leia o MASE por cliente ao lado do MAE agregado. Uma verificação que muda é motivo para parar e entender a causa antes de publicar a próxima previsão.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.5

As escolhas abaixo são as que um leitor teria de fazer de outra forma para mudar os resultados. Cada uma é uma decisão do livro, sujeita a revisão quando uma edição posterior medir outra coisa.

  • O modelo repassado usa apenas os lags 24 e 168. O lag 1 aparece somente na verificação de vazamento, nunca em uma previsão.
  • O conjunto de calendário é hour, dayofweek e month. Ele é medido e não é mantido: na visão por cliente, é pior do que usar apenas os lags. Não há um indicador separado para fim de semana, porque o dia da semana já contempla o fim de semana.
  • O indicador de feriado é medido apenas sobre o conjunto de calendário, em todas as janelas de decisão. Ele não é mantido, porque o conjunto que o contém ainda é pior do que usar apenas os lags. O capítulo 6 usa o conjunto apenas com lags.
  • Os feriados vêm do pacote holidays para Portugal, referentes aos dois anos dos dados. A função is_holiday fica em examples/lib/features.py.
  • A variável alvo de cada cliente é escalonada por padrão, com make_forecaster(scaled=True). O escalonador é ajustado somente com o histórico de cada janela. A execução sem escalonamento é impressa uma única vez, para mostrar a falha que o escalonamento corrige.
  • As horas mascaradas da mudança de horário de cada janela são preenchidas com o histórico dessa janela antes do ajuste, de modo que nenhuma linha é descartada por causa delas e o LightGBM nunca recebe um valor ausente.
  • As configurações do LightGBM são LGBM_PARAMS em examples/lib/features.py: determinísticas, histogramas por linha (row-wise), uma thread e semente 0. Elas ficam ali, e não em settings.py, que este capítulo deixa inalterado.
  • A escala do MASE é scoring.book_scale. Ela começa na primeira leitura de cada cliente e usa as leituras anteriores à primeira janela de decisão, 18 de abril de 2014.
  • Nas janelas de decisão, o modelo com apenas lags supera o naive sazonal na média do MASE por cliente. O capítulo não ajusta o modelo para alterar esse resultado.
  • Os conjuntos de atributos são escolhidos nas janelas de decisão, e não nos cortes padrão nem na semana reservada para teste. As janelas de feriados terminam em 8 de dezembro, por isso o efeito do feriado em 25 de dezembro não é medido neste capítulo. Também não se mede aqui se os atributos de calendário compensam em um histórico mais longo.
  • A verificação de vazamento usa MT_014, um único cliente, porque o vazamento é uma propriedade do lag e não da composição de clientes; por isso, sua variável alvo não é escalonada. Os conjuntos de atributos usam SUBSET8.
  • O capítulo 6 reaproveita make_forecaster, mlforecast_windows, fit_window_mae, lag_table e is_holiday de examples/lib/features.py. make_forecaster escalona por padrão.
  • A lição é uma ordem de testes: o teste de deslocamento roda antes de qualquer pontuação, e o MASE por cliente decide quais atributos permanecem.

Este capítulo, nesta edição

Edição 2026.11.11Exemplos aprovados em 20 de nov de 20262 de 2 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.11.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 5 de 10: Adicionar variáveis de calendário e de defasagem

  1. Turn history into features
  2. Acrescente defasagens que a previsão possa ver
  3. Adicionar características de calendário e de feriados
  4. Escolha nas janelas de decisão
  5. Meça o que cada atributo acrescenta
  6. Detecte um lag que vaza o futuro
  7. O que dá errado em produção
  8. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos