dxda
0.6.2
Ferramenta CLI para gerenciar o download de grandes quantidades de arquivos do DNAnexus
NOTA: Esta é uma versão inicial desta ferramenta e está sendo testada em vários ambientes. Entre em contato com a DNAnexus se estiver interessado em verificar se esta ferramenta é apropriada para sua aplicação.
Para começar a usar dx-download-agent , baixe o binário pré-compilado mais recente na página de lançamento. O agente de download aceita dois arquivos:
manifest_file : um arquivo de manifesto JSON compactado em BZ2 que descreve, no mínimo, as seguintes informações para um download, por exemplo:
{ "projeto-AAAA": [
{ "id": "arquivo-XXXX", "nome": "foo", "pasta": "/caminho/para", "partes": { "1": { "tamanho": 10, "md5": "49302323" }, "2": { "tamanho": 5, "md5": "39239329" }
}
}, "..."
], "projeto-BBBB": [ "..." ]
}Para iniciar um processo de download, primeiro gere um token de API DNAnexus que seja válido por um período de tempo em que você planeja baixar os arquivos. Armazene-o na seguinte variável de ambiente:
exportar DX_API_TOKEN=
Se nenhum token de API for fornecido, o agente de download procurará ~/.dnanexus_config/environment.json também usado pelo dx-toolkit.
Para iniciar o download:
dx-download-agent download exome_bams_manifest.json.bz2 Obtained token using environment Creating manifest database manifest.json.bz2.stats.db Required disk space = 1.2TB, available = 3.6TB Logging detailed output to: manifest.json.bz2.download.log Preparing files for download Downloading files using 8 threads Downloaded 11904/1098469 MB 124/11465 Parts (104.0 MB written to disk in the last 60s)
Um relatório contínuo sobre o progresso do download é gravado na tela. Antes de iniciar a transferência de dados, é feita uma verificação para ver se há espaço em disco suficiente para toda a lista de arquivos. Caso contrário, um erro será relatado e nada será baixado. A velocidade de download reflete não apenas a largura de banda da rede, mas também a capacidade de E/S da sua máquina.
Um log de download contém informações mais detalhadas sobre o download caso ocorra um erro. Se ocorrer um erro e você não entender como lidar com ele, entre em contato com [email protected] com o arquivo de log anexado e nós o ajudaremos.
Observe que a nova execução do comando dx-download-agent download NÃO baixará novamente nenhum arquivo baixado anteriormente que tenha sido movido, excluído ou modificado posteriormente. Execute dx-download-agent inspect (descrito abaixo) para detectar quaisquer alterações nos arquivos baixados anteriormente e marcá-los para download novamente. Consulte Movendo arquivos baixados para obter mais detalhes.
Você pode consultar o progresso de um download existente em um terminal separado
dx-download-agent progress exome_bams_manifest.json.bz2
e você receberá um breve resumo do status dos downloads:
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
Para verificar a integridade dos arquivos baixados, você pode executar
dx-download-agent inspect exome_bams_manifest.json.bz2
Este comando realizará uma inspeção dos arquivos e garantirá que seus MD5sums correspondam ao manifesto. Se um arquivo estiver faltando ou um MD5sum não corresponder, o agente de download reportará os arquivos afetados e você poderá executar dx-download-agent download novamente para baixar novamente os arquivos afetados.
-num_threads (inteiro): número máximo de threads simultâneos a serem usados ao baixar ou inspecionar arquivos
Por exemplo, o comando
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
criará um pool de trabalhadores de 20 threads que baixará partes de arquivos em paralelo. Um máximo de 20 trabalhadores realizarão downloads a qualquer momento. A limitação da taxa de downloads pode ser controlada até certo ponto, variando esse número.
As informações sobre quais partes foram baixadas são mantidas em um arquivo de banco de dados sqlite3 que contém informações semelhantes ao que está no formato de arquivo JSON, além de um campo bytes_fetched adicional.
Nome da tabela: manifest_stats
Campos (todos os campos são strings, salvo especificação em contrário)
file_id : ID do arquivo para parte do arquivo
project : ID do projeto para parte do arquivo
name : nome do arquivo
folder : pasta contendo arquivo no DNAnexus
part_id (inteiro): ID da peça do arquivo
md5 : md5sum para ID da peça
size (inteiro): tamanho da peça
block_size (inteiro): tamanho do bloco primário do arquivo (assumido igual ao size exceto para a última parte)
bytes_fetched (inteiro <= size ): número total de bytes baixados
Cabe à implementação decidir se bytes_fetched é ou não atualizado de uma forma mais grosseira ou mais refinada. Por exemplo, bytes_fetched pode ser atualizado somente quando o download da parte for concluído. Neste caso, seus valores serão apenas 0 ou o valor de size .
O manifesto inclui quatro campos para cada arquivo: file_id , project , name e parts . Se todos os quatro forem especificados, o arquivo será considerado ativo e fechado, disponibilizando-o para download. Caso o campo parts seja omitido, o arquivo será descrito na plataforma. As descrições em massa são usadas para fazer isso de forma eficiente para muitos arquivos em lote. Os arquivos arquivados ou não fechados não poderão ser baixados e causarão um erro.
É possível baixar links simbólicos DNAx, que não possuem partes. Os campos obrigatórios para links simbólicos são file_id , project e name . Observe que um link simbólico possui uma soma de verificação MD5 global, que é verificada no final do download.
Além do binário Go independente, fornecemos também a versão Dockerizada. Ele pode ser usado de maneira muito semelhante a um executável independente, com exceção da necessidade de montar sua pasta local e fornecer seu token API DX.
Atualmente, oferecemos as seguintes tags de imagem:
latest - a versão mais recente do branch master
0.5.11 , 0.5.12 , ... - tags dedicadas para cada versão (a partir de 0.5.11)
Exemplo de uso:
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
onde:
$PWD é um caminho para o diretório no seu computador para baixar arquivos para
DX_API_TOKEN é um token para acessar nossa plataforma (veja Início rápido)
Para direcionar dx-download-agent para um proxy, defina a variável de ambiente HTTP_PROXY como algo como export HTTP_PROXY=hostname:port . HTTPS_PROXY também é compatível.
Por padrão, dx-download-agent usa certificados instalados no sistema para criar conexões seguras. Se o seu sistema exigir um certificado TLS adicional e o dx-download-agent não parecer estar usando um certificado instalado no seu sistema, existem duas opções em ordem de preferência. Primeiro, defina a variável de ambiente DX_TLS_CERTIFICATE_FILE como o caminho do arquivo de certificado TLS codificado em PEM exigido por sua organização pai. Como último recurso, você pode se conectar de forma insegura, evitando totalmente a verificação do certificado, definindo DX_TLS_SKIP_VERIFY=true . Use isso apenas para fins de teste.
Por conveniência, o arquivo create_manifest.py no diretório scripts/ é uma maneira de criar arquivos de manifesto para o agente de download. Este script requer que o dx-toolkit esteja instalado em seu sistema e que você esteja logado na plataforma DNAnexus. Um exemplo de como pode ser usado:
python3 create_manifest.py "Projeto:/Pasta" --recursive --output_file "meusarquivos.manifest.json.bz2"
Aqui, um manifesto é criado recursivamente para todos os arquivos sob o nome do projeto Project e na pasta Folder .
O manifesto pode ser posteriormente filtrado usando o script filter_manifest.py . Por exemplo, se você deseja capturar arquivos em uma pasta específica (por exemplo, Folder ) com testcall neles (por exemplo, /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ), você pode executar o comando:
$ python3 filter_manifest.py manifest.json.bz2 '^/Folder.*testcall.*'
onde o segundo argumento dado ao script é uma expressão regular em todo o caminho (pasta + nome do arquivo).
Em alguns casos, pode ser desejável dividir o manifesto de download em vários arquivos de manifesto para fins de teste ou para gerenciar vários downloads de um conjunto inteiro de dados em diferentes ambientes. Para dividir o arquivo, fornecemos um utilitário Python simples que não requer pacotes adicionais no diretório scripts/ . Por exemplo, executando o comando:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
criará arquivos de manifesto contendo cada um 100 arquivos por projeto. Por exemplo, se houver um total de 300 arquivos em manifest.json.bz2, a saída deste comando criará três arquivos chamados: manifest_001.json.bz2 , manifest_002.json.bz2 e manifest_003.json.bz2 . Cada um desses arquivos pode ser usado de forma independente com o agente de download.
Este repositório também pode ser usado diretamente como um módulo Go. No diretório cmd/dx-download-agent , o arquivo dx-download-agent.go é um exemplo de como ele pode ser usado.
Para desenvolver e experimentar o código-fonte dentro do ambiente Docker isolado, o Dockerfile neste repositório pode ser um bom começo.
Após o download bem-sucedido (e opcionalmente inspecionar o pós-download), deve ser seguro mover os arquivos para o local desejado.
AVISO: Em geral, recomendamos não mover arquivos durante o download, mas movê-los pode ser seguro em certos casos especiais. O agente de download funciona mantendo um banco de dados leve de quais partes dos arquivos foram baixadas e não foram baixadas, de modo que é isso que ele opera principalmente a partir de. Isso significa que mesmo se você mover arquivos, o agente de download não perceberá isso até que você execute o subcomando inspect que executa verificações pós-download da integridade do arquivo no disco. O comando inspecionar notará que os arquivos estão faltando, atualizará o banco de dados e, quando você emitir novamente um comando de download, tentará baixá-los novamente. Portanto, se você mover os arquivos concluídos e não executar o subcomando inspecionar, o agente de download deverá continuar de onde parou. Dito isto, existe o perigo de mover arquivos se o download do arquivo ainda não estiver concluído. Nesse caso você terá movido um arquivo incompleto.
Somente objetos da classe File podem ser baixados.
