Чтобы отправить данные в архивы данных Национального института психического здоровья (NDA), пользователи должны проверить свои данные, чтобы убедиться, что они соответствуют требуемому формату. Это делается с помощью инструмента проверки и загрузки NDA. Кроме того, пользователи также могут упаковывать и загружать данные из NDA. Если связанные данные загружаются из S3, требуются временные федеративные токены AWS. Пакет Python и клиенты командной строки были разработаны, чтобы позволить пользователям программно проверять, упаковывать, отправлять и/или загружать данные. Веб-службы проверки, пакета отправки и отправки данных.
Для использования клиента пользователю понадобится дистрибутив Python. Запустите следующую команду из терминала/командной строки, чтобы определить, установлен ли уже Python:
python3 --version
Примечания:
Если Python уже установлен, пользователи должны увидеть информацию о версии. Если нет, вам нужно будет загрузить и установить его с Python.org.
Для установки дистрибутива Python пользователю могут потребоваться права администратора, root или sudo.
Python может быть установлен, но недоступен по системному пути. Пожалуйста, обратитесь к документации по установке и использованию Python: Python3.
Начиная с Python 3.4, pip по умолчанию включен в двоичный файл Python. Проверить версию можно с помощью:
pip3 --version
Если pip установлен, вы должны увидеть информацию о версии. Если нет, вам следует установить pip. Сначала загрузите его с https://bootstrap.pypa.io/get-pip.py, затем запустите следующую команду, чтобы установить для своего пользователя.
python3 get-pip.py --user
Примечания:
Pip может быть установлен, но недоступен по системному пути. Пожалуйста, обратитесь к документации по установке и использованию Python.
Эти инструкции помогут вам настроить запуск клиента.
Просто введите следующую команду в свой терминал или командную строку, чтобы установить nda-tools:
pip install nda-tools
Это автоматически установит пакет nda-tools, включая сценарии командной строки и необходимые пакеты.
Примечания:
Если для nda-tools требуется специальное разрешение, попробуйте:
pip install nda-tools --user
Если на рабочем компьютере существует несколько версий Python или pip, командная строка не распознает сценарий nda-tools. Вместо этого попробуйте следующую команду:
python -m NDATools.clientscripts.[NDAtoolcommand]
Если устаревшая версия инструмента уже установлена, пользователю будет предложено выполнить обновление. Для обновления следуйте подсказке.
Хотя это и не требуется исключительно для проверки, если вы хотите создать пакет и отправить свои данные в NDA, у вас должна быть активная учетная запись у нас. Это можно запросить на сайте NDA. Подробнее о том, что необходимо для внесения данных в NDA, можно прочитать здесь.
Keyring — это пакет Python, который использует диспетчер учетных данных операционной системы для безопасного хранения и получения учетных данных пользователя.
Для пользователей любой операционной системы пароль можно обновить с помощью:
keyring.set_password('nda-tools', USERNAME, NEW_PASSWORD)
Пользователи Mac и Windows могут использовать Keychain и Credentials Manager соответственно для обновления своих паролей.
Чтобы обновить пароль с помощью брелока, запустите:
keyring.set_password('nda-tools', 'YOUR_USERNAME', 'NEW_PASSWORD') ,
заменив YOUR_USERNAME и NEW_PASSWORD на свое имя пользователя NDA и новый пароль. Вы можете прочитать больше в документации по брелокам.
Если у вас нет записей, сохраненных в связке ключей, вам будет предложено ввести пароль. Если аутентификация прошла успешно, nda-tools сохранит ваш пароль в связке ключей. Последующее использование nda-tools позволит автоматически и безопасно получить пароль из связки ключей.
Пользователям Linux может потребоваться установить серверную реализацию набора ключей, поскольку у них может не быть встроенного менеджера учетных данных, например, включенного в операционные системы Mac и Windows. Если серверная часть связки ключей отсутствует, nda-tools выведет следующее сообщение:
If there is no backend set up for keyring, you may try pip install secretstorage --upgrade keyrings.alt
Для пользователей Ubuntu:
apt-get install -y gnome-keyring
Обратите внимание, что если вы столкнулись с ошибками SSL при запуске клиента, вам может потребоваться повторно запустить установку запросов pip с помощью pip install pip install requests[secure] , который установит некоторые дополнительные пакеты с большей поддержкой SSL-соединений.
Чтобы просмотреть параметры, доступные для клиента Python средства проверки, введите следующую команду:
vtcmd -h
или чтобы просмотреть параметры, доступные для клиента Download Python, введите:
downloadcmd -h
Если входные данные командной строки содержат специальные символы (например, пароли) или пробелы (например, в именах каталогов/файлов), вам может потребоваться заключить их в кавычки.
Если вы используете Windows, используйте двойные кавычки: " "
Если вы используете Mac OSX или Linux, используйте одинарные кавычки: ' '
При первом запуске клиент предложит вам ввести имя пользователя и пароль, которые он сохранит в диспетчере учетных данных вашей операционной системы. Вы можете вернуться и изменить свои учетные данные в любое время.
Файл ~.NDAToolssettings.cfg, поставляемый с клиентом, содержит настраиваемые параметры для конечных точек, файлов и информации о пользователе.
Обычно вам не нужно изменять записи в разделе «Конечные точки»; однако вы можете изменить разделы «Файлы» и «Пользователь», указав предпочтительные местоположения для результатов проверки, входа пользователя и информации об учетных данных AWS.
Хотя аргументы не являются позиционными, первым аргументом должен быть список файлов для проверки.
vtcmd -l "Users/[youruser]/Documents/MultipleDataTypes" "Users/[youruser]/Documents/MultipleDataTypes/Stage_Testing_BigFiles_genomics_sample03.csv"
В списке файлов нет переключателя командной строки, поэтому его можно интерпретировать как часть предыдущего аргумента.
Например, невозможно отличить, является ли файл csv частью аргумента -l или вторым аргументом:
Необходимо знать полный путь к файлам CSV, которые будут проверены. Более того, если ваши данные включают манифесты и/или связанные файлы (например, файлы геномики, файлы изображений и т. д.), вы также должны знать полный путь к этим файлам, который следует ввести в качестве необязательного аргумента командной строки. В противном случае клиент предложит вам ввести список каталогов, в которых хранятся дополнительные файлы. Вы также можете указать сегмент, необязательный префикс и свои учетные данные AWS, если связанные файлы находятся в AWS.
Обратите внимание: при указании каталога для связанных файлов указывайте папку до имени файла, указанного в CSV-файле, но не включая его .
Если имя связанного файла находится в Users/[youruser]/Documents/MultipleDataTypes/data/1G_file.fastq и указано в вашем CSV-файле как:
данные/1G_file.fastq
тогда каталог, в который вы войдете:
Пользователи/[вашпользователь]/Документы/MultipleDataTypes
Не следует включать папку data/ в имя каталога.
Проверьте свойства всех файлов и убедитесь, что у пользователя есть все разрешения.
Чтобы начать проверку, необходимо ввести список файлов (или путь к файлу, если он не находится в текущем каталоге), разделенный пробелом:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv
Если ваши данные включают файлы манифеста, вам необходимо указать каталоги, в которых расположены файлы манифеста, через пробел:
vtcmd submission_data/sample_imagingcollection01.csv -m submission_data/Manifests
Если есть связанные файлы, укажите каталоги, в которых они находятся, через пробел:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l MultipleDataTypes testdata/with_associated_files
Если файлы расположены где-то кроме текущего рабочего каталога, то необходимо ввести полный путь к файлам:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l Users/[youruser]/Downloads/SubmissionData testdata/with_associated_files
Если связанные файлы находятся в S3, необходимо указать имя корзины, ключ доступа и секретный ключ.
Доступ и секретный ключ также можно сохранить в файле settings.cfg.
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -s3 my_bucket -ak XXXXXXXXXXXXXX -sk XXXXXXXXXXXXXX
Примечание. Вы также можете загрузить связанные файлы, сохраненные локально и в s3. Просто не забудьте указать каталог, в котором сохраняются локальные файлы (-l путь/к/локальным/связанным/файлам).
Чтобы создать пакет, введите «-b» в конце аргумента командной строки. Вы также можете ввести свое имя пользователя, учетные данные AWS, идентификатор коллекции, а также название и описание вашей заявки или можете ввести эту информацию позже, когда это будет предложено клиентом. Клиент не начнет создавать пакет для отправки до тех пор, пока:
Все ваши файлы проверены
Все связанные файлы расположены на вашем локальном диске или в S3.
Как только отправка и загрузка пакета будут завершены, вы получите электронное письмо от NDA, подтверждающее, что ваша отправка прошла успешно. Локальная версия пакета будет автоматически сохранена в папке ~nda-toolsvtcmdsubmission_package , и ее можно будет найти на вкладке отправки коллекции на сайте NDA.
Проверка качества выполняется для всех данных после того, как они были отправлены в NDA, на предмет несоответствий в таких точках данных, как пол, предмет, возраст интервью и дата интервью. Если с данными будут обнаружены какие-либо проблемы, пользователям, создавшим отправку, будет отправлено электронное письмо вместе с отчетом об ошибках, обнаруженных NDA.
Чтобы исправить данные в Соглашении о неразглашении для вашей отправки, вам необходимо заменить все файлы csv, содержащие ошибки в вашей исходной отправке. Для этого вам необходимо:
Получите файлы CSV, которые использовались для создания исходной отправки и содержат данные, которые необходимо исправить. Сюда входят все файлы CSV, данные в которых необходимо добавить, удалить или обновить.
Исправьте файлы, добавив, удалив или обновив информацию по мере необходимости.
Запустите vtcmd с аргументом командной строки -rs. Укажите стоимость отправки, для которой необходимо исправить данные. Затем перечислите все файлы CSV, в которые вы внесли исправления. Если в исходной отправке был файл CSV, который не содержал никаких изменений, на данном этапе нет необходимости предоставлять этот файл в качестве аргумента.
Например, если исходная отправка с идентификатором 123456 состояла из файлов file1.csv, file2.csv и file3.csv и необходимо внести исправления в file1.csv и file2.csv, команда для исправления ошибок контроля качества будет выглядеть так:
vtcmd -b -rs 123456 corrected-file1.csv corrected-file2.csv
Обратите внимание, что файл file3.csv исключен из команды, поскольку в этот конкретный файл не требуется вносить никаких изменений.
Обратите внимание, что эту команду следует выполнить один раз при отправке и она должна включать все файлы, содержащие исправления данных . т.е. не запускайте vtcmd один раз для исправленного файла1.csv и еще раз для исправленного файла2.csv. Если вы случайно пропустили файлы, содержащие необходимые изменения, при выполнении команды, обратитесь в службу поддержки по адресу [email protected].
Также обратите внимание, что файлы CSV должны содержать все данные, которые были отправлены изначально. т.е. если CSV изначально имел 800 строк и нужно было изменить только 3 строки, все 800 строк должны присутствовать в CSV при запуске vtcmd , а не только 3 строки, содержащие изменения. Любые данные, не включенные в CSV, будут отражены в ожидаемых числах для коллекции.
Скрипт не будет загружать никакие связанные файлы, которые были загружены во время исходной отправки. Загружать связанные файлы необходимо будет только в том случае, если они присутствуют в исправленных файлах CSV, но не присутствуют ни в одном из файлов CSV из исходной отправки. Это экономит время при отправке геномных изображений и изображений, поскольку загрузка связанных файлов может занять несколько дней.
Для загрузки данных следует использовать команду downloadcmd. Это предоставляет несколько вариантов загрузки упакованных данных NDA или подмножества данных. Все файлы автоматически загружаются в папку ~nda-toolsdownloadcmdpackages , но вы можете изменить это, указав в командной строке новый каталог для сохранения файлов. Обратите внимание: максимальный лимит передачи данных — 20 ТБ в месяц.
Пользователи могут обратиться в службу поддержки NDA по адресу [email protected] и попросить [временно] продлить порог загрузки.
Все упакованные данные можно скачать, передав идентификатор пакета:
downloadcmd -dp <packageID>
Примечание. Он НЕ будет загружать связанные файлы , если вы не создали пакет NDA со связанными файлами . Шаги по загрузке связанных файлов приведены ниже.
Команда downloadcmd имеет два варианта загрузки данных из файлов .txt. Если вы загрузили пакет соглашения о неразглашении, вы найдете файлы метаданных .txt, многие из которых представляют собой показатели данных. Геномика, визуализация и другие связанные данные будут перечислены в этих файлах .txt в виде ссылок s3. Если вы хотите загрузить все ссылки s3 в вашем .txt-файле, вы можете указать это, передав флаг -ds.
downloadcmd -dp <packageID> -ds path/to/data/structure/file/image03.txt
Если вы хотите загрузить пакет NDA, а также все геномные, визуальные и другие связанные данные в виде списка ссылок s3, хранящегося в специальном txt-файле, вы можете сделать это, используя флаг -t.
downloadcmd -dp <packageID> -t path/to/all/s3/txt/file/alls3.txt
Команда downloadcmd может загрузить пакет NDA напрямую в корзину S3.
downloadcmd -dp <packageID> -s3 <s3 bucket>
Это предпочтительный способ загрузки данных из NDA по двум причинам:
Загрузка в другую корзину S3 происходит значительно быстрее, поскольку данные не покидают AWS.
Это позволяет нам загружать неограниченное количество данных из NDA напрямую в вашу корзину.
Чтобы операции копирования S3 в S3 были успешными, корзина S3, указанная в качестве аргумента программы, должна быть настроена на разрешение операций с объектами PUT для arn:aws:sts::618523879050:federated-user/<username> , где <username> это ваше имя пользователя NDA.
Для закрытых сегментов это потребует обновления политики сегментов. Необходимо добавить следующий оператор, чтобы предоставить необходимые разрешения после замены <your-s3-bucket> именем корзины:
{
"Sid": "AllowNDAUpload",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:federated-user/<username>"
},
"Action": "s3:PutObject*",
"Resource": "arn:aws:s3:::<your-s3-bucket>/*"
}Возможно, вам придется отправить электронное письмо в ИТ-отдел вашей компании/учреждения, чтобы добавить это для вас.
Примечание. Если ваша корзина S3 зашифрована с помощью ключа KMS, управляемого клиентом, вам также потребуется обновить политику ключа, который используется для шифрования корзины.
В политику вашего ключа следует добавить следующее утверждение:
{
"Sid": "EnableUseForFederatedNDA",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:user/DownloadManager"
},
"Action": ["kms:GenerateDataKey","kms:Decrypt"],
"Resource": "*"
}Если у вас возникли проблемы с этим клиентом Python для средства проверки или вы хотите оставить отзыв/комментарий, напишите нам по адресу [email protected].
