AlertTools 1.2.0 release candidate

[BaruqueRodrigues]

Resultado

Prepara a release candidata 1.2.0 com a refatoração das fases 0–7: baseline reproduzível, camada DBI explícita, núcleo em memória, API snake_case, wrappers de compatibilidade, documentação, CI e gate de migração dos consumidores.

Validação local

• 258 testes passaram; 1 integração PostgreSQL opt-in foi ignorada
• cobertura 57,96%
• lintr sem ocorrências
• pkgdown construído
• R CMD check: 0 errors, 0 warnings, 0 notes

Compatibilidade e rollout

• wrappers legados permanecem disponíveis
• janela aprovada: pelo menos duas releases minor e seis meses a partir dos warnings formais da 1.3.0
• remoção continua bloqueada por consumidores críticos
• nenhuma conexão global ou acesso a produção foi reintroduzido

O branch será usado como revisão fixa nos PRs de migração dos consumidores antes da release principal.

[esloch]

Olá, @BaruqueRodrigues. Obrigado pelo trabalho nesta refatoração.

Sempre que possível, trabalharmos com PRs menores, com responsabilidades bem definidas. Isso facilita a revisão, permite identificar regressões com mais precisão e simplifica bastante o rollback quando alguma alteração apresenta problemas.

Neste PR estamos reunindo mudanças de arquitetura, nova API pública, compatibilidade com funções legadas, acesso ao banco, paralelismo, testes, CI, documentação e política de migração.

São alterações importantes, mas que poderiam ser introduzidas e validadas progressivamente. Quando tudo chega no mesmo PR, fica mais difícil distinguir uma melhoria interna de uma mudança de comportamento que afeta outros componentes.

Revisei o PR em relação ao master atual do AlertTools e também o fluxo do AlertaDengueAnalise, principalmente o main/main_BR.R.

A direção da refatoração faz sentido. Separar leitura, processamento e persistência é uma evolução importante para o pacote. Minha preocupação está em garantir que essa evolução não altere contratos existentes sem a devida validação e que a nova API seja consistente para qualquer consumidor, não apenas para o AlertaDengueAnalise.

Alguns pontos de atenção:

1. Compatibilidade com a API legada

Este é o principal bloqueador de migração que identifiquei.

No master, pipe_infodengue() utiliza datasource = con e tabela_historico() utiliza versao = Sys.Date().

No PR, esses argumentos passam a ser obrigatórios.

O problema é que o AlertaDengueAnalise/main/main_BR.R continua utilizando as duas funções sem informar esses argumentos.

ale <- pipe_infodengue(
  cidades,
  cid10 = cid10,
  nowcasting = now_mode,
  finalday = report_end_date,
  narule = "arima",
  iniSE = 201001,
  dataini = "sinpri",
  completetail = 0
)

restab <- tabela_historico(
  ale,
  iniSE = report_epiweek - window_weeks
)

Com a versão proposta, a execução falha inicialmente na validação de datasource. Corrigindo isso, ainda teríamos a exigência de versao.

O consumidor também possui um mecanismo de recuperação que executa os municípios individualmente quando o processamento estadual falha. Porém, esse caminho utiliza os mesmos argumentos e também seria afetado.

Concordo com a exigência de conexões e datas explícitas na nova API. É uma decisão correta para melhorar o controle das dependências.

Entretanto, precisamos preservar a compatibilidade dos wrappers legados enquanto existirem consumidores que dependem desses contratos.

O próprio consumer-registry.csv identifica o main_BR.R como consumidor crítico, ainda não migrado.

O AlertaDengueAnalise atualmente fixa o AlertTools no commit e460b3b8, portanto o merge deste PR não interromperia automaticamente a imagem atual. A incompatibilidade apareceria na atualização dessa dependência.

Minha sugestão é manter o contrato legado durante a transição e validar a migração dos consumidores antes de remover ou alterar esse comportamento.

2. Parâmetros de Zika

O comportamento dos parâmetros de Zika também merece atenção.

Na implementação atual, existe um fallback que utiliza os parâmetros de dengue quando o CID10 não corresponde a dengue ou chikungunya.

No PR, o pipe_infodengue() passa a utilizar:

fetch_alert_parameters(
  conn = datasource,
  geocodes = cities,
  disease = cid10
)

A nova consulta procura especificamente os parâmetros de A92.8.

Se não houver parâmetros cadastrados para todos os municípios solicitados, a execução será interrompida.

