dxda
0.6.2
Herramienta CLI para gestionar la descarga de grandes cantidades de archivos desde DNAnexus
NOTA: Esta es una versión inicial de esta herramienta y se está probando en una variedad de entornos. Comuníquese con DNAnexus si está interesado en ver si esta herramienta es apropiada para su aplicación.
Para comenzar con dx-download-agent , descargue el binario precompilado más reciente desde la página de lanzamiento. El agente de descarga acepta dos archivos:
manifest_file : un archivo de manifiesto JSON comprimido con BZ2 que describe, como mínimo, la siguiente información para una descarga, por ejemplo:
{ "proyecto-AAAA": [
{ "id": "archivo-XXXX", "nombre": "foo", "carpeta": "/ruta/a", "partes": { "1": { "tamaño": 10, "md5": "49302323" }, "2": { "tamaño": 5, "md5": "39239329" }
}
}, "..."
], "proyecto-BBBB": [ "..." ]
}Para iniciar un proceso de descarga, primero genere un token API de DNAnexus que sea válido durante el período de tiempo en el que planea descargar los archivos. Guárdelo en la siguiente variable de entorno:
exportar DX_API_TOKEN=
Si no se proporciona ningún token API, el agente de descarga buscará el ~/.dnanexus_config/environment.json que también utiliza dx-toolkit.
Para iniciar la descarga:
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)
Se escribe en la pantalla un informe continuo sobre el progreso de la descarga. Antes de iniciar la transferencia de datos, se comprueba que haya suficiente espacio en disco para toda la lista de archivos. De lo contrario, se informa un error y no se descarga nada. La velocidad de descarga refleja no sólo el ancho de banda de la red, sino también la capacidad de IO de su máquina.
Un registro de descarga contiene información más detallada sobre la descarga en caso de que se produzca un error. Si se produce un error y no comprende cómo solucionarlo, comuníquese con [email protected] con el archivo de registro adjunto y lo ayudaremos.
Tenga en cuenta que volver a ejecutar el comando dx-download-agent download NO volverá a descargar ningún archivo descargado anteriormente que se haya movido, eliminado o modificado posteriormente. Ejecute dx-download-agent inspect (que se describe a continuación) para detectar cualquier cambio en los archivos descargados anteriormente y marcarlos para volver a descargarlos. Consulte Mover archivos descargados para obtener más detalles.
Puede consultar el progreso de una descarga existente en una terminal separada
dx-download-agent progress exome_bams_manifest.json.bz2
y obtendrás un breve resumen del estado de las descargas:
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
Para verificar la integridad de los archivos descargados, puede ejecutar
dx-download-agent inspect exome_bams_manifest.json.bz2
Este comando realizará una inspección de los archivos y garantizará que sus sumas MD5 coincidan con el manifiesto. Si falta un archivo o una suma MD5 no coincide, el agente de descarga informará los archivos afectados y luego podrá ejecutar dx-download-agent download nuevamente para volver a descargar los archivos afectados.
-num_threads (entero): número máximo de subprocesos simultáneos para usar al descargar o inspeccionar archivos
Por ejemplo, el comando
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
creará un grupo de trabajadores de 20 subprocesos que descargarán partes de archivos en paralelo. Un máximo de 20 trabajadores realizarán descargas en cualquier momento. La limitación de la velocidad de descargas se puede controlar hasta cierto punto variando este número.
La información sobre las partes que se han descargado se mantiene en un archivo de base de datos sqlite3 que contiene información similar a la del formato de archivo JSON más un campo bytes_fetched adicional.
Nombre de la tabla: manifest_stats
Campos (todos los campos son cadenas a menos que se especifique lo contrario)
file_id : ID de archivo para la parte del archivo
project : ID del proyecto para la parte del archivo
name : nombre del archivo
folder : carpeta que contiene el archivo en DNAnexus
part_id (entero): ID de pieza para el archivo
md5 : md5sum para ID de pieza
size (entero): tamaño de la pieza
block_size (entero): tamaño del bloque principal del archivo (se supone que es igual al size excepto en la última parte)
bytes_fetched (entero <= size ): número total de bytes descargados
Depende de la implementación decidir si bytes_fetched se actualiza o no de una manera más gruesa o más detallada. Por ejemplo, bytes_fetched solo se puede actualizar cuando se completa la descarga de la pieza. En este caso, sus valores solo serán 0 o el valor de size .
El manifiesto incluye cuatro campos para cada archivo: file_id , project , name y parts . Si se especifican los cuatro, se supone que el archivo está activo y cerrado, por lo que estará disponible para su descarga. Si se omite el campo parts , el archivo se describirá en la plataforma. Las descripciones masivas se utilizan para hacer esto de manera eficiente para muchos archivos por lotes. Los archivos que están archivados o no cerrados no se pueden descargar y generarán un error.
Es posible descargar enlaces simbólicos de DNAx, que no tienen partes. Los campos obligatorios para los enlaces simbólicos son file_id , project y name . Tenga en cuenta que un enlace simbólico tiene una suma de comprobación MD5 global, que se comprueba al final de la descarga.
Además del binario Go autónomo, también ofrecemos una versión Dockerizada. Se puede usar de manera muy similar como ejecutable independiente, con la excepción de que sea necesario montar su carpeta local y proporcionar su token API DX.
Actualmente, ofrecemos las siguientes etiquetas de imagen:
latest : la versión más reciente de la rama maestra
0.5.11 , 0.5.12 , ... - etiquetas dedicadas para cada versión (a partir de 0.5.11)
Uso de ejemplo:
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
dónde:
$PWD es una ruta al directorio de su computadora para descargar archivos
DX_API_TOKEN es un token para acceder a nuestra plataforma (ver Inicio rápido)
Para dirigir dx-download-agent a un proxy, configure la variable de entorno HTTP_PROXY en algo como export HTTP_PROXY=hostname:port . También se admite HTTPS_PROXY .
De forma predeterminada, dx-download-agent utiliza certificados instalados en el sistema para crear conexiones seguras. Si su sistema requiere un certificado TLS adicional y dx-download-agent no parece estar usando un certificado instalado en su sistema, hay dos opciones en orden de preferencia. Primero, configure la variable de entorno DX_TLS_CERTIFICATE_FILE en la ruta del archivo de certificado TLS codificado con PEM requerido por su organización principal. Como último recurso, puede conectarse de forma insegura evitando por completo la verificación del certificado configurando DX_TLS_SKIP_VERIFY=true . Utilice esto únicamente con fines de prueba.
Para mayor comodidad, el archivo create_manifest.py en el directorio scripts/ es una forma de crear archivos de manifiesto para el agente de descarga. Este script requiere que el dx-toolkit esté instalado en su sistema y que haya iniciado sesión en la plataforma DNAnexus. Un ejemplo de cómo se puede utilizar:
python3 create_manifest.py "Proyecto:/Carpeta" --recursive --output_file "misarchivos.manifest.json.bz2"
Aquí se crea un manifiesto para todos los archivos de forma recursiva bajo el nombre del proyecto Project y en la Folder Carpeta.
Posteriormente, el manifiesto se puede filtrar utilizando el script filter_manifest.py . Por ejemplo, si desea capturar archivos en una carpeta particular (por ejemplo, Folder ) con testcall en ellos (por ejemplo, /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ), puede ejecutar el comando:
$ python3 filter_manifest.py manifest.json.bz2 '^/Carpeta.*testcall.*'
donde el segundo argumento dado al script es una expresión regular en toda la ruta (carpeta + nombre de archivo).
En algunos casos, puede ser conveniente dividir el manifiesto de descarga en varios archivos de manifiesto con fines de prueba o para administrar varias descargas de un conjunto de datos completo en diferentes entornos. Para dividir el archivo, proporcionamos una utilidad Python simple que no requiere paquetes adicionales en el directorio scripts/ . Por ejemplo, ejecutando el comando:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
creará archivos de manifiesto que contienen cada uno 100 archivos por proyecto. Por ejemplo, si hay 300 archivos en total en manifest.json.bz2, el resultado de este comando creará tres archivos denominados: manifest_001.json.bz2 , manifest_002.json.bz2 y manifest_003.json.bz2 . Cada uno de estos archivos se puede utilizar de forma independiente con el agente de descarga.
Este repositorio también se puede utilizar directamente como módulo Go. En el directorio cmd/dx-download-agent , el archivo dx-download-agent.go es un ejemplo de cómo se puede utilizar.
Para desarrollar y experimentar con el código fuente dentro de un entorno Docker aislado, el Dockerfile de este repositorio puede ser un buen comienzo.
Después de descargar correctamente (y, opcionalmente, inspeccionar después de la descarga), debería ser seguro mover los archivos a la ubicación deseada.
ADVERTENCIA: En general, recomendamos no mover archivos durante el curso de una descarga, pero moverlos podría ser seguro en ciertos casos especiales. El agente de descarga funciona manteniendo una base de datos liviana de qué partes de los archivos se han descargado y no, así que eso es lo que opera principalmente fuera de. Esto significa que incluso si mueve archivos, el agente de descarga no se dará cuenta hasta que ejecute el subcomando inspect que realiza comprobaciones posteriores a la descarga para verificar la integridad de los archivos en el disco. El comando de inspección notará que faltan archivos, actualizará la base de datos y, cuando vuelva a emitir un comando de descarga, intentará descargarlos nuevamente. Por lo tanto, si mueve archivos completados y no ejecuta el subcomando inspeccionar, el agente de descarga debería continuar desde donde lo dejó. Dicho esto, existe un peligro al mover archivos si la descarga del archivo aún no está completa. En ese caso habrás movido un archivo incompleto.
Sólo se pueden descargar objetos de la clase Archivo.
