weightflow: declarative, recipe-aware survey weighting in R

Resumo Técnico de weightflow: ponderação de levantamentos declarativa e consciente de receitas em R

Definição do Problema
A produção de pesos de análise para levantamentos complexos requer uma cascata hierárquica de ajustes: resolução de elegibilidade desconhecida, descarte de unidades fora de escopo, restauração de probabilidades de seleção dentro do domicílio, correção de não resposta e calibração para totais populacionais conhecidos. Um desafio crítico na prática atual é que, embora os estimadores pontuais (os pesos finais) sejam bem compreendidos, a estimativa da variância frequentemente falha ao não considerar o fato de que os estágios intermediários do processo de ponderação (por exemplo, modelos de não resposta, redistribuição de elegibilidade) são, eles próprios, estimados a partir da amostra. As ferramentas existentes em R (como survey, sampling, icarus, surveysd e svrep) abordam partes específicas deste fluxo de trabalho, mas carecem de um objeto unificado que trate todo o pipeline como uma entidade única e auditável. Consequentemente, os pesos de réplica frequentemente refletem apenas a incerteza do estágio final de calibração, ignorando a variabilidade introduzida pelos estágios estimados anteriores. Além disso, a metodologia é frequentemente implementada como uma sequência de scripts desconectados, tornando o processo difícil de auditar, reproduzir ou manter.

Metodologia
O artigo apresenta o weightflow, um pacote dependente de zero (base R) que implementa uma API declarativa e encadeável inspirada no framework tidymodels. A metodologia central separa a definição da estratégia de ponderação da sua aplicação:

1. API de Receita Declarativa: Os usuários definem um pipeline de ponderação como um objeto inerte usando weighting_spec() seguido por uma cadeia de funções step_*(). Esta "receita" pode incluir:

   • Tratamento de disposição: step_unknown_eligibility() (redistribuindo o peso entre casos resolvidos), step_drop_ineligible() (removendo unidades fora de escopo) e step_select_within() (restaurando probabilidades de seleção dentro do domicílio).
   • Ajuste de não resposta: Implementado via step_nonresponse() utilizando classes de ponderação ou modelos de propensão de resposta (regressão logística, CART, florestas aleatórias, gradient boosting). O pacote suporta cross-fitting para evitar o overfitting, garantindo que as pontuações de propensão sejam estimadas a partir de modelos treinados em diferentes dobras (folds) dos dados.
   • Calibração: step_calibrate() suporta raking (ajuste proporcional iterativo), pós-estratificação e calibração linear/GREG. Oferece várias funções de distância (linear, exponencial), limites (Deville–Särndal), penalização ridge para auxiliares colineares e variantes particionadas por domínio ou integrativas (um peso por domicílio).
   • Etapas de finalização: Trimming opcional (ex: corte otimizado pelo MSE de Potter) e arredondamento.

2. Estimativa de Variância Consciente da Receita: A principal inovação metodológica do pacote é a reexecução de toda a receita em cada réplica. Em vez de tratar os pesos finais como fixos, o weightflow aplica um bootstrap de reescalonamento ou um jackknife de delete-a-PSU onde toda a cascata de ponderação (incluindo modelagem de não resposta e calibração) é reestimada para cada réplica. Isso garante que a variância do estimador final capture a incerteza de todos os estágios estimados, não apenas do estágio final de calibração.

3. Diagnósticos: O pacote computa automaticamente o efeito de design de Kish e indicadores de representatividade (R-) para diagnosticar a dispersão dos pesos e riscos de viés de não resposta.

Principais Contribuições
O artigo identifica quatro contribuições principais:

1. Uma API de Receita Declarativa: Ao separar a definição preguiçosa (lazy definition) do pipeline da sua execução, o pacote torna a estratégia de ponderação um objeto permanente, auditável e transparente. A própria receita serve como um registro permanente das decisões metodológicas.
2. Variância Consciente da Receita: A implementação de métodos de bootstrap de reescalonamento e jackknife de delete-a-PSU que reaplicam a receita completa em cada réplica. Isso propaga a variabilidade dos estágios intermediários (elegibilidade desconhecida, não resposta, calibração) para os pesos de réplica.
3. Implementação Abrangente e Sem Dependências: O pacote fornece um conjunto completo de métodos de calibração (raking, pós-estratificação, GREG com várias distâncias e penalidades) e ajustes de não resposta (classes de peso e machine learning com cross-fitting) sem depender de dependências externas pesadas.
4. Diagnósticos Automáticos: Integração do efeito de design de Kish e indicadores R para avaliar automaticamente a qualidade do processo de ponderação.

Resultados e Validação
O artigo valida o pacote através de duas vias principais:

• Consistência Metodológica: Em métodos compartilhados, o weightflow reproduz os resultados do pacote estabelecido survey. Pós-estratificação, raking e calibração linear produzem pesos idênticos (dentro da tolerância numérica), e o jackknife de delete-a-PSU coincide com o jackknife de réplicas do survey para totais.
• Aplicação em Dados Reais (ECH Uruguaio): Os autores aplicaram o pipeline completo à Pesquisa Contínua de Hogares (ECH) de 2019 do Uruguai, simulando inelegibilidade e não resposta em 79.000 registros.
  • O estimador ponderado pela base apresentou um viés descendente acentuado (0,059 vs. o verdadeiro 0,0876) devido à não resposta entre estratos mais pobres.
  • O ajuste de não resposta recuperou parte do viés (0,068) e a calibração subsequente às margens de idade, sexo e região recuperou o restante (0,084), aproximando-se do valor real.
  • O bootstrap consciente da receita (1.000 réplicas) produziu um intervalo de confiança de 95% que cobriu com sucesso a taxa de pobreza real, demonstrando que o pipeline recupera parâmetros com incerteza "honesta".
  • Benchmarks de desempenho mostraram que preparar a receita em 79.000 registros leva 0,45 segundos, enquanto o bootstrap (reaplicando a receita completa 1.000 vezes) leva aproximadamente 344 segundos em um laptop padrão, tornando a inferência baseada em design completa viável em uma única máquina.

Significância
O artigo afirma que o weightflow preenche uma lacuna crítica no ecossistema R para estatísticas oficiais e prática de levantamentos. Sua significância não reside na proposta de novos estimadores pontuais, mas no fornecimento de um framework de variância consciente da receita que nenhum outro pacote oferece. Ao tratar toda a cascata de ponderação como um objeto único e explícito, o pacote garante:

• Auditabilidade e Reprodutibilidade: A metodologia não é mais implícita na ordem dos arquivos ou em ajustes não documentados, mas codificada em um único objeto inspecionável.
• Quantificação Precisa da Incerteza: Os erros padrão refletem a incerteza de todo o processo de estimativa, incluindo ajustes de não resposta e elegibilidade, em vez de apenas a calibração final.
• Ativo Institucional: A própria receita torna-se um ativo institucional duradouro que sobrevive a mudanças de pessoal, garantindo a continuidade metodológica.

O pacote é projetado especificamente para Institutos Nacionais de Estatística (INEs) e profissionais que exigem procedimentos de ponderação transparentes, reprodutíveis e estatisticamente rigorosos. Ele integra-se perfeitamente com os pacotes survey e srvyr para inferência descendente baseada em design.