Guia de execução — fechamento da dissertação

Números provisórios

O critério de elegibilidade descrito abaixo em ‘Elegibilidade’ (≥ 4 anos não nulos na janela de treino) era o desenho original de 08/07/2026. O autor resolveu o IMP-ELEG em 01/09/2026: a elegibilidade mínima vigente é 2 anos (config.yaml, bloco elegibilidade) — min2 é o canônico do Capítulo 5, e o mínimo de 4 anos passou a cenário de sensibilidade. O restante do desenho (escopo, pipeline, ordem dos experimentos) segue como descrito abaixo.

O que entra e o que sai do escopo, como os dados ficam organizados, qual pipeline os processa, quais experimentos rodam e em que ordem.

Como ler

Este é o plano de execução que operacionaliza a proposta de encaminhamento: a proposta decide o rumo, o guia decide a ordem. Escrito em 08/07/2026 a partir do parecer metodológico de 06/07 e das checagens já executadas.

1. A decisão que organiza tudo

O Caminho E trata a estruturação temporal como a pergunta e as transições entre etapas como a explicação da heterogeneidade encontrada. Protocolo único, escopo do 1º EF ao 3º EM, apenas escolas públicas, cobertura nacional.

Entra

Comparação retroativa × escalonada
Taxonomia interna/fronteira
Caracterização das transições (MAE + WAPE + mecanismo)
Investigação do baseline de persistência
Direção do erro
Kalman como método comparado
Ensemble simples
Reprocessamento só-públicas
Ensino Médio no desenho experimental
Sensibilidade com séries descontínuas

Núcleo herdado da qualificação, mais o que a banca cobrou.

Condicional

Representação progressão/coorte em escala nacional ou amostral (depende de o E7 caber no prazo)
Compra por quantis além de Maceió (E9)
Escalonada-EM completa (uma tentativa; se falhar, vira achado)

Decidido pelo calendário, não pelo mérito.

Sai

Alocação espacial como contribuição (fica como resultado negativo)
Nacionalização obrigatória do GPR
Refinamento do Kalman
Variáveis exógenas (justificar exclusão no texto)
Conformal e MASE como eixos
Machine learning e deep learning

Cada exclusão precisa de uma frase de justificativa no texto.

Regras de ouro

Nenhum número do Capítulo 5 atual é definitivo até o reprocessamento só-públicas.
Nenhuma comparação entre blocos antigos — tudo renasce do pipeline consolidado.

2. Como os dados ficam organizados

Formato longo, Parquet onde há volume, CSV só para artefatos pequenos ou publicáveis. Tudo deriva de observacoes.parquet e nada é editado à mão. Sete módulos numerados, idempotentes, executáveis por linha de comando (python -m pipeline.30_series --config config.yaml), com log por execução.

Pipeline e artefatos. cada módulo lê o config.yaml e produz um artefato nomeado. As caixas tracejadas são saídas de leitura, não bases; o registry carimba toda execução.

Dicionário dos artefatos

Arquivo	Grão	Observação
`A. observacoes.parquet`	escola × etapa × ano	Fonte única da verdade. `tp_dependencia` por ano se viável (os microdados de 2007–2024 estão em `Arquivos aux microdados`); senão, snapshot de 2025 com flag — decisão registrada.
`B. mapa_transicoes_etapas.csv`	transição	Cadeia de progressão e classificação crítica/interna. Copiar do `config.py` da Validação Transição, que já resolve a armadilha do código 41.
`C. series_modelagem.parquet`	série × observação	Uma tabela para todas as representações; o formato largo é gerado na hora quando um modelo exigir. `serie_id` = hash(co_entidade, etapa_alvo, ano_alvo, representação).
`D. predicoes.parquet`	predição	As ~15 colunas já especificadas no CONTEXTO, incluindo `fallback_usado`, `motivo_falha` e `tempo_ms`. Append-only por `run_id`.
`E. metricas_agregadas.csv`	run × recorte	Sempre derivado de D por script — nunca calculado à mão em notebook.
`F. registry_experimentos.yml`	run	`git_hash`, snapshot da config, hashes de entrada, seeds e status. Sem entrada no registry, o resultado não existe.

3. Representações de série

Cadeia de progressão. a representação escalonada anda para trás por esta cadeia. As três transições marcadas em vermelho são as críticas — aquelas em que o aluno muda de escola, rede ou município.

