ดีเอ็กซ์ด้า

dx-ดาวน์โหลด-ตัวแทน

เครื่องมือ CLI เพื่อจัดการการดาวน์โหลดไฟล์จำนวนมากจาก DNAnexus

หมายเหตุ: นี่เป็นเวอร์ชันเริ่มต้นของเครื่องมือนี้ และอยู่ระหว่างการทดสอบในการตั้งค่าต่างๆ โปรดติดต่อ DNAnexus หากคุณสนใจที่จะดูว่าเครื่องมือนี้เหมาะสมกับการใช้งานของคุณหรือไม่

เริ่มต้นอย่างรวดเร็ว

หากต้องการเริ่มต้นใช้งาน dx-download-agent ให้ดาวน์โหลดไบนารี่ที่คอมไพล์ไว้ล่วงหน้าล่าสุดจากหน้าเผยแพร่ ตัวแทนการดาวน์โหลดยอมรับสองไฟล์:

• manifest_file : ไฟล์ Manifest JSON ที่บีบอัด BZ2 ที่อธิบายข้อมูลต่อไปนี้สำหรับการดาวน์โหลดขั้นต่ำที่สุด เช่น:

 { "โครงการ AAAA": [
    { "id": "file-XXXX", "name": "foo", "folder": "/path/to", "parts": { "1": { "size": 10, "md5": "49302323" }, "2": { "ขนาด": 5, "md5": "39239329" }
      -
    -
  ], "โครงการ-BBBB": [ "..." ]
-

หากต้องการเริ่มกระบวนการดาวน์โหลด ขั้นแรกให้สร้างโทเค็น DNAnexus API ที่ถูกต้องตามระยะเวลาที่คุณวางแผนจะดาวน์โหลดไฟล์ เก็บไว้ในตัวแปรสภาพแวดล้อมต่อไปนี้:

 ส่งออก DX_API_TOKEN=<ใส่โทเค็น API ที่นี่>

หากไม่มีการระบุโทเค็น API เอเจนต์การดาวน์โหลดจะดูที่ ~/.dnanexus_config/environment.json ซึ่ง dx-toolkit ใช้เช่นกัน

เพื่อเริ่มการดาวน์โหลด:

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)

รายงานความคืบหน้าการดาวน์โหลดอย่างต่อเนื่องจะถูกเขียนลงบนหน้าจอ ก่อนที่จะเริ่มการถ่ายโอนข้อมูล จะมีการตรวจสอบเพื่อดูว่ามีพื้นที่ดิสก์เพียงพอสำหรับรายการไฟล์ทั้งหมด ถ้าไม่เช่นนั้น ระบบจะรายงานข้อผิดพลาด และจะไม่มีการดาวน์โหลดอะไรเลย ความเร็วในการดาวน์โหลดไม่เพียงสะท้อนถึงแบนด์วิธเครือข่ายเท่านั้น แต่ยังสะท้อนถึงความสามารถ IO ของเครื่องของคุณด้วย

บันทึกการดาวน์โหลดประกอบด้วยข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการดาวน์โหลดหากเกิดข้อผิดพลาด หากมีข้อผิดพลาดเกิดขึ้นและคุณไม่เข้าใจวิธีจัดการกับข้อผิดพลาดดังกล่าว โปรดติดต่อ [email protected] พร้อมแนบไฟล์บันทึก แล้วเราจะช่วยเหลือคุณ

โปรดทราบว่าการรันคำสั่ง dx-download-agent download อีกครั้งจะไม่ดาวน์โหลดไฟล์ที่ดาวน์โหลดก่อนหน้านี้อีกครั้ง ซึ่งถูกย้าย ลบ หรือแก้ไขในภายหลัง โปรดเรียกใช้ dx-download-agent inspect (อธิบายไว้ด้านล่าง) เพื่อตรวจหาการเปลี่ยนแปลงใดๆ ในไฟล์ที่ดาวน์โหลดก่อนหน้านี้ และทำเครื่องหมายให้ดาวน์โหลดใหม่ ดูการย้ายไฟล์ที่ดาวน์โหลดสำหรับรายละเอียดเพิ่มเติม

คุณสามารถค้นหาความคืบหน้าของการดาวน์โหลดที่มีอยู่ในเทอร์มินัลที่แยกต่างหาก

dx-download-agent progress exome_bams_manifest.json.bz2

และคุณจะได้รับข้อมูลสรุปโดยย่อเกี่ยวกับสถานะการดาวน์โหลด:

21.6 MB/sec	1184/27078 MB	18/327 Parts Downloaded and written to disk

คุณสามารถเรียกใช้เพื่อตรวจสอบความสมบูรณ์ของไฟล์ที่ดาวน์โหลดได้

dx-download-agent inspect exome_bams_manifest.json.bz2

คำสั่งนี้จะทำการตรวจสอบไฟล์และตรวจสอบให้แน่ใจว่า MD5sums ตรงกับไฟล์ Manifest หากไฟล์หายไปหรือ MD5sum ไม่ตรงกัน เอเจนต์การดาวน์โหลดจะรายงานไฟล์ที่ได้รับผลกระทบ จากนั้นคุณสามารถเรียกใช้ dx-download-agent download อีกครั้งเพื่อดาวน์โหลดไฟล์ที่ได้รับผลกระทบอีกครั้ง

ตัวเลือกการดำเนินการ

• -num_threads (จำนวนเต็ม): จำนวนเธรดพร้อมกันสูงสุดที่จะใช้เมื่อดาวน์โหลดหรือตรวจสอบไฟล์

เช่น คำสั่ง

dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2

จะสร้างกลุ่มผู้ปฏิบัติงาน 20 เธรดที่จะดาวน์โหลดไฟล์บางส่วนพร้อมกัน พนักงานสูงสุด 20 คนจะทำการดาวน์โหลดได้ตลอดเวลา การจำกัดอัตราการดาวน์โหลดสามารถควบคุมได้ในระดับหนึ่งโดยการเปลี่ยนแปลงตัวเลขนี้

ข้อมูลจำเพาะฐานข้อมูลสถิติ Manifest

ข้อมูลเกี่ยวกับส่วนที่ดาวน์โหลดจะถูกเก็บรักษาไว้ในไฟล์ฐานข้อมูล sqlite3 ซึ่งมีข้อมูลที่คล้ายกันกับสิ่งที่อยู่ในรูปแบบไฟล์ JSON พร้อมด้วยฟิลด์ bytes_fetched เพิ่มเติม

ชื่อตาราง: manifest_stats

ฟิลด์ (ฟิลด์ทั้งหมดเป็นสตริง เว้นแต่จะระบุไว้เป็นอย่างอื่น)

• file_id : file ID สำหรับส่วนของไฟล์

• project : รหัสโครงการสำหรับส่วนของไฟล์

• name : ชื่อของไฟล์

• folder : โฟลเดอร์ที่มีไฟล์บน DNAnexus

• part_id (จำนวนเต็ม): ID ส่วนสำหรับไฟล์

• md5 : md5sum สำหรับรหัสชิ้นส่วน

• size (จำนวนเต็ม): ขนาดของชิ้นส่วน

• block_size (จำนวนเต็ม): ขนาดบล็อกหลักของไฟล์ (ถือว่าเท่ากับ size ยกเว้นส่วนสุดท้าย)

• bytes_fetched (จำนวนเต็ม <= size ): จำนวนไบต์ทั้งหมดที่ดาวน์โหลด

ขึ้นอยู่กับการใช้งานที่จะตัดสินใจว่า bytes_fetched ได้รับการอัปเดตในรูปแบบที่หยาบหรือละเอียดมากขึ้นหรือไม่ ตัวอย่างเช่น สามารถอัปเดต bytes_fetched ได้เมื่อการดาวน์โหลดชิ้นส่วนเสร็จสมบูรณ์เท่านั้น ในกรณีนี้ ค่าจะเป็น 0 หรือค่าของ size เท่านั้น

รายการประกอบด้วยสี่ฟิลด์สำหรับแต่ละไฟล์: file_id , project , name และ parts หากระบุทั้งสี่ไฟล์ จะถือว่าไฟล์นั้นใช้งานจริงและปิดอยู่ ทำให้พร้อมสำหรับการดาวน์โหลด หากละเว้นฟิลด์ parts ไฟล์จะถูกอธิบายบนแพลตฟอร์ม คำอธิบายแบบกลุ่มใช้เพื่อดำเนินการนี้อย่างมีประสิทธิภาพกับไฟล์จำนวนมากในแบทช์ ไฟล์ที่ถูกเก็บถาวรหรือไม่ได้ปิดไม่สามารถดาวน์โหลดได้ และจะทำให้เกิดข้อผิดพลาด

สามารถดาวน์โหลดลิงก์สัญลักษณ์ DNAx ซึ่งไม่มีชิ้นส่วนได้ ฟิลด์ที่จำเป็นสำหรับลิงก์สัญลักษณ์คือ file_id , project และ name โปรดทราบว่าลิงก์สัญลักษณ์จะมีการตรวจสอบ MD5 ทั่วโลก ซึ่งจะถูกตรวจสอบเมื่อสิ้นสุดการดาวน์โหลด

ทำงานโดยใช้นักเทียบท่า

นอกเหนือจาก Go binary ที่มีในตัวเองแล้ว เรายังมีเวอร์ชัน Dockerized อีกด้วย สามารถใช้ในลักษณะที่คล้ายกันมากกับปฏิบัติการแบบสแตนด์อโลนได้ ยกเว้นความจำเป็นในการเมานต์โฟลเดอร์ในเครื่องของคุณและเพื่อจัดเตรียมโทเค็น DX API ของคุณ

ขณะนี้ เรามีแท็กรูปภาพดังต่อไปนี้:

• latest - โครงสร้างล่าสุดของสาขาหลัก

• 0.5.11 , 0.5.12 , ... - แท็กเฉพาะสำหรับแต่ละรุ่น (เริ่มตั้งแต่ 0.5.11)

• - บิลด์การพัฒนาสำหรับแต่ละคอมมิตในสาขาหลัก

ตัวอย่างการใช้งาน:

$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2

ที่ไหน:

• $PWD เป็นเส้นทางไปยังไดเร็กทอรีบนคอมพิวเตอร์ของคุณเพื่อดาวน์โหลดไฟล์ไป

• DX_API_TOKEN เป็นโทเค็นเพื่อเข้าถึงแพลตฟอร์มของเรา (ดูการเริ่มต้นอย่างรวดเร็ว)

การตั้งค่าพร็อกซีและ TLS

หากต้องการเปลี่ยนทิศทาง dx-download-agent ไปยังพร็อกซี โปรดตั้งค่าตัวแปรสภาพแวดล้อม HTTP_PROXY ให้เป็นประเภท export HTTP_PROXY=hostname:port รองรับ HTTPS_PROXY ด้วย

ตามค่าเริ่มต้น dx-download-agent จะใช้ใบรับรองที่ติดตั้งบนระบบเพื่อสร้างการเชื่อมต่อที่ปลอดภัย หากระบบของคุณต้องการใบรับรอง TLS เพิ่มเติม และ dx-download-agent ไม่ได้ใช้ใบรับรองที่ติดตั้งบนระบบของคุณ มีสองตัวเลือกตามลำดับที่ต้องการ ขั้นแรก ให้ตั้งค่าตัวแปรสภาพแวดล้อม DX_TLS_CERTIFICATE_FILE เป็นเส้นทางของไฟล์ใบรับรอง TLS ที่เข้ารหัส PEM ที่องค์กรแม่ของคุณต้องการ วิธีสุดท้าย คุณสามารถเชื่อมต่อแบบไม่ปลอดภัยได้โดยหลีกเลี่ยงการตรวจสอบใบรับรองทั้งหมดพร้อมกันโดยตั้งค่า DX_TLS_SKIP_VERIFY=true ใช้สิ่งนี้เพื่อการทดสอบเท่านั้น

การสร้างและการกรองไฟล์รายการ

เพื่อความสะดวก ไฟล์ create_manifest.py ในไดเร็กทอรี scripts/ เป็นวิธีหนึ่งในการสร้างไฟล์ manifest สำหรับเอเจนต์การดาวน์โหลด สคริปต์นี้กำหนดให้ติดตั้ง dx-toolkit บนระบบของคุณและคุณต้องลงชื่อเข้าใช้แพลตฟอร์ม DNAnexus ตัวอย่างการใช้งาน:

 python3 create_manifest.py "โครงการ: / โฟลเดอร์" --recursive --output_file "myfiles.manifest.json.bz2"

ที่นี่ รายการจะถูกสร้างขึ้นสำหรับไฟล์ ทั้งหมด แบบวนซ้ำภายใต้ชื่อโปรเจ็กต์ Project และในโฟลเดอร์ Folder

รายการสามารถกรองได้ในภายหลังโดยใช้สคริปต์ filter_manifest.py ตัวอย่างเช่น หากคุณต้องการบันทึกไฟล์ในโฟลเดอร์ใดโฟลเดอร์หนึ่ง (เช่น Folder ) โดยมี testcall อยู่ในนั้น (เช่น /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ) คุณสามารถเรียกใช้คำสั่ง:

 $ python3 filter_manifest.py manifest.json.bz2 '^/Folder.*testcall.*'

โดยที่อาร์กิวเมนต์ที่สองที่กำหนดให้กับสคริปต์คือนิพจน์ทั่วไปบนเส้นทางทั้งหมด (โฟลเดอร์ + ชื่อไฟล์)

การแยกไฟล์รายการ

ในบางกรณี อาจเป็นที่พึงปรารถนาที่จะแบ่งไฟล์ Manifest การดาวน์โหลดออกเป็นไฟล์ Manifest หลายไฟล์เพื่อวัตถุประสงค์ในการทดสอบ หรือเพื่อจัดการการดาวน์โหลดชุดข้อมูลทั้งหมดหลายครั้งในสภาพแวดล้อมที่แตกต่างกัน ในการแยกไฟล์ เรามียูทิลิตี Python แบบธรรมดาที่ไม่ต้องใช้แพ็คเกจเพิ่มเติมในไดเร็กทอรี scripts/ ตัวอย่างเช่น ดำเนินการคำสั่ง:

python3 scripts/split_manifest.py manifest.json.bz2 -n 100

จะสร้างไฟล์รายการซึ่งแต่ละไฟล์มี 100 ไฟล์ต่อโครงการ ตัวอย่างเช่น หากมีไฟล์ทั้งหมด 300 ไฟล์ใน manifest.json.bz2 เอาต์พุตของคำสั่งนี้จะสร้างไฟล์สามไฟล์ชื่อ: manifest_001.json.bz2 , manifest_002.json.bz2 และ manifest_003.json.bz2 แต่ละไฟล์เหล่านี้สามารถใช้งานแยกกันกับเอเจนต์การดาวน์โหลดได้

สภาพแวดล้อมการพัฒนา

พื้นที่เก็บข้อมูลนี้สามารถใช้เป็นโมดูล Go ได้โดยตรงเช่นกัน ในไดเร็กทอรี cmd/dx-download-agent ไฟล์ dx-download-agent.go เป็นตัวอย่างของวิธีการใช้งาน

สำหรับการพัฒนาและการทดลองกับแหล่งที่มาภายในสภาพแวดล้อม Docker ที่แยกออกมา Dockerfile ในพื้นที่เก็บข้อมูลนี้อาจเป็นการเริ่มต้นที่ดี

การย้ายไฟล์ที่ดาวน์โหลด

หลังจากดาวน์โหลดสำเร็จ (และเลือกตรวจสอบภายหลังการดาวน์โหลด) การย้ายไฟล์ไปยังตำแหน่งที่คุณต้องการน่าจะปลอดภัย

คำเตือน: โดยทั่วไป เราไม่แนะนำให้ย้ายไฟล์ในระหว่างการดาวน์โหลด แต่การย้ายไฟล์เหล่านั้นอาจปลอดภัยในบางกรณี ตัวแทนการดาวน์โหลดทำงานโดยรักษาฐานข้อมูลขนาดเล็กของส่วนต่างๆ ของไฟล์ที่มีและยังไม่ได้ดาวน์โหลด ดังนั้นนั่นคือสิ่งที่ โดยหลักแล้วจะดำเนินการจาก ซึ่งหมายความว่าแม้ว่าคุณจะย้ายไฟล์ แต่ตัวแทนการดาวน์โหลดจะไม่เข้าใจจนกว่าคุณจะเรียกใช้คำสั่งย่อย inspect ที่ดำเนินการตรวจสอบความสมบูรณ์ของไฟล์บนดิสก์หลังการดาวน์โหลด คำสั่งตรวจสอบจะสังเกตเห็นว่าไฟล์หายไป ให้อัพเดตฐานข้อมูล และเมื่อคุณออกคำสั่งดาวน์โหลดใหม่ จะพยายามดาวน์โหลดอีกครั้ง ดังนั้น หากคุณย้ายไฟล์ที่เสร็จสมบูรณ์และไม่รันคำสั่งย่อย inspect เอเจนต์การดาวน์โหลดควรดำเนินการต่อจากที่ค้างไว้ ดังที่กล่าวไปแล้ว การย้ายไฟล์อาจเกิดอันตรายได้หากการดาวน์โหลดไฟล์ยังไม่เสร็จสิ้น ในกรณีนั้น คุณจะย้ายไฟล์ที่ไม่สมบูรณ์

หมายเหตุเพิ่มเติม

• สามารถดาวน์โหลดได้เฉพาะอ็อบเจ็กต์ของไฟล์คลาสเท่านั้น