Considero mais correto que a nova API trabalhe com parâmetros específicos de cada doença. Entretanto, precisamos verificar a disponibilidade desses dados e decidir como será feita a transição do comportamento anterior.

Sugiro incluir testes para Zika, cobrindo municípios com e sem parâmetros específicos, e confirmar qual comportamento deve ser mantido nas funções legadas.

3. Padronização dos geocódigos e identificação das doenças

Aqui identifiquei dois pontos relacionados.

O primeiro é a nomenclatura utilizada pela nova API.

Atualmente, cases$cidade representa o geocódigo numérico do município, não o nome da cidade.

No clima, o mesmo identificador é chamado de geocodigo, enquanto nos parâmetros utilizamos municipio_geocodigo.

Como estamos definindo uma nova API, considero importante padronizar essa nomenclatura.

Minha sugestão é utilizar municipio_geocodigo como identificador canônico do município, preservando os nomes anteriores apenas onde forem necessários para compatibilidade.

Isso deixa o contrato mais claro e mantém a mesma referência utilizada no banco de dados e nos demais componentes do InfoDengue.

O segundo ponto está na unidade de processamento.

new_alert_inputs() estabelece a chave dos casos como:

municipio_geocodigo + CID10 + SE

Entretanto, alerttools_pipeline() processa apenas por município:

cities <- unique(parameters$municipio_geocodigo)

Dentro de compute_city(), os casos e parâmetros também são selecionados apenas pelo geocódigo.

Se houver parâmetros de dengue e chikungunya para o mesmo município, o pipeline encontrará duas linhas de parâmetros e falhará.

Também existe o risco de processar conjuntamente séries de doenças diferentes quando apenas uma linha de parâmetros estiver disponível.

Precisamos definir se a API permitirá múltiplas doenças na mesma execução.

Se permitir, a unidade de processamento deverá considerar a combinação municipio_geocodigo e cid10.

Se cada chamada aceitar apenas uma doença, isso precisa ser uma restrição explícita, validada antes do cálculo.

O importante é que todas as validações, relacionamentos e restrições respeitem as chaves reais dos dados, sem depender de nomes textuais dos municípios.

4. Paralelismo e desempenho

A refatoração introduz workers para distribuir o processamento dos municípios.

Entretanto, esse mesmo valor também é encaminhado ao nowcasting e ao INLA.

Com workers = 8, por exemplo, podemos ter oito processos municipais, cada um solicitando oito threads ao INLA.

Isso pode gerar até 64 threads solicitadas nesses dois níveis, além do consumo de memória de cada processo.

O AlertTools deve ser independente da arquitetura de execução do AlertaDengueAnalise. Não considero adequado restringir o pacote à configuração utilizada atualmente nesse consumidor.

Pelo contrário, a nova estrutura deveria permitir utilização eficiente em diferentes ambientes, inclusive em execuções estaduais, nacionais e em outros projetos.

Minha sugestão é separar os controles de concorrência, por exemplo:

municipality_workers = 4
inla_threads = 1

Esses valores são apenas ilustrativos. Precisamos definir padrões seguros e verificar os melhores resultados por meio de benchmarks.

Também seria importante avaliar o overhead de criação dos processos, compartilhamento ou cópia de dados, uso de memória e tempo total de execução.

O ideal é permitir que cada consumidor ajuste a concorrência conforme os recursos disponíveis, sem que o próprio AlertTools crie paralelismo aninhado excessivo.

No caso do AlertaDengueAnalise, que já distribui o trabalho entre estados, precisaríamos considerar o custo total de recursos dos três níveis de execução.

5. Política de depreciação

O transition-policy.dcf estabelece o início dos warnings na versão 1.3.0.

Entretanto, a implementação utiliza:

lifecycle::deprecate_warn(
  "1.1.0",
  ...
)

O guia de migração também informa que a depreciação começou na versão 1.1.0.

Precisamos alinhar a documentação e a implementação com a política aprovada.

Como estamos preparando a versão 1.2.0, considero importante resolver essa divergência antes da release.

6. Compatibilidade de setCriteria()

No master, o argumento delays possui como padrão uma lista com três configurações.

No PR, o valor padrão passa a ser:

delays = 3

Entretanto, a implementação interna ainda acessa os três elementos individualmente para construir critérios personalizados.

Isso modifica o contrato anterior e pode causar erros ou resultados diferentes dependendo da regra utilizada.

O próprio guia de migração informa que delays foi preservado.

Sugiro manter o comportamento anterior no wrapper legado e definir separadamente o contrato de define_alert_rules().

7. Parâmetro minimum_history

