dxda
0.6.2
CLI-Tool zur Verwaltung des Downloads großer Dateimengen von DNAnexus
HINWEIS: Dies ist eine frühe Version dieses Tools und wird derzeit in verschiedenen Umgebungen getestet. Bitte wenden Sie sich an DNAnexus, wenn Sie wissen möchten, ob dieses Tool für Ihre Anwendung geeignet ist.
Um mit dx-download-agent zu beginnen, laden Sie die neueste vorkompilierte Binärdatei von der Release-Seite herunter. Der Download-Agent akzeptiert zwei Dateien:
manifest_file : Eine BZ2-komprimierte JSON-Manifestdatei, die mindestens die folgenden Informationen für einen Download beschreibt, zum Beispiel:
{ "Projekt-AAAA": [
{ „id“: „file-XXXX“, „name“: „foo“, „folder“: „/path/to“, „parts“: { „1“: { „size“: 10, „md5“: "49302323" }, "2": { "size": 5, "md5": "39239329" }
}
}, „…“
], „project-BBBB“: [ „…“ ]
}Um einen Downloadvorgang zu starten, generieren Sie zunächst ein DNAnexus-API-Token, das für den Zeitraum gültig ist, in dem Sie die Dateien herunterladen möchten. Speichern Sie es in der folgenden Umgebungsvariablen:
export DX_API_TOKEN=
Wenn kein API-Token bereitgestellt wird, sucht der Download-Agent nach ~/.dnanexus_config/environment.json das auch vom dx-toolkit verwendet wird.
So starten Sie den 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)
Ein fortlaufender Bericht über den Download-Fortschritt wird auf dem Bildschirm angezeigt. Vor Beginn der Datenübertragung wird geprüft, ob ausreichend Speicherplatz für die gesamte Dateiliste vorhanden ist. Wenn nicht, wird ein Fehler gemeldet und es wird nichts heruntergeladen. Die Download-Geschwindigkeit spiegelt nicht nur die Netzwerkbandbreite wider, sondern auch die E/A-Fähigkeit Ihres Computers.
Ein Download-Protokoll enthält detailliertere Informationen zum Download, falls ein Fehler auftritt. Wenn ein Fehler auftritt und Sie nicht wissen, wie Sie damit umgehen sollen, wenden Sie sich bitte mit der beigefügten Protokolldatei an [email protected] . Wir helfen Ihnen dann weiter.
Bitte beachten Sie, dass durch die erneute Ausführung des dx-download-agent download KEINE zuvor heruntergeladenen Dateien erneut heruntergeladen werden, die anschließend verschoben, gelöscht oder geändert wurden. Bitte führen Sie dx-download-agent inspect (unten beschrieben) aus, um Änderungen an zuvor heruntergeladenen Dateien zu erkennen und sie zum erneuten Herunterladen zu markieren. Weitere Einzelheiten finden Sie unter Heruntergeladene Dateien verschieben.
Den Fortschritt eines bestehenden Downloads können Sie in einem separaten Terminal abfragen
dx-download-agent progress exome_bams_manifest.json.bz2
und Sie erhalten eine kurze Zusammenfassung des Status der Downloads:
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
Um die Integrität der heruntergeladenen Dateien zu überprüfen, können Sie Folgendes ausführen
dx-download-agent inspect exome_bams_manifest.json.bz2
Dieser Befehl führt eine Überprüfung der Dateien durch und stellt sicher, dass ihre MD5-Summen mit dem Manifest übereinstimmen. Wenn eine Datei fehlt oder eine MD5-Summe nicht übereinstimmt, meldet der Download-Agent die betroffenen Dateien und Sie können dx-download-agent download erneut ausführen, um die betroffenen Dateien erneut herunterzuladen.
-num_threads (Ganzzahl): maximale Anzahl gleichzeitiger Threads, die beim Herunterladen oder Überprüfen von Dateien verwendet werden sollen
Zum Beispiel der Befehl
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
erstellt einen Worker-Pool mit 20 Threads, der Teile von Dateien parallel herunterlädt. Maximal 20 Mitarbeiter führen jederzeit Downloads durch. Durch Variation dieser Anzahl kann die Ratenbegrenzung der Downloads bis zu einem gewissen Grad gesteuert werden.
Informationen darüber, welche Teile heruntergeladen wurden, werden in einer SQLite3-Datenbankdatei verwaltet, die ähnliche Informationen wie die Inhalte im JSON-Dateiformat sowie ein zusätzliches Feld bytes_fetched enthält.
Tabellenname: manifest_stats
Felder (alle Felder sind Zeichenfolgen, sofern nicht anders angegeben)
file_id : Datei-ID für den Dateiteil
project : Projekt-ID für Dateiteil
name : Name der Datei
folder : Ordner mit der Datei auf DNAnexus
part_id (Ganzzahl): Teile-ID für die Datei
md5 : md5sum für Teile-ID
size (Ganzzahl): Größe des Teils
block_size (Ganzzahl): primäre Blockgröße der Datei (wird bis auf den letzten Teil als gleich der size angenommen)
bytes_fetched (Ganzzahl <= size ): Gesamtzahl der heruntergeladenen Bytes
Es liegt an der Implementierung, zu entscheiden, ob bytes_fetched grobkörniger oder feinkörniger aktualisiert wird oder nicht. Beispielsweise kann bytes_fetched nur aktualisiert werden, wenn der Teile-Download abgeschlossen ist. In diesem Fall sind seine Werte nur 0 oder der Wert von size .
Das Manifest enthält vier Felder für jede Datei: file_id , project , name und parts . Wenn alle vier angegeben sind, wird davon ausgegangen, dass die Datei live und geschlossen ist und zum Download verfügbar ist. Wenn das parts weggelassen wird, wird die Datei auf der Plattform beschrieben. Massenbeschreibungen werden verwendet, um dies effizient für viele Dateien im Stapel durchzuführen. Archivierte oder nicht geschlossene Dateien können nicht heruntergeladen werden und lösen einen Fehler aus.
Es ist möglich, symbolische DNAx-Links herunterzuladen, die keine Teile haben. Die erforderlichen Felder für symbolische Links sind file_id , project und name . Beachten Sie, dass ein symbolischer Link über eine globale MD5-Prüfsumme verfügt, die am Ende des Downloads überprüft wird.
Neben der eigenständigen Go-Binärdatei bieten wir auch eine Docker-Version an. Es kann auf sehr ähnliche Weise wie eine eigenständige ausführbare Datei verwendet werden, mit Ausnahme der Notwendigkeit, Ihren lokalen Ordner bereitzustellen und Ihr DX-API-Token bereitzustellen.
Derzeit bieten wir folgende Bild-Tags an:
latest – der neueste Build des Master-Zweigs
0.5.11 , 0.5.12 , ... – dedizierte Tags für jede Version (ab 0.5.11)
Beispielverwendung:
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
Wo:
$PWD ist ein Pfad zu einem Verzeichnis auf Ihrem Computer, in das Sie Dateien herunterladen können
DX_API_TOKEN ist ein Token für den Zugriff auf unsere Plattform (siehe Schnellstart)
Um dx-download-agent an einen Proxy weiterzuleiten, setzen Sie bitte die Umgebungsvariable HTTP_PROXY auf etwas wie export HTTP_PROXY=hostname:port . HTTPS_PROXY wird ebenfalls unterstützt.
Standardmäßig verwendet dx-download-agent auf dem System installierte Zertifikate, um sichere Verbindungen herzustellen. Wenn Ihr System ein zusätzliches TLS-Zertifikat erfordert und der dx-download-agent offenbar kein auf Ihrem System installiertes Zertifikat verwendet, gibt es zwei Optionen in der Reihenfolge ihrer Präferenz. Legen Sie zunächst die Umgebungsvariable DX_TLS_CERTIFICATE_FILE auf den Pfad der PEM-codierten TLS-Zertifikatdatei fest, die von Ihrer Mutterorganisation benötigt wird. Als letzten Ausweg können Sie eine unsichere Verbindung herstellen, indem Sie die Zertifikatsüberprüfung insgesamt vermeiden, indem Sie DX_TLS_SKIP_VERIFY=true festlegen. Verwenden Sie dies nur zu Testzwecken.
Der Einfachheit halber ist die Datei create_manifest.py im Verzeichnis scripts/ eine Möglichkeit, Manifestdateien für den Download-Agenten zu erstellen. Für dieses Skript ist es erforderlich, dass das dx-toolkit auf Ihrem System installiert ist und Sie bei der DNAnexus-Plattform angemeldet sind. Ein Anwendungsbeispiel:
python3 create_manifest.py "Projekt:/Ordner" --recursive --output_file "myfiles.manifest.json.bz2"
Hierbei wird rekursiv ein Manifest für alle Dateien unter dem Projektnamen Project und im Ordner Folder erstellt.
Das Manifest kann anschließend mit dem Skript filter_manifest.py gefiltert werden. Wenn Sie beispielsweise Dateien in einem bestimmten Ordner (z. B. Folder ) mit testcall darin erfassen möchten (z. B. /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ), können Sie den folgenden Befehl ausführen:
$ python3 filter_manifest.py manifest.json.bz2 '^/Folder.*testcall.*'
Dabei ist das zweite dem Skript übergebene Argument ein regulärer Ausdruck für den gesamten Pfad (Ordner + Dateiname).
In manchen Fällen kann es wünschenswert sein, das Download-Manifest zu Testzwecken in mehrere Manifestdateien aufzuteilen oder mehrere Downloads eines gesamten Datensatzes über verschiedene Umgebungen hinweg zu verwalten. Um die Datei aufzuteilen, stellen wir ein einfaches Python-Dienstprogramm bereit, das keine zusätzlichen Pakete im Verzeichnis scripts/ erfordert. Beispiel: Ausführen des Befehls:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
erstellt Manifestdateien mit jeweils 100 Dateien pro Projekt. Wenn es beispielsweise insgesamt 300 Dateien in manifest.json.bz2 gibt, erstellt die Ausgabe dieses Befehls drei Dateien mit den Namen: manifest_001.json.bz2 , manifest_002.json.bz2 und manifest_003.json.bz2 . Jede dieser Dateien kann unabhängig mit dem Download-Agenten verwendet werden.
Dieses Repository kann auch direkt als Go-Modul verwendet werden. Im Verzeichnis cmd/dx-download-agent ist die Datei dx-download-agent.go ein Beispiel dafür, wie sie verwendet werden kann.
Für die Entwicklung und das Experimentieren mit der Quelle in einer isolierten Docker-Umgebung kann die Docker-Datei in diesem Repository ein guter Anfang sein.
Nach erfolgreichem Download (und optionaler Überprüfung nach dem Download) sollte es sicher sein, die Dateien an den gewünschten Speicherort zu verschieben.
WARNUNG: Im Allgemeinen raten wir davon ab, Dateien während eines Downloads zu verschieben. In bestimmten Sonderfällen kann das Verschieben jedoch sicher sein. Der Download-Agent verwaltet eine kompakte Datenbank darüber, welche Teile der Dateien heruntergeladen wurden und welche nicht Es funktioniert hauptsächlich aus. Das bedeutet, dass der Download-Agent selbst dann, wenn Sie Dateien verschieben, dies erst erkennt, wenn Sie den Unterbefehl inspect “ ausführen, der nach dem Download Prüfungen auf Dateiintegrität auf der Festplatte durchführt. Der Befehl „inspect“ stellt fest, dass die Dateien fehlen, aktualisiert die Datenbank und versucht, sie erneut herunterzuladen, wenn Sie einen Download-Befehl erneut ausgeben. Wenn Sie abgeschlossene Dateien verschieben und den Unterbefehl „inspect“ nicht ausführen, sollte der Download-Agent daher an der Stelle fortfahren, an der er aufgehört hat. Allerdings besteht beim Verschieben von Dateien die Gefahr, dass der Download einer Datei noch nicht abgeschlossen ist. In diesem Fall haben Sie eine unvollständige Datei verschoben.
Es können nur Objekte der Klasse File heruntergeladen werden.
