34 Pacotes de Pesquisa Abertos e Reutilizáveis
Este capítulo faz parte de um livro em desenvolvimento ativo e ainda não passou pela revisão do autor. O conteúdo pode mudar conforme a revisão avança.
A decisão de pesquisa. Decida o que entra na cápsula de reprodutibilidade que acompanha a sua nota de pesquisa e defenda a alegação de que uma pessoa desconhecida consegue rodar o seu trabalho de novo e obter os seus números. Você é dono do que o pacote inclui e de saber se “isto se reproduz” é honesto, e você nunca deixa uma execução limpa passar por uma execução correta.
34.1 Por que essa decisão importa
A decisão em jogo: o que vai dentro da cápsula que acompanha o seu trabalho, e se a frase “isto se reproduz” é honesta quando você a escreve.
“Não quero ouvir que roda no seu computador. Me entregue a pasta, me deixe limpar tudo e me deixe apertar o botão. Se o seu número principal não voltar na minha máquina, você ainda não tem um resultado. Você tem a lembrança de um.” — um editor de replicação, abrindo a pasta anexada à sua submissão
Uma nota de pesquisa argumenta a sua alegação em prosa. A cápsula prova que a alegação sobrevive sem você na sala. Se o único lugar em que a sua análise roda é o computador onde você a construiu, na ordem de cliques que por acaso você lembra, então ninguém consegue conferir o seu trabalho, e um resultado que ninguém consegue conferir é um boato com um gráfico. Este capítulo é sobre empacotar o trabalho de modo que conferir seja fácil, e sobre continuar honesto quanto ao que “reprodutível” realmente quer dizer.
34.2 O conceito
Uma cápsula de reprodutibilidade é tudo o que uma pessoa desconhecida precisa para reconstruir os seus números e nada que ela tenha de adivinhar. Exemplo: uma pasta com o seu notebook, os seus dados e um registro curto de cada escolha feita à mão. Ela tem cinco partes, cada uma definida uma vez.
- Um notebook executável que passa no restart-and-run-all (reiniciar e rodar tudo), ou seja, você limpa o kernel e roda cada célula de cima a baixo, sem nenhuma memória de cliques anteriores. Exemplo: Runtime, Restart and run all, e o seu número principal reaparece.
- Uma nota de proveniência dos dados: de onde veio cada conjunto de dados, qual é a versão dele e como ele pode ser usado. Exemplo: a URL de download, a data e a licença.
- Uma semente fixa, um número de partida que faz cada passo aleatório devolver os mesmos valores em toda execução. Exemplo:
SEED = 464alimentando cada reamostragem. - Um registro de decisões: as escolhas feitas à mão que moldaram o resultado, cada uma com o seu motivo. Exemplo: cada linha que você descartou, e por quê.
- Um registro de uso de IA, o seu AI Research Ledger (registro de pesquisa com IA): cada ferramenta, a tarefa dela e como você verificou a saída.
Cápsulas quebram de maneiras entediantemente previsíveis, e isso é uma boa notícia, porque uma falha previsível é uma falha que se pega. Batizadas, elas são os cinco pecados de pacote: um caminho fixo no código que só existe na sua máquina, uma semente ausente que move cada execução, uma edição feita à mão que nenhuma execução limpa reproduz, uma exclusão não documentada sem motivo registrado, e dados desatualizados que a pessoa leitora não consegue obter de novo. O auditor do laboratório procura os cinco. Mas segure firme a linha que carrega o capítulo inteiro: uma cápsula com zero alertas é executável, nunca comprovadamente correta. A varredura leva você até a linha de largada. Quem roda o seu trabalho a frio é a corrida.
34.3 Um exemplo trabalhado
Você reuniu o comparecimento eleitoral por seção em doze condados, na eleição de meio de mandato de um estado, e o seu destaque é a fração de seções em que o comparecimento ficou abaixo de 40%. Observe a mesma análise entregue de duas formas.
A cápsula pecadora carrega ~/Desktop/turnout_clean.csv, um arquivo que só o seu computador tem. Ela faz bootstrap de um intervalo de confiança para essa fração sem semente, então o intervalo muda a cada execução. Ela corrige à mão um nome de seção duplicado, em uma célula que nenhuma execução limpa repete. Ela descarta em silêncio toda seção cuja contagem de eleitores registrados estava faltando, sem nota sobre o motivo. E os dados dela foram baixados “lá pela primavera passada”, antes de o estado certificar a apuração, sem nenhuma versão registrada. Cinco pecados, e cada um deles quebra a reexecução.
A cápsula limpa carrega o arquivo certificado pela URL pública dele, com a fonte, a data do download e os termos de uso na nota de proveniência. Ela fixa SEED = 464 antes do bootstrap. Ela registra a única renomeação no registro de decisões, com o motivo. Ela mantém as seções com contagem de registro faltante, ou as descarta por uma regra registrada e declarada de antemão. Agora uma pessoa desconhecida limpa o kernel, roda de cima a baixo, e a sua fração de seções abaixo de 40% volta. Mesmo número, sem adivinhação.
Aqui está a checagem de honestidade que o auditor não faz por você. A cápsula limpa ainda pode estar errada: a sua semente pode estar fixada no subconjunto errado, ou descartar as seções sem contagem de registro pode ser uma regra ruim, registrada com capricho. Executável não é correto. Essa distância é exatamente o motivo de a sua cápsula ser exercitada por uma pessoa, e não só por um script.
34.4 O laboratório no Colab
Este capítulo tem o seu próprio notebook companheiro — abra-o no Colab pelo selo acima. O notebook reúne os prompts e o código do capítulo e termina com o espaço de trabalho Agora é a sua vez, para você completar a etapa do capítulo no seu projeto sem sair do Colab. O laboratório completo de sala de aula por trás deste capítulo é o notebook do curso nb15 — From poster to research note (abrir no Colab), parte do curso companheiro apresentado no apêndice Para instrutores. Lá você constrói o audit_capsule, vê a função sinalizar os cinco pecados em um pacote quebrado de propósito e nenhum em um pacote limpo, e depois cola as linhas principais da sua própria cápsula e corrige o que ela pegar.
34.5 Prompts de IA recomendados
Comprometa-se primeiro com a sua própria resposta, depois delegue. Empacotar é um loop que você vai rodar mais de uma vez: você pergunta, conserta o que volta, roda a cápsula a frio outra vez, e essa reexecução revela a próxima lacuna. Algumas ferramentas hoje rodam esse loop sozinhas, editando arquivos e reexecutando até nada dar erro. Um loop que termina sem erros provou que o código roda. Ele não provou que os números estão certos, e só você consegue perceber a diferença. Cada prompt é uma tarefa verificável, não um veredito.
Localize a ferramenta padrão.
Act as a reproducibility assistant. Name the standard file and format for recording
the exact package versions a notebook needs in order to rerun, and cite the official
documentation. Only name tools you are confident exist.Depois de rodar, verifique: abra a documentação oficial e confirme que o arquivo e a sintaxe dele existem. Combate a fabricação confiante (um nome de ferramenta inventado chega com a mesma confiança de um real).
Liste para você poder verificar (a pessoa que replica a frio).
Here are the key lines of my capsule: [paste]. Playing a replicator who has only
these lines and none of my memory, list every input, file, or by-hand step you would
need to rerun my headline number and might not find here.Depois de rodar, verifique: case cada lacuna apontada com o que a sua própria execução do audit_capsule de fato sinalizou, e descarte qualquer lacuna que não corresponda a nenhuma linha realmente faltante. Combate a ilusão de completude (uma cápsula arrumadinha que parece inteira enquanto um insumo está faltando).
Faça red team (revisão adversária) da alegação.
My claim is: "a stranger can rerun this capsule and get my number." Act as a hostile
replication reviewer and name every way it could fail on a machine that is not mine.
Do not fix it for me.Depois de rodar, verifique: se a resposta só tranquilizar você, insista e exija a pior falha isolada. Combate a concordância bajuladora (elogio que revisa o seu ego, não o seu pacote).
Você decide o que entra na cápsula e se a frase “isto se reproduz” é honesta. A ferramenta pode listar lacunas e fixar versões, mas não consegue registrar a proveniência verdadeira dos seus dados, julgar se o motivo registrado de uma exclusão é um bom motivo, nem certificar que a sua análise está correta em vez de apenas executável. O nome na pasta, e a alegação de que uma pessoa desconhecida pode confiar nela, são seus.
34.6 Um caso de falha da IA
Você cola o seu notebook na sua IA e pergunta: “isto vai rodar a frio e produzir a minha fração de comparecimento baixo?”. Ele percorre cada célula e responde, com total confiança: “Sim, isto roda de cima a baixo sem problemas e devolve o seu número principal”. Soa como um sinal verde. Não é. A IA não executou nada. Ele leu o código e narrou. A célula 3 carrega ~/Desktop/turnout_clean.csv, um caminho que só o seu computador tem, e a explicação fluente descreveu a leitura desse arquivo como se ele estivesse ali.
Você pega o erro do único jeito que vale: você de fato roda o restart-and-run-all em um kernel novo, de preferência no Colab, em uma máquina que não é a sua. O FileNotFoundError aparece na célula 3 em segundos. Uma execução narrada não é uma execução. Você verifica o notebook executando-o, não lendo um parágrafo sobre executá-lo.
34.7 Agora é a sua vez
O seu projeto já tem uma nota de pesquisa e uma pasta que roda; este passo transforma as duas em uma cápsula que alguém poderia pegar daqui a um ano e reutilizar.
- Monte as cinco partes para o seu próprio projeto: o notebook executável, a nota de proveniência dos dados, a semente fixa, o registro de decisões e o seu registro de uso de IA. Tudo o que a pessoa leitora teria de adivinhar pertence a uma das cinco.
- Rode a auditoria do capítulo nas suas próprias linhas principais e corrija o que ela sinalizar, começando pelo pecado que você mais teve vontade de deixar quieto. Caminhos fixos no código e sementes ausentes são os dois que mais quebram para quem chega de fora.
- Escreva o README que uma pessoa desconhecida lê primeiro: o que o projeto pergunta, qual é o número principal, qual arquivo o produz e em que ordem rodar as coisas.
- Rode tudo de novo a frio em um segundo ambiente, uma sessão limpa do Colab ou uma máquina que não é a sua, e confira se o número principal volta dentro do arredondamento. Um número que viaja é reprodutível. Um número que não viaja quer dizer que algo carregado por você à mão fazia um trabalho silencioso que nunca foi empacotado.
- Escreva uma frase honesta sobre o limite de tudo isso: a sua cápsula é executável, o que não é a mesma coisa que correta, e nomeie a escolha dentro dela que você mais gostaria que um revisor questionasse.
- Registre a rodada de empacotamento no seu AI Research Ledger, e verifique pelo menos um resultado com um método nomeado do Guia de Verificação. Um revisor de IA pode rodar a checagem com você; a decisão de aceitar ou rejeitar continua sendo sua.