Métodos · Entrega de análise
Como entregar um pacote de análise de investigação reproduzível
Entregar não é apenas enviar um ZIP: é definir um percurso verificável das entradas autorizadas aos resultados especificados. Registe versões, ordem, ambiente e critérios; execute numa pasta separada e documente diferenças.
Para materiais públicos ou sintéticos cujo uso esteja autorizado: explica onde um colaborador começa e como verifica resultados. A revisão antes da submissão trata da coerência no manuscrito; esta página trata de regenerar resultados com os mesmos materiais e código.
Usamos a definição de The Turing Way: reprodutibilidade computacional com os mesmos dados e etapas de análise. A terminologia varia entre áreas. Uma reexecução não substitui validação com novos dados, robustez com outros métodos nem generalização.
Uma estrutura mínima com função explícita para cada ficheiro
Os nomes são sugestões didáticas, não software obrigatório nem formato de exportação RigorMed. Adapte ao projeto e explique como obter entradas e produzir saídas.
| Local ilustrativo | O que registar | Verificação de quem recebe |
|---|---|---|
| README | Âmbito, permissões, entrada, ordem, saídas esperadas, condições de paragem e papel de contacto | Começo e limites sem explicação oral |
| inputs/ e data-dictionary | Versão da fonte ou ID de ficheiro, caminhos relativos, unidades, códigos e valores em falta; acesso legal se redistribuição proibida | Entradas acessíveis correspondem à versão analisada |
| scripts/ e analysis-plan | Ordem de limpeza, análise e tabelas/figuras; parâmetros e critérios de elegibilidade | Etapa geradora para cada resultado, não números copiados |
| environment | Versões reais de SO, linguagem e pacotes, instalação; sementes, threads e limites de hardware se relevantes | Execução no ambiente declarado, não apenas “versão mais recente” |
| expected/ e output-map | Ficheiros previstos, mapa de tabelas/figuras, campos e tolerâncias predefinidas | Concordância de conteúdo, não existência ou arredondamento semelhante |
| rerun-record | Data, ambiente, etapas, estado de saída, diferenças e pendências reais | Separar não executado, falha, aprovação parcial e âmbito verificado |
Remova segredos, tokens, caminhos pessoais absolutos e materiais por linha que não possam ser partilhados. Separe licença do código, condições dos dados e restrições de acesso. Poder descarregar não autoriza redistribuir.
Inventariar e reexecutar sem reutilizar resultados antigos
Fixar os resultados-alvo
Identifique versão de manuscrito ou análise, tabelas/figuras principais e plano. Não misture exploração com resultados formais. Registe materiais ausentes e direitos incertos; não reconstrua dados brutos do artigo.
Ligar entradas, etapas e saídas
Por tabela ou figura, registe entradas, scripts geradores, parâmetros e destinos. Use caminhos relativos e dependências explícitas. Decisões manuais exigem regras e registos reais, não a designação automática.
Documentar ambiente e entrada executáveis
O README deve conter comandos de instalação e execução realmente testados pelo autor, pasta de trabalho e ordem. Não inventamos um comando universal. Uma semente não garante igualdade bit a bit entre software, threads ou hardware.
Executar numa pasta nova
Preserve originais e saídas formais; guarde novos resultados separadamente. Copiar expected/ não é um novo cálculo. Fontes em linha exigem versões fixas e aquisição legal, não ligações privadas mutáveis.
Comparar segundo critérios prévios
Verifique primeiro amostras, denominadores, variáveis, modelos e unidades de efeito; depois estimativas, intervalos e dados de tabelas/figuras. Separe diferenças não científicas como datas. Não alargue tolerâncias após ver discrepâncias.
Registar falhas antes da entrega
Guarde execução e diferenças. Entradas ausentes, dependências falhadas ou resultados-chave diferentes suspendem conclusões afetadas: não preencha zeros nem edite saídas para coincidir. Ficheiros sem execução ficam pendentes; um sucesso não certifica outros ambientes nem qualidade.
Fragmento sintético: mais específico do que “gerou um CSV”
Uma entrada didática própria tem uma coluna x e 5 linhas: 1, 2, 3, 4 e vazio. Só neste exercício aritmético se predefine média dos não ausentes, sem imputação: total 5, válidos 4, ausente 1, média 2.5. Não são pacientes, resultados reais, recomendação estatística ou execução do produto.
O mapa pode ligar n_total/n_valid/n_missing/mean_x de summary.csv às verificações README. O registo documenta comandos, ambiente e comparação reais. Criar um ficheiro com 2.5 não demonstra execução do cálculo.
Se a média for 2.0, verifique se o vazio virou 0; se houver 5 válidos, examine leitura e pré-processamento. Não altere primeiro o esperado. São necessárias regras e denominadores, não apenas uma tabela parecida.
Pedir à IA que organize lacunas, não que declare sucesso
Materiais sugeridos: inventário autorizado, dicionário público ou sintético, README existente, instruções confirmadas e resumo de execução sem informação sensível. Não envie linhas de pacientes, credenciais ou textos que não possa partilhar para organizar uma lista.
Pedido adaptável: apenas com os materiais fornecidos, redigir tabela e README ligando resultado-alvo—versão/local de entrada—etapas/parâmetros—saída—campos de aceitação—lacunas. Se faltam comandos, versões ou prova de execução, marcar por confirmar; não inventar ambientes, resultados ou aprovações.
Propõem-se mapa de entrega, rascunho README e perguntas pendentes; não são execução real nem resultado de cliente. Executar código específico exige avaliação separada de materiais, capacidade, direitos e confirmação prévia.
Cinco perguntas ao entregar
Cinco perguntas ao entregar
- É possível obter legalmente a mesma entrada, com dicionário e parâmetros claros?
- Cada saída-chave tem etapa geradora, não um ficheiro manual na máquina do autor?
- Ambiente, comandos e ordem foram testados, com partes não testadas assinaladas?
- Compararam conteúdo, denominadores, unidades e tolerâncias prévias, não só código 0 ou existência?
- Falhas, tarefas não executadas, passos manuais e partes não públicas foram registados com honestidade?
Um percurso reproduzível não prova desenho adequado, controlo de viés, autorização nem validade causal. As políticas PLOS aplicam-se a esse sistema editorial, não automaticamente a todas as revistas. Explique restrições e acesso legal conforme a política aplicável, sem divulgar dados sensíveis.
Fontes verificadas
As fontes oficiais foram verificadas em 2026-10-21; condições e datas são revisadas antes da publicação.
- The Turing Way: definições de reprodutibilidade
Mesmos dados e etapas face à validação com novos dados; terminologia variável.
- PLOS: partilha de materiais, software e código
Código, documentação, dependências, materiais de teste e restrições no âmbito da política.
Reprodutibilidade e entrega de investigação
Transformar materiais existentes numa entrega verificável
No espaço RigorMed descreva permissões, ficheiros e questão de entrega e adapte o pedido acima. Confirme âmbito suportado e produtos reais; depois verifique fontes, execução e diferenças. Organizar uma lista não é concluir uma reexecução.