dxda
0.6.2
Alat CLI untuk mengelola pengunduhan file dalam jumlah besar dari DNAnexus
CATATAN: Ini adalah versi awal alat ini dan sedang menjalani pengujian dalam berbagai pengaturan. Silakan hubungi DNAnexus jika Anda tertarik untuk mengetahui apakah alat ini sesuai untuk aplikasi Anda.
Untuk memulai dx-download-agent , unduh biner terbaru yang telah dikompilasi dari halaman rilis. Agen pengunduhan menerima dua file:
manifest_file : File manifes JSON terkompresi BZ2 yang menjelaskan, minimal, informasi berikut untuk diunduh, misalnya:
{ "proyek-AAAA": [
{ "id": "file-XXXX", "name": "foo", "folder": "/path/to", "parts": { "1": { "size": 10, "md5": "49302323" }, "2": { "ukuran": 5, "md5": "39239329" }
}
}, "..."
], "proyek-BBBB": [ "..." ]
}Untuk memulai proses pengunduhan, pertama-tama buatlah token API DNAnexus yang valid untuk jangka waktu yang Anda rencanakan untuk mengunduh file. Simpan dalam variabel lingkungan berikut:
ekspor DX_API_TOKEN=
Jika tidak ada token API yang disediakan, agen pengunduhan akan mencari ~/.dnanexus_config/environment.json yang juga digunakan oleh dx-toolkit.
Untuk memulai pengunduhan:
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)
Laporan berkelanjutan tentang kemajuan pengunduhan ditulis ke layar. Sebelum memulai transfer data, pemeriksaan dilakukan untuk melihat apakah ada cukup ruang disk untuk seluruh daftar file. Jika tidak, kesalahan akan dilaporkan, dan tidak ada yang diunduh. Kecepatan pengunduhan tidak hanya mencerminkan bandwidth jaringan, tetapi juga kemampuan IO mesin Anda.
Log unduhan berisi informasi lebih rinci tentang unduhan jika terjadi kesalahan. Jika memang terjadi kesalahan dan Anda tidak memahami cara mengatasinya, silakan hubungi [email protected] dengan melampirkan file log dan kami akan membantu Anda.
Harap dicatat bahwa menjalankan kembali perintah dx-download-agent download TIDAK akan mengunduh ulang file yang diunduh sebelumnya yang kemudian dipindahkan, dihapus, atau dimodifikasi. Silakan jalankan dx-download-agent inspect (dijelaskan di bawah) untuk mendeteksi perubahan apa pun pada file yang diunduh sebelumnya dan menandainya untuk diunduh ulang. Lihat Memindahkan file yang diunduh untuk detail selengkapnya.
Anda dapat menanyakan kemajuan unduhan yang ada di terminal terpisah
dx-download-agent progress exome_bams_manifest.json.bz2
dan Anda akan mendapatkan ringkasan singkat tentang status unduhan:
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
Untuk memeriksa integritas file yang diunduh, Anda dapat menjalankannya
dx-download-agent inspect exome_bams_manifest.json.bz2
Perintah ini akan melakukan pemeriksaan terhadap file dan memastikan bahwa MD5sumnya cocok dengan manifes. Jika ada file yang hilang atau MD5sum tidak cocok, agen pengunduhan akan melaporkan file yang terpengaruh dan Anda kemudian dapat menjalankan dx-download-agent download lagi untuk mengunduh ulang file yang terpengaruh.
-num_threads (integer): # maksimum thread bersamaan yang digunakan saat mengunduh atau memeriksa file
Misalnya perintah
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
akan membuat kumpulan pekerja yang terdiri dari 20 utas yang akan mengunduh sebagian file secara paralel. Maksimum 20 pekerja akan melakukan pengunduhan setiap saat. Pembatasan kecepatan pengunduhan dapat dikontrol sampai batas tertentu dengan memvariasikan jumlah ini.
Informasi tentang bagian apa saja yang telah diunduh disimpan dalam file database sqlite3 yang berisi informasi serupa dengan apa yang ada dalam format file JSON ditambah bidang bytes_fetched tambahan.
Nama tabel: manifest_stats
Bidang (semua bidang adalah string kecuali ditentukan lain)
file_id : ID file untuk bagian file
project : ID proyek untuk bagian file
name : nama file
folder : folder yang berisi file pada DNAnexus
part_id (integer): ID bagian untuk file
md5 : md5sum untuk ID bagian
size (integer): ukuran bagian
block_size (integer): ukuran blok utama file (diasumsikan sama dengan size kecuali bagian terakhir)
bytes_fetched (integer <= size ): jumlah total byte yang diunduh
Terserah pada implementasi untuk memutuskan apakah bytes_fetched diperbarui dengan cara yang lebih kasar vs. halus. Misalnya, bytes_fetched hanya dapat diperbarui ketika pengunduhan bagian selesai. Dalam hal ini, nilainya hanya 0 atau nilai size .
Manifes mencakup empat bidang untuk setiap file: file_id , project , name , dan parts . Jika keempatnya ditentukan, file dianggap aktif dan tertutup, sehingga tersedia untuk diunduh. Jika bidang parts dihilangkan, file akan dijelaskan pada platform. Penjelasan massal digunakan untuk melakukan ini secara efisien untuk banyak file dalam batch. File yang diarsipkan atau tidak ditutup tidak dapat diunduh, dan akan memicu kesalahan.
Dimungkinkan untuk mengunduh tautan simbolik DNAx, yang tidak memiliki bagian. Bidang yang wajib diisi untuk tautan simbolik adalah file_id , project , dan name . Perhatikan bahwa tautan simbolik memiliki checksum MD5 global, yang diperiksa di akhir pengunduhan.
Selain biner Go mandiri, kami juga menyediakan versi Docker. Ini dapat digunakan dengan cara yang sangat mirip dengan executable mandiri dengan pengecualian kebutuhan untuk memasang folder lokal Anda dan menyediakan token DX API Anda.
Saat ini, kami menawarkan tag gambar berikut:
latest - versi terbaru dari cabang master
0.5.11 , 0.5.12 , ... - tag khusus untuk setiap rilis (mulai dari 0.5.11)
Contoh penggunaan:
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
Di mana:
$PWD adalah jalur ke direktori di komputer Anda untuk mengunduh file
DX_API_TOKEN adalah token untuk mengakses platform kami (lihat Panduan cepat)
Untuk mengarahkan dx-download-agent ke proxy, setel variabel lingkungan HTTP_PROXY ke sesuatu seperti export HTTP_PROXY=hostname:port . HTTPS_PROXY juga didukung.
Secara default, dx-download-agent menggunakan sertifikat yang diinstal pada sistem untuk membuat koneksi aman. Jika sistem Anda memerlukan sertifikat TLS tambahan dan dx-download-agent tampaknya tidak menggunakan sertifikat yang diinstal pada sistem Anda, ada dua opsi sesuai urutan preferensi. Pertama, atur variabel lingkungan DX_TLS_CERTIFICATE_FILE ke jalur file sertifikat TLS berkode PEM yang diperlukan oleh organisasi induk Anda. Sebagai upaya terakhir, Anda dapat terhubung secara tidak aman dengan menghindari verifikasi sertifikat secara bersamaan dengan menyetel DX_TLS_SKIP_VERIFY=true . Gunakan ini untuk tujuan pengujian saja.
Untuk kenyamanan, file create_manifest.py di direktori scripts/ adalah salah satu cara untuk membuat file manifes untuk agen pengunduhan. Skrip ini mengharuskan dx-toolkit diinstal pada sistem Anda dan Anda masuk ke platform DNAnexus. Contoh cara penggunaannya:
python3 create_manifest.py "Proyek:/Folder" --rekursif --output_file "myfiles.manifest.json.bz2"
Di sini, manifes dibuat untuk semua file secara rekursif dengan nama proyek Project dan di folder Folder .
Manifes selanjutnya dapat difilter menggunakan skrip filter_manifest.py . Misalnya, jika Anda ingin mengambil file dalam folder tertentu (misalnya Folder ) dengan testcall di dalamnya (misalnya /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ), Anda dapat menjalankan perintah:
$ python3 filter_manifest.py manifest.json.bz2 '^/Folder.*testcall.*'
dimana argumen kedua yang diberikan pada skrip adalah ekspresi reguler di seluruh jalur (folder + nama file).
Dalam beberapa kasus, mungkin diinginkan untuk membagi manifes unduhan menjadi beberapa file manifes untuk tujuan pengujian atau untuk mengelola beberapa unduhan dari keseluruhan kumpulan data di lingkungan yang berbeda. Untuk membagi file, kami menyediakan utilitas Python sederhana yang tidak memerlukan paket tambahan di direktori scripts/ . Misalnya, menjalankan perintah:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
akan membuat file manifes yang masing-masing berisi 100 file per proyek. Misalnya jika ada total 300 file di manifest.json.bz2, output dari perintah ini akan menghasilkan tiga file bernama: manifest_001.json.bz2 , manifest_002.json.bz2 , dan manifest_003.json.bz2 . Masing-masing file ini dapat digunakan secara mandiri dengan agen pengunduhan.
Repositori ini juga dapat digunakan secara langsung sebagai modul Go. Di direktori cmd/dx-download-agent , file dx-download-agent.go adalah contoh penggunaannya.
Untuk mengembangkan dan bereksperimen dengan sumber di dalam lingkungan Docker yang terisolasi, Dockerfile di repositori ini mungkin merupakan awal yang baik.
Setelah berhasil mengunduh (dan secara opsional memeriksa pasca-pengunduhan), file seharusnya aman untuk dipindahkan ke lokasi yang Anda inginkan.
PERINGATAN: Secara umum kami menyarankan untuk tidak memindahkan file selama pengunduhan tetapi memindahkannya mungkin aman dalam kasus-kasus khusus tertentu. Agen pengunduhan bekerja dengan memelihara basis data ringan tentang bagian mana dari file yang telah dan belum diunduh sehingga itulah yang terjadi itu terutama beroperasi. Ini berarti bahwa meskipun Anda memindahkan file, agen pengunduhan tidak akan menyadarinya sampai Anda menjalankan perintah inspect yang melakukan pemeriksaan pasca-pengunduhan untuk integritas file pada disk. Perintah inspeksi akan melihat file-file tersebut hilang, memperbarui database, dan ketika Anda mengeluarkan kembali perintah unduh, cobalah untuk mengunduhnya lagi. Oleh karena itu, jika Anda memindahkan file yang sudah selesai dan tidak menjalankan subperintah inspeksi, agen pengunduhan harus melanjutkan dari bagian terakhirnya. Meskipun demikian, bahaya dalam memindahkan file adalah jika pengunduhan file belum selesai. Dalam hal ini Anda akan memindahkan file yang tidak lengkap.
Hanya objek File kelas yang dapat diunduh.
