dxda
0.6.2
Инструмент CLI для управления загрузкой большого количества файлов с DNAnexus.
ПРИМЕЧАНИЕ. Это ранняя версия этого инструмента, которая проходит тестирование в различных условиях. Пожалуйста, свяжитесь с DNAnexus, если вы хотите узнать, подходит ли этот инструмент для вашего приложения.
Чтобы начать работу с dx-download-agent , загрузите последнюю предварительно скомпилированную двоичную версию со страницы выпуска. Агент загрузки принимает два файла:
manifest_file : файл манифеста JSON, сжатый BZ2, который описывает, как минимум, следующую информацию для загрузки, например:
{ "проект-АААА": [
{ "id": "file-XXXX", "name": "foo", "folder": "/path/to", "parts": { "1": { "size": 10, "md5": "49302323" }, "2": { "size": 5, "md5": "39239329" }
}
}, "..."
], "project-BBBB": [ "..." ]
}Чтобы начать процесс загрузки, сначала сгенерируйте токен API DNAnexus, действительный в течение периода времени, в течение которого вы планируете загружать файлы. Сохраните его в следующей переменной среды:
экспорт 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)
На экран выводится непрерывный отчет о ходе загрузки. Перед началом передачи данных проверяется наличие достаточного места на диске для всего списка файлов. В противном случае выдается сообщение об ошибке и ничего не загружается. Скорость загрузки отражает не только пропускную способность сети, но и возможности ввода-вывода вашего компьютера.
Журнал загрузок содержит более подробную информацию о загрузке в случае возникновения ошибки. Если ошибка все же произошла, и вы не понимаете, как с ней справиться, свяжитесь с нами по [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
Эта команда выполнит проверку файлов и убедится, что их суммы MD5 соответствуют манифесту. Если файл отсутствует или сумма MD5 не совпадает, агент загрузки сообщит о затронутых файлах, и вы сможете снова запустить dx-download-agent download чтобы повторно загрузить затронутые файлы.
-num_threads (целое число): максимальное количество одновременных потоков, которые можно использовать при загрузке или проверке файлов.
Например, команда
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
создаст рабочий пул из 20 потоков, которые будут параллельно загружать части файлов. Максимум 20 рабочих будут выполнять загрузку в любое время. Ограничением скорости загрузки можно в некоторой степени управлять, изменяя это число.
Информация о том, какие части были загружены, хранится в файле базы данных sqlite3, который содержит информацию, аналогичную той, что содержится в формате файла JSON, плюс дополнительное поле bytes_fetched .
Имя таблицы: manifest_stats
Поля (все поля являются строками, если не указано иное)
file_id : идентификатор файла для части файла
project : идентификатор проекта для части файла
name : имя файла
folder : папка, содержащая файл на DNAnexus.
part_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, мы предоставляем также 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 — это токен для доступа к нашей платформе (см. Быстрый старт).
Чтобы направить 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/ является одним из способов создания файлов манифеста для агента загрузки. Для этого сценария требуется, чтобы в вашей системе был установлен 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 манифест.json.bz2 '^/Folder.*testcall.*'
где второй аргумент, передаваемый скрипту, представляет собой регулярное выражение по всему пути (папка + имя файла).
В некоторых случаях может быть желательно разделить манифест загрузки на несколько файлов манифеста в целях тестирования или для управления несколькими загрузками всего набора данных в разных средах. Чтобы разделить файл, мы предоставляем простую утилиту Python, которая не требует дополнительных пакетов в каталоге scripts/ . Например, выполнив команду:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
создаст файлы манифеста, каждый из которых содержит по 100 файлов на проект. Например, если в файле Manifest.json.bz2 всего 300 файлов, в результате выполнения этой команды будут созданы три файла с именами: manifest_001.json.bz2 , manifest_002.json.bz2 и manifest_003.json.bz2 . Каждый из этих файлов можно использовать независимо с агентом загрузки.
Этот репозиторий также можно использовать непосредственно как модуль Go. В каталоге cmd/dx-download-agent файл dx-download-agent.go является примером того, как его можно использовать.
Для разработки и экспериментирования с исходным кодом в изолированной среде Docker хорошим началом может стать файл Dockerfile в этом репозитории.
После успешной загрузки (и, при необходимости, проверки после загрузки) можно безопасно переместить файлы в нужное место.
ВНИМАНИЕ: В целом мы советуем не перемещать файлы во время загрузки, но в некоторых особых случаях их перемещение может быть безопасным. Агент загрузки работает, поддерживая облегченную базу данных о том, какие части файлов были загружены, а какие не были загружены. в основном он работает за счет. Это означает, что даже если вы переместите файлы, агент загрузки не заметит этого, пока вы не запустите подкоманду inspect , которая выполняет проверку целостности файлов на диске после загрузки. Команда проверки заметит отсутствие файлов, обновит базу данных и при повторном вводе команды загрузки попытается загрузить их еще раз. Таким образом, если вы переместите завершенные файлы и не запустите подкоманду проверки, агент загрузки должен продолжить работу с того места, где он остановился. При этом существует опасность перемещения файлов, если загрузка файла еще не завершена. В этом случае вы переместите неполный файл.
Загружать можно только объекты класса File.