A nova API expõe:

classify_alerts(
  ...,
  minimum_history = 8
)

Entretanto, a lógica relacionada ao antigo argumento dy continua comentada.

Não considero isso uma regressão do algoritmo, pois esse comportamento já existia.

O problema é expor um novo argumento público que sugere controlar uma funcionalidade sem produzir efeito na classificação.

Sugiro documentar essa limitação ou retirar o argumento da nova API até que seu comportamento esteja definido e testado.

8. Validação dos dados de entrada

new_alert_inputs() valida a unicidade dos casos por município, doença e semana epidemiológica.

Também valida a unicidade dos dados climáticos por município e semana.

Entretanto, alerttools_pipeline() é exportado e aceita data.frames diretamente, sem aplicar todas essas validações.

Se existirem registros climáticos duplicados para o mesmo município e semana, o left_join() poderá multiplicar os registros.

Isso afeta diretamente os cálculos de incidência, Rt e classificação dos alertas.

Minha sugestão é centralizar as validações e garantir que todos os pontos de entrada públicos respeitem as mesmas invariantes.

Outra possibilidade é manter alerttools_pipeline() como função interna, utilizando run_alert_pipeline() como interface pública.

9. Validação dos resultados epidemiológicos

Este ponto considero tão importante quanto a compatibilidade da API.

A refatoração altera o fluxo de leitura dos dados, processamento do nowcasting, cálculo dos indicadores e estrutura dos resultados.

Mesmo que os testes passem e a execução termine sem erros, precisamos confirmar que os resultados epidemiológicos permanecem equivalentes quando utilizamos os mesmos dados e parâmetros.

Sugiro comparar a versão atual e a versão candidata utilizando uma base controlada, verificando:

1. Casos notificados e estimados.
2. Incidência por 100 mil habitantes.
3. Estimativas de Rt e probabilidades associadas.
4. Classificação dos níveis de alerta.
5. Comportamento nas semanas com dados climáticos ausentes.
6. Estrutura e conteúdo do histórico gerado.

Para os componentes estocásticos, podemos utilizar sementes fixas e tolerâncias previamente definidas, já que nem todos os resultados precisam ser numericamente idênticos.

Também precisamos validar o formato dos objetos produzidos pelo pacote.

O pipe_infodengue() passa a retornar alerttools_result, enquanto o contrato anterior utiliza objetos alerta organizados por município.

O conversor histórico já possui adaptações, mas precisamos verificar os consumidores que acessam diretamente a estrutura dos resultados.

O objetivo é garantir não apenas que o novo código execute, mas que preserve o comportamento esperado.

10. CI e validação dos consumidores

O workflow associado ao commit revisado está passando, o que demonstra que os testes configurados para o pacote estão sendo executados com sucesso.

Entretanto, o check-migration-readiness.R valida principalmente o registro de consumidores, seus estados de migração e as referências internas à API legada.

Ele não executa o pipeline atual do AlertaDengueAnalise utilizando a versão candidata.

Isso significa que temos validação interna do pacote, mas ainda não temos uma validação integrada suficiente para confirmar a compatibilidade operacional.

Sugiro acrescentar uma execução representativa do consumidor principal com a versão candidata, utilizando um banco descartável e comparando os resultados com a versão atualmente utilizada.

Essa validação também deveria considerar os artefatos .RData, SQLs gerados e o comportamento do pipeline nos casos de falha e recuperação por município.

Considerações finais

O AlertTools deve continuar sendo um pacote independente, reutilizável e capaz de atender diferentes consumidores. Por isso, considero importante que os contratos públicos, as chaves dos dados e os controles de paralelismo sejam definidos pensando no pacote como um todo, e não apenas na execução atual do AlertaDengueAnalise.

Minha sugestão é priorizar a compatibilidade dos wrappers legados, a consistência do processamento por município e doença, o tratamento dos parâmetros de Zika e o controle do paralelismo.

Também considero necessária uma comparação dos resultados epidemiológicos antes de aprovar a migração.

Os demais pontos podem ser corrigidos neste PR ou organizados em entregas menores, desde que não comprometam a compatibilidade e a release.

Para as próximas etapas, é melhor que avancemos com PRs menores e objetivos mais específicos. Assim conseguimos revisar, testar e integrar cada mudança com mais segurança, sem concentrar tantas alterações de comportamento em uma única entrega.

Com esses ajustes, acredito que podemos aproveitar a base construída neste PR e avançar com a nova API sem comprometer os consumidores atuais.

[esloch]

A few points need attention before merging.