Representação	Regra de construção	Risco
Retroativa	Etapa-alvo fixa, valores da mesma etapa em t−k.	Baixo — já validada; é a referência.
Escalonada	Para o alvo `e` em `y`: valor da etapa anterior na cadeia em y−1, y−2… na mesma escola.	A do EM precisa ser reconstruída encadeando desde o EF sobre a base completa — a atual saiu só com as etapas 25–27 e tem histórico de 1 a 3 anos. No 1º EM a cobertura será baixa por construção: reportar, não forçar.
Progressão / coorte	Escalonada ajustada pela razão média destino/origem da transição, estimada apenas nos anos de treino do fold.	Vazamento se a razão usar anos de teste; razões instáveis em escolas pequenas — usar razão por transição agregada, não por escola.
Interna / fronteira	Atributo da etapa-alvo, não uma série nova: vira coluna em C e D.	O 1º EF fica como fronteira nominal, mas sem penalidade empírica — reportar assim.
Fallback	Escalonada inelegível → retroativa; retroativa inelegível → último valor; nada → sem predição, com `motivo_falha`.	Contamina comparações. As análises comparativas usam só o subconjunto sem fallback; ele existe para a leitura operacional de "predição para tudo".

4. Modelos

Modelo	Papel	Parâmetros	Custo	Prioridade
Média histórica	baseline	—	trivial	P0
Último valor	baseline de persistência — é o objeto da SP3	—	trivial	P0
Regressão linear	baseline de tendência	mín. 2 pontos	trivial	P0
Suavização exponencial	baseline recente-ponderado	α = 0,5 (sensibilidade 0,3 / 0,7 em amostra)	trivial	P0
Kalman simples	comparação herdada do TCC	iterações do EM entre 0 e 2, fixadas e documentadas	~3× os baselines	P0
Ensemble simples	responde à sugestão da banca	média e mediana das predições dos cinco acima	trivial	P1
GPR / coorte	regra de domínio (SP4)	razões por transição, do treino	médio	P2
~~ARIMA, ETS, ML~~	Fora do escopo — justificar no texto.

5. Protocolo experimental

Backtesting com defasagem T−2. a janela de treino cresce a cada fold, mas nunca encosta no ano-alvo: os dois anos hachurados reproduzem o intervalo real entre o dado do Censo e a decisão de compra do PNLD.

Elegibilidade: ≥ 4 anos não nulos na janela de treino; sensibilidade com 3 e 5 em amostra.
Zeros: Ausência de oferta, não quantidade — descartados do histórico, com a decisão explicitada no texto.
Rede: TP_DEPENDENCIA ∈ {1, 2, 3}. Dependência por ano quando os microdados permitirem; se for snapshot de 2025, registrar como ameaça à validade — escolas extintas antes de 2025 ficam de fora.
Escopo: Etapas-alvo 14–21, 41, 25–27. A pré-escola (2) entra só como origem. Cobertura nacional.
Séries descontínuas: Cenário principal com a regra de elegibilidade, mais um cenário de sensibilidade com regra relaxada em duas ou três etapas (no mínimo 6º e 9º ano) — é a resposta ao exemplo que o Thyago deu.
Comparações pareadas: Sempre no subconjunto comum de (escola, etapa-alvo, ano-alvo), reportando a cobertura de cada representação. A escalonada nivela a interseção por baixo: explicar, não esconder.

6. Métricas e testes

Instrumento	Quando usar
MAE	Métrica principal — sempre por etapa e por posição, nunca só global.
WAPE	Sempre ao lado do MAE. É a única base válida para comparar etapas de portes diferentes, como EF e EM.
Decomposição MAE = tamanho médio × WAPE	Tabela obrigatória nas transições. Com os números atuais, que serão reprocessados: 5º→6º EF, MAE ×1,66 ≈ tamanho ×1,59 × WAPE ×1,05; 9º EF→1º EM, ×2,36 ≈ ×2,13 × ×1,11.
Bias médio e taxa de sub/superestimação	Direção do erro por método × representação × etapa. É o que conecta ao PNLD.
Erro agregado	Leitura operacional de "quantos livros"; base do E9.
Wilcoxon pareado + rank-biserial + Holm	Método × método e representação × representação, nas mesmas unidades.
Mann-Whitney + rank-biserial	Internas × fronteiras, que são grupos independentes.
Descritivas	Antes de tudo. O módulo 20 precede e contextualiza qualquer teste.

Proibições

MAPE em agregações — no máximo uma menção com ressalva.
R² fora das comparações principais.
A palavra "significativo" sem teste formal.
Ranking global sem segmentação.

7. Experimentos

Os dez experimentos. a ordem é da esquerda para a direita. O bloco P0 é o que sustenta a dissertação; P1 e P2 só entram com o P0 fechado.

