Exportações de análise

dispatchatlas.analytica transforma repositórios de campanhas concluídas em resumos estatísticos, figuras determinísticas, pacotes de evidência e conjuntos de dados prontos para o portal. O pacote consome manifestos JSON estáveis e não importa o tempo de execução da campanha.

Exemplo executável: examples/analyze_results.py resume um conjunto de resultados com estatística não paramétrica, tamanhos de efeito, intervalos de confiança, tabelas determinísticas e figuras de duplo formato.

📥 Entradas

O carregador de análise espera um diretório de campanha contendo:

• checkpoint.json com ids de execuções concluídas, falhas e pendentes.
• plan.json com a ordem de execução e os rótulos de divulgação.
• environment.json com fatos de ambiente não secretos.
• results/*.json linhas de execuções concluídas.
• failures/*.json linhas de tentativas falhas quando presentes.

Pontos de verificação, hashes de conteúdo, valores de objetivo ou rótulos de divulgação ausentes fazem a ingestão falhar antes de a análise começar.

📊 Métodos estatísticos

Um registro de métodos nomeados declara cada método de análise com seus pressupostos de dados, sua regra de amostra mínima, seu modo de falha e seu nível de evidência mais baixo. Cada método inferencial e indicador de qualidade requer ao menos 30 execuções independentes por célula estocástica solver-instância; uma amostra abaixo-do-piso é roteada para a superfície de limitações em vez de produzir um resultado inválido.

Para cada objetivo, a camada de resumo reporta contagens de solver, contagens viáveis, média, mediana, desvio padrão, intervalos de confiança por bootstrap corrigido-por-viés e acelerado (BCa), o teste de Wilcoxon dos postos sinalizados com os tamanhos de efeito A12 de Vargha-Delaney e delta de Cliff para comparação por pares, o teste ômnibus de Friedman com um post-hoc de diferença-crítica de Nemenyi sobre o campo multi-solver, correção de Holm ou Hochberg sobre a família por pares, e postos médios por problema de benchmark. Frentes multi-objetivo reportam adicionalmente os indicadores de qualidade hipervolume (primário), IGD+, epsilon-indicador aditivo e dispersão.

O objetivo padrão é makespan com semântica de minimização. O teste de Wilcoxon usa a distribuição nula exata para amostras pequenas sem empates e a aproximação normal corrigida-por-empates caso contrário. Os intervalos de confiança usam reamostragem bootstrap determinística com uma semente registrada; eles descrevem a amostra de campanha observada e não são por si sós afirmações de campanha completa.

Ao lado do teste de sinal bayesiano de forma fechada, bayesian_signed_rank_test extrai um posterior de processo de Dirichlet semeado sobre as médias de Walsh das diferenças emparelhadas, de modo que métricas contínuas ganham a comparação bayesiana ciente-de-magnitude de Benavoli, Corani, Demšar e Zaffalon (2017); o teste de sinal permanece o padrão de forma fechada. A família de comparação-múltipla adiciona o procedimento estático descendente de Shaffer, que explora as restrições lógicas de uma família de comparação de todos-os-pares completa e falha fechando sobre uma parcial (Shaffer 1986), e o ajuste descendente de Finner, um ganho de potência mais simples que aceita qualquer família (Finner 1993); Holm permanece o padrão configurado. O desvio percentual relativo junta-se aos métodos de lacuna-de-otimalidade: arpd_rows pontua cada execução viável contra um valor de referência melhor-conhecido fornecido pelo chamador com proveniência explícita, e ensure_equal_budgets verifica o protocolo de orçamento-igual escalado-por-tamanho por trás dele — um orçamento idêntico por problema entre solvers, orçamentos livres para crescer com o tamanho da instância (Vallada, Ruiz e Framiñan 2015). Comparações de hipervolume multi-objetivo arquivam seu ponto de referência compartilhado: multiobjective_indicator_report deriva o ponto sob uma regra nomeada — o padrão de fração-de-margem ou a escala ishibuchi-h — registra o ideal, o nadir, a regra, o parâmetro e um vocabulário de proveniência que falha fechando em um ReferencePointRecord, e ensure_shared_reference_points recusa comparar artefatos cujos pontos arquivados diferem (Ishibuchi, Imada, Setoguchi e Nojima 2018; o deslocamento publicado exato permanece marcado APPROXIMATE à espera do texto completo revisado-pelo-operador). Uma regra rígida guarda cada tabela exportada: um valor-p nunca é entregue sem um tamanho de efeito e um intervalo a seu lado. ensure_effect_sizes_beside_p_values verifica os cabeçalhos dentro dos construtores de tabelas e novamente no momento da escrita do pacote, falhando fechando sobre qualquer coluna de significância nua (Carrasco, García, Rueda, Das e Herrera 2020).

🖼️ Figuras e tabelas

Os pacotes de evidência incluem tabelas Markdown para resumos de solvers, comparações por pares, rankings, cobertura de benchmarks e linhas inviáveis. As figuras SVG carregam metadados acessíveis title e desc para barras de ranking, perfis de desempenho, tendências de objetivo por ordem de execução, o diagrama de diferença-crítica de Nemenyi, compromissos tempo-qualidade, trajetórias de convergência, o balanço exploração-explotação, escalabilidade de tempo de execução por tamanho de instância, estabilidade de semente (coeficiente de variação), robustez (risco de cauda CVaR) e caracterização de benchmarks. Um manifesto de figuras registra o papel, a proveniência e a nota de acessibilidade de cada figura. Figuras que dependem de diagnósticos que uma campanha não registrou (tempo de execução, traço de convergência, diversidade de população, escala de instância) ou de múltiplas sementes (estabilidade de semente) renderizam um aviso de limitações. Um supplement/limitations.md reúne todo método roteado para limitações.

Reexecutar a mesma exportação contra as mesmas entradas produz as mesmas cargas úteis JSON, de tabela e de figura.

O perfil de desempenho de Dolan-Moré viaja com seu companheiro de Moré-Wild: data_profile_svg e data_profile_tex plotam a fração de células (solver, problema) resolvidas a uma acurácia-alvo dentro de um orçamento de grupos de avaliação — a adaptação em grupos-de-avaliação da unidade de gradiente-simplex — a partir dos mesmos traços de convergência que as figuras de convergência consomem, e um conjunto de dados sem traços é roteado para a figura de limitações. Perfis de desempenho que comparam mais de dois solvers carregam uma ressalva de interpretação em ambas as formas de saída: um perfil ordena cada solver apenas contra o melhor por-problema, de modo que a ordem relativa de solvers não-melhores não está implícita (Gould e Scott 2016).

⚖️ Comparação de plataformas

As exportações de comparação de plataformas renderizam linhas de capacidade de frameworks rivais, uma matriz de cobertura de riqueza-de-recursos, uma avaliação de ponte de lacuna-com-a-realidade e linhas de inspeção de artefatos. Cada linha carrega um rótulo de fonte-de-evidência (documented, measured, artifact-inspected, vendor-claim ou unsupported), e qualquer linha não suportada é roteada para uma superfície de limitações-e-trabalho-futuro. A exportação carrega uma linha de guarda permanente: as tabelas comparam capacidades, recursos e artefatos de plataforma, e não são afirmações de desempenho diretas — a evidência de desempenho vive nas exportações de análise estatística.

🥊 Corredor de comparação frente a frente

O corredor frente a frente compara um solver focal contra uma coorte base nomeada usando os mesmos testes não paramétricos nomeados, orienta cada linha para o solver focal, e condiciona uma afirmação de vence-a-coorte a que o solver focal mantenha o melhor posto médio e vença cada comparação por pares no nível de significância corrigido com o tamanho de efeito a seu favor. Construtores de tabelas de complexidade-algorítmica e de ameaças-à-validade de construto/internas/externas acompanham o corredor para o consumo em relatórios.

🔒 Política de divulgação

As exportações são filtradas através de políticas de divulgação executáveis:

• core permite apenas evidência central/pública.
• speed permite evidência central, de velocidade e pública.
• quality permite evidência central, de velocidade, de qualidade e pública.
• platform permite evidência de plataforma enquanto ainda bloqueia fonte redigida e termos de narrativa-obsoleta.

As linhas proibidas são excluídas da evidência e dos conjuntos de dados do portal e escritas em um manifesto de exclusões suplementar com o motivo.

🗂️ Layout do pacote

evidence-bundle/
  bundle.json
  tables/
    solver-summary.md
    pairwise-comparisons.md
    rankings.md
    benchmarks.md
    infeasible-rows.md
  figures/
    performance-profile.svg
    solver-rankings.svg
    run-order-trend.svg
    critical-difference.svg
    runtime-quality.svg
    convergence.svg
    characterization.svg
    exploration-exploitation.svg
    scalability.svg
    stability.svg
    robustness.svg
    figure-manifest.json
  supplement/
    exclusions.json
    limitations.md

bundle.json lista cada arquivo gerado e faz hash da carga útil canônica do manifesto, de modo que cada tabela, figura e suplemento permanece dentro de um único manifesto rastreado e endereçado-por-conteúdo.

⌨️ Comando

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core `
  --objective makespan `
  --portal

O comando escreve um pacote de evidência mais um conjunto de dados do portal opcional. O pacote de evidência inclui tabelas, figuras e exclusões suplementares. O JSON do portal inclui tags pesquisáveis, rótulos de divulgação, valores de objetivo, ids de execução e metadados de campanha ligados por hash. --target-dir deve resolver dentro de --authorized-output-root; a raiz autorizada padrão é o diretório de trabalho atual.

Execute uv run dispatchatlas export --help para descrições de opções e exemplos. Erros de entrada em tempo de execução imprimem uma mensagem de recuperação por padrão; passe --debug antes do subcomando quando um traceback de Python for necessário para o desenvolvimento.

📝 Andaimes de relatório

A camada de análise também transforma um pacote de evidência filtrado por divulgação em um andaime de relatório determinístico indexado por nível de evidência. Um ReportScaffoldSpec declara a afirmação de contribuição, a justificativa de design e os portões de afirmação; write_report_scaffold escreve o pacote de evidência mais um plano de seções abrangente, uma afirmação de contribuição, um livro-razão de portões-de-afirmação, e um relatório de redação sob report/. Cada seção se ancora a um artefato de evidência filtrado, e o andaime gerado é escaneado de modo que um mecanismo de nível posterior ou um marcador interno restrito faça a escrita falhar fechando.

Os portões de afirmação falham fechando: uma afirmação em nível de design abre incondicionalmente, enquanto uma afirmação comparativa permanece fechada até que uma comparação frente a frente vença a coorte com cada contagem emparelhada no ou acima do piso de potência estatística. Uma contribution_partition sobre os níveis de evidência prova uma contribuição de sobreposição-zero por nível, e redaction_report aceita um registro fornecido pelo chamador de modo que um rascunho não-público possa ser verificado sem que esse registro entre jamais na fonte publicada.

uv run dispatchatlas report `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\scaffolds\smoke-pilot `
  --authorized-output-root .\scaffolds `
  --tier core