ID	Objetivo	Critério de sucesso	Risco
`E0`	Sanity checks: totais contra a sinopse do INEP, códigos (41 e 22), duplicatas, cobertura de dependência, escolas extintas.	Divergências abaixo de 1%, todas explicadas.	Achar problema grave na base — melhor agora que em setembro.
`E1`	Reprocessar tudo sobre a base só-públicas.	Capítulo 5 reproduzível em versão só-pública.	Números mudarem qualitativamente; improvável, a direção deve se manter.
`E2`	Retroativa × escalonada — o núcleo da SP1, agora de 1º EF a 3º EM.	Comparação pareada com cobertura reportada.	Cobertura baixa da escalonada nas fronteiras — é achado, não falha.
`E3`	Análise por etapa em toda a educação básica.	Curva por etapa com a decomposição.	Leitura errada se o WAPE faltar.
`E4`	Internas × fronteiras, com a taxonomia como fator.	Penalidade relativa quantificada, com tamanho de efeito.	Efeito pequeno em WAPE — reportar com honestidade.
`E5`	Estabilidade e persistência: por que o último valor é difícil de superar.	Explicação empírica documentada.	—
`E6`	Recomputar todos os testes a partir de D.	Zero teste solto fora do pipeline.	—
`E-EM`	Reconstruir a escalonada do EM encadeando 21 → 41 → 25 → 26 → 27.	Histórico médio ≥ 4 anos nas séries elegíveis.	Cobertura baixa no 1º EM por construção — coerente com o mecanismo.
`E8`	Ensemble e cobertura com fallback.	Ensemble comparado sob o mesmo protocolo.	Diluir o foco: é uma tabela, não um capítulo.
`E7`	GPR/coorte além de Maceió, em amostra estratificada ou uma UF.	Efeito na mesma direção do de Maceió.	Prazo. Se não couber, fica Maceió mais trabalho futuro.
`E9`	Compra e risco por quantis — já existe para Maceió, com p* ≈ 0,70–0,80.	Curva reproduzida sob o pipeline novo.	Escopo; a versão de Maceió já basta para o texto.

8. O que isso vira na dissertação

Tabelas

T1 caracterização da base
T2 global, método × representação
T3 por etapa, 1º EF a 3º EM
T4 decomposição das transições
T5 pareada retroativa × escalonada
T6 internas × fronteiras
T7 GPR/coorte
T8 cobertura e fallback

Figuras

F1 MAE por etapa — a curva com picos no 6º e no 1º EM
F2 WAPE por etapa — a mesma curva, achatada
F3 sub e superestimação
F4 razões de progressão
F5 curva falta × sobra
F6 fluxograma do pipeline

O par F1/F2 é o coração do argumento.

O mapeamento para os capítulos já está definido: Método proposto recebe a taxonomia, as representações e o protocolo (módulos 30–60); Configuração dos experimentos recebe o config.yaml, o registry e a elegibilidade; Resultados recebe T2–T8 e F1–F5 na ordem do arco — global, etapa, fronteiras, mecanismo, coorte, resultado negativo espacial, PNLD. Os apêndices ficam com o E6 completo, as sensibilidades e o dicionário de dados. O link público dos dados e do repositório é exigência da banca.

9. Riscos e cuidados

Vazamento temporal

Razões de progressão, α e iterações do EM aprendidos fora do treino. Teste automatizado é obrigatório.

Múltiplas bases com filtros diferentes

O erro que já aconteceu: pública+privada contra só-pública. Antídoto: tudo deriva de observacoes.parquet e é proibido ler CSV legado em análise nova.

Rankings instáveis

Último ano vence num bloco, suavização exponencial noutro, naive em Maceió. Nunca alegar campeão universal — sempre segmentar.

MAE sem WAPE

Superestima o fenômeno das transições. A decomposição é obrigatória.

EM escalonado

Cobertura baixa no 1º EM é esperada. Reportar como achado; não forçar a série a existir.

GPR extrapolado

Cerca de 5% em um município não sustenta um método proposto nacional. A linguagem é prova de conceito.

Excesso de experimentos

E7 e E9 só depois do P0 completo. O congelamento vale mais que qualquer experimento extra.

Snapshot de dependência de 2025

Viés de sobrevivência. Mitigar com dependência por ano se os microdados permitirem; senão, declarar.

Cobertura nivelada nas pareadas

A interseção é limitada pela escalonada. Reportar cobertura sempre.

OneDrive e arquivos grandes

Trabalhar com cópia local do diretório de dados durante as execuções; o Parquet reduz o I/O.

Números antigos no texto

Nenhum valor do Capítulo 5 atual sobrevive sem reprocessamento. Manter uma lista de números a substituir.

10. Ordem de ataque

Sequência imediata

Validar a proposta de encaminhamento com a orientação, colhendo as respostas dos sete pontos de validação.
Congelar este guia como referência, ajustando depois da reunião.
Inventariar o repositório antes de mexer no código.
E0 — sanity checks da base bruta, incluindo a decisão entre dependência por ano e snapshot.
Construir observacoes.parquet e mapa_transicoes_etapas.csv (módulo 10, copiando a cadeia do config.py da Validação Transição).
E1 — reprocessamento só-públicas do núcleo; primeiro run canônico no registry.
E-EM — a tentativa única de reconstrução da escalonada do EM.
Módulo 20 e E5, que alimentam a SP3 e o texto de caracterização.
E2 a E4 e E6 sobre o run canônico completo.
E8 como pós-processamento; decidir E7 e E9 conforme o calendário.
Congelamento dos experimentos. Depois, só escrita.