Para enviar dados ao Instituto Nacional de Arquivos de Dados de Saúde Mental (NDA), os usuários devem validar seus dados para garantir que estejam em conformidade com o formato exigido. Isso é feito usando a ferramenta de validação e upload de NDA. Além disso, os usuários também podem empacotar e baixar dados do NDA. Se os dados associados forem baixados do S3, serão necessários tokens federados temporários da AWS. Um pacote Python e clientes de linha de comando foram desenvolvidos para permitir que os usuários validem, empacotem, enviem e/ou baixem dados programaticamente. Serviços da web de validação, pacote de envio e envio de dados.
O usuário precisará de uma distribuição Python para usar o cliente. Execute o seguinte em um terminal/prompt de comando para determinar se o Python já está instalado:
python3 --version
Notas:
Se o Python já estiver instalado, os usuários deverão ver as informações da versão. Caso contrário, você precisará baixá-lo e instalá-lo em Python.org.
O usuário pode precisar de direitos administrativos, privilégios de root ou sudo para instalar uma distribuição Python.
Python pode estar instalado, mas não disponível no caminho do sistema. Consulte a documentação de instalação e uso do Python: Python3
Desde o Python 3.4, o pip é incluído por padrão no binário do Python. Você pode verificar a versão com:
pip3 --version
Se o pip estiver instalado, você deverá ver as informações da versão. Caso contrário, você deve instalar o pip. Primeiro, baixe-o em https://bootstrap.pypa.io/get-pip.py e execute o seguinte para instalar para seu usuário.
python3 get-pip.py --user
Notas:
O Pip pode estar instalado, mas não disponível no caminho do sistema. Consulte a documentação de instalação e uso do Python.
Estas instruções ajudarão você a configurar para executar o cliente.
Basta digitar o seguinte comando em seu terminal ou prompt de comando para instalar o nda-tools:
pip install nda-tools
Isso instalará automaticamente o pacote nda-tools, incluindo os scripts de linha de comando e os pacotes necessários.
Notas:
Se o nda-tools precisar de permissão especial, tente:
pip install nda-tools --user
Se existirem várias versões de python ou pip na máquina de operação, o prompt de comando não reconhecerá o script nda-tools. Tente o seguinte comando:
python -m NDATools.clientscripts.[NDAtoolcommand]
Se uma versão obsoleta da ferramenta já estiver instalada, ela solicitará que o usuário atualize. Para atualizar, siga o comando prompt.
Embora não seja necessário apenas para validação, se quiser criar um pacote e enviar seus dados ao NDA, você deve ter uma conta ativa conosco. Isso pode ser solicitado no site da NDA. Você pode ler mais sobre o que é necessário para contribuir com dados para o NDA aqui.
Keyring é um pacote Python que aproveita o gerenciador de credenciais do sistema operacional para armazenar e recuperar com segurança as credenciais do usuário.
Para usuários de qualquer sistema operacional, a senha pode ser atualizada com:
keyring.set_password('nda-tools', USERNAME, NEW_PASSWORD)
Usuários de Mac e Windows podem usar Keychain e Credentials Manager, respectivamente, para atualizar suas senhas.
Para atualizar sua senha com chaveiro, execute:
keyring.set_password('nda-tools', 'YOUR_USERNAME', 'NEW_PASSWORD') ,
substituindo YOUR_USERNAME e NEW_PASSWORD pelo seu nome de usuário e nova senha do NDA. Você pode ler mais na documentação do chaveiro.
Se você não tiver nenhuma entrada armazenada por meio do chaveiro, será solicitado que você insira a senha. Se a autenticação for bem-sucedida, o nda-tools armazenará sua senha por meio de um chaveiro. O uso subsequente do nda-tools recuperará a senha de forma automática e segura do chaveiro.
Os usuários do Linux podem precisar instalar uma implementação de back-end do chaveiro, pois podem não ter um gerenciador de credenciais nativo, como aqueles incluídos nos sistemas operacionais Mac e Windows. Se o backend do chaveiro estiver faltando, o nda-tools imprimirá a seguinte mensagem:
If there is no backend set up for keyring, you may try pip install secretstorage --upgrade keyrings.alt
Para usuários do Ubuntu,
apt-get install -y gnome-keyring
Observe que se você encontrar erros de SSL ao executar o cliente, pode ser necessário executar novamente a instalação de solicitações do pip, com pip install pip install requests[secure] que instalará alguns pacotes adicionais com mais suporte para conexões SSL.
Para visualizar as opções disponíveis para o cliente Python da Validation Tool, insira o seguinte comando:
vtcmd -h
ou para visualizar as opções disponíveis para o cliente Download Python, digite:
downloadcmd -h
Se suas entradas de linha de comando tiverem caracteres especiais (isto é, senhas) ou espaços (isto é, em diretórios/nomes de arquivos), você pode precisar colocá-los entre aspas.
Se você estiver usando Windows, use aspas duplas: " "
Se você estiver usando Mac OSX ou Linux, use aspas simples: ' '
Na primeira execução, o cliente solicitará que você insira seu nome de usuário e senha, que serão armazenados no gerenciador de credenciais do seu sistema operacional. Você pode voltar e editar suas credenciais a qualquer momento.
O arquivo ~.NDAToolssettings.cfg fornecido com o cliente contém opções configuráveis para endpoints, arquivos e informações do usuário.
Normalmente, você não precisará alterar as entradas na seção ‘Endpoints’; no entanto, você pode querer modificar as seções 'Arquivos' e 'Usuário' com locais preferenciais para resultados de validação, login de usuário e informações de credenciais da AWS.
Embora os argumentos não sejam posicionais, o primeiro argumento deve ser a lista de arquivos a serem validados.
vtcmd -l "Users/[youruser]/Documents/MultipleDataTypes" "Users/[youruser]/Documents/MultipleDataTypes/Stage_Testing_BigFiles_genomics_sample03.csv"
A lista de arquivos não possui opção de linha de comando, portanto pode ser interpretada como parte de um argumento anterior.
Por exemplo, não há como diferenciar se o arquivo csv faz parte do argumento -l ou de um segundo argumento:
É necessário que você conheça o caminho completo dos arquivos csv que serão validados. Além disso, se seus dados incluírem manifestos e/ou arquivos associados (ou seja, arquivos genômicos, arquivos de imagem, etc.), você também deverá saber o caminho completo para esses arquivos, que deve ser inserido como um argumento opcional de linha de comando. Caso contrário, o cliente solicitará que você insira uma lista de diretórios onde quaisquer arquivos adicionais estão armazenados. Você também pode listar um bucket, um prefixo opcional e suas credenciais da AWS se os arquivos associados estiverem na AWS.
Observação: ao listar o diretório dos arquivos associados, inclua a pasta até , mas não incluindo, o nome do arquivo listado no arquivo csv.
Se o nome do arquivo associado estiver em Users/[youruser]/Documents/MultipleDataTypes/data/1G_file.fastq e estiver listado em seu arquivo csv como:
dados/1G_file.fastq
então o diretório que você irá inserir é:
Usuários/[seuusuário]/Documentos/MultipleDataTypes
Você não deve incluir a pasta 'data/' como parte do nome do diretório.
Verifique todas as propriedades dos arquivos e certifique-se de que o usuário tenha todas as permissões permitidas.
Para iniciar a validação, você deve inserir uma lista de arquivos (ou um caminho de arquivo se não estiver no diretório atual), separados por um espaço:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv
Se seus dados incluírem arquivos de manifesto, você deverá inserir os diretórios onde os arquivos de manifesto estão localizados, separados por um espaço:
vtcmd submission_data/sample_imagingcollection01.csv -m submission_data/Manifests
Caso existam arquivos associados, insira os diretórios onde se encontram, separados por um espaço:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l MultipleDataTypes testdata/with_associated_files
Se os arquivos estiverem localizados em algum lugar diferente do diretório de trabalho atual, você deverá inserir o caminho completo para os arquivos:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l Users/[youruser]/Downloads/SubmissionData testdata/with_associated_files
Se os arquivos associados estiverem no S3, você deverá incluir o nome do bucket, a chave de acesso e a chave secreta.
O acesso e a chave secreta também podem ser armazenados no arquivo settings.cfg.
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -s3 my_bucket -ak XXXXXXXXXXXXXX -sk XXXXXXXXXXXXXX
Observação: você também pode fazer upload de arquivos associados salvos localmente e no s3. Apenas certifique-se de incluir o diretório onde os arquivos locais são salvos (-l caminho/para/local/associado/arquivos)
Para criar um pacote, digite “-b” no final do argumento da linha de comando. Você também pode inserir seu nome de usuário, credenciais da AWS, ID da coleção e o título e a descrição do seu envio, ou pode inserir essas informações posteriormente, quando solicitado pelo cliente. O cliente não começará a construir o pacote de envio até:
Todos os seus arquivos são validados
Todos os arquivos associados foram localizados na sua unidade local ou no S3
Assim que o envio e o upload do pacote forem concluídos, você receberá um e-mail da NDA em sua caixa de entrada confirmando que seu envio foi bem-sucedido. Uma versão local do pacote será salva automaticamente na pasta ~nda-toolsvtcmdsubmission_package e pode ser encontrada na guia de envio de coleção no site do NDA.
Uma verificação de controle de qualidade é realizada em todos os dados após terem sido submetidos ao NDA para detectar inconsistências em pontos de dados, incluindo sexo, sujeito, idade da entrevista e data da entrevista. Caso seja encontrado algum problema com os dados, será enviado um e-mail aos usuários que criaram o envio junto com um relatório dos erros encontrados pelo NDA.
Para corrigir os dados do NDA para o seu envio, você precisa substituir todos os arquivos csv que continham erros no seu envio original. Para fazer isso você deve:
Recupere os arquivos csv que foram usados para criar o envio original e que contêm dados que precisam ser corrigidos. Isso inclui todos os arquivos csv onde os dados precisam ser adicionados, removidos ou atualizados.
Corrija os arquivos adicionando, removendo ou atualizando informações conforme necessário.
Execute o vtcmd com o argumento de linha de comando -rs. Especifique o valor do envio para o qual você precisa corrigir os dados. Em seguida, liste todos os arquivos csv nos quais você fez correções. Se houve um arquivo csv do envio original que não continha nenhuma alteração, não é necessário fornecer o arquivo como argumento neste momento.
Por exemplo, se o envio original com id 123456 consistia em arquivo1.csv, arquivo2.csv e arquivo3.csv, e correções precisassem ser feitas em arquivo1.csv e arquivo2.csv, o comando para corrigir erros de qa será semelhante a:
vtcmd -b -rs 123456 corrected-file1.csv corrected-file2.csv
Observe que file3.csv foi excluído do comando porque nenhuma alteração precisou ser feita nesse arquivo específico.
Observe que este comando deve ser executado uma vez para um envio e deve incluir todos os arquivos que contêm correções nos dados . ou seja, não execute o vtcmd uma vez para o arquivo1.csv corrigido e outra vez para o arquivo2.csv corrigido. Se você acidentalmente omitir arquivos contendo alterações necessárias ao executar o comando, entre em contato com o HelpDesk em [email protected].
Observe também que os arquivos csv devem conter todos os dados enviados originalmente. ou seja , se um csv originalmente tinha 800 linhas e apenas 3 linhas precisavam ser alteradas, todas as 800 linhas deveriam estar presentes no csv ao executar o vtcmd , não apenas as 3 linhas que contêm alterações. Quaisquer dados deixados de fora do csv serão refletidos nos números esperados de dados para a coleção.
O script não carregará nenhum arquivo associado que tenha sido carregado durante o envio original. Só será necessário fazer upload dos arquivos associados se eles aparecerem em arquivos csv corrigidos, mas não em nenhum dos arquivos csv do envio original. Isso economiza tempo durante os envios genômicos e de imagens, onde os arquivos associados podem levar dias para serem carregados.
Para baixar dados, você deve usar o comando downloadcmd. Isso fornece várias opções para baixar os dados empacotados do NDA ou um subconjunto dos dados. Todos os arquivos são baixados automaticamente para a pasta ~nda-toolsdownloadcmdpackages , mas você pode alterar isso indicando um novo diretório na linha de comando para salvar os arquivos. Atenção: o limite máximo de transferência de dados é de 20 TB por mês.
Os usuários podem entrar em contato com o Help Desk da NDA em [email protected] e solicitar que seu limite de download seja estendido [temporariamente].
Todos os dados empacotados podem ser baixados passando o ID do pacote:
downloadcmd -dp <packageID>
Observação: NÃO baixará arquivos associados , a menos que você crie seu pacote NDA com arquivos associados . As etapas para baixar os arquivos associados estão abaixo.
O comando downloadcmd possui duas opções para baixar dados dentro de arquivos .txt. Se você baixou seu pacote NDA, encontrará arquivos .txt de metadados, muitos dos quais representam medidas de dados. Genômica, imagens e outros dados associados serão listados nesses arquivos .txt como links s3. Se desejar baixar todos os links s3 em seu arquivo .txt, você pode indicar isso passando o sinalizador -ds.
downloadcmd -dp <packageID> -ds path/to/data/structure/file/image03.txt
Se quiser baixar seu pacote NDA e todos os dados genômicos, imagens e outros dados associados como uma lista de links s3 armazenados em um arquivo .txt personalizado, você pode fazer isso usando o sinalizador -t.
downloadcmd -dp <packageID> -t path/to/all/s3/txt/file/alls3.txt
O comando downloadcmd pode baixar seu pacote NDA diretamente em seu bucket S3.
downloadcmd -dp <packageID> -s3 <s3 bucket>
Esta é a forma preferida de baixar dados do NDA por dois motivos:
O download para outro bucket S3 é consideravelmente mais rápido porque os dados não saem da AWS.
Ele nos permite baixar uma quantidade ilimitada de dados do NDA diretamente para o seu bucket.
Para que as operações de cópia S3 para S3 sejam bem-sucedidas, o bucket S3 fornecido como argumento do programa deve ser configurado para permitir operações de objeto PUT para arn:aws:sts::618523879050:federated-user/<username> , onde <username> , onde <username> é o seu nome de usuário do NDA.
Para buckets não públicos, isso exigirá uma atualização da política de bucket. A instrução a seguir deve ser adicionada para permitir as permissões necessárias após substituir <your-s3-bucket> pelo nome do bucket:
{
"Sid": "AllowNDAUpload",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:federated-user/<username>"
},
"Action": "s3:PutObject*",
"Resource": "arn:aws:s3:::<your-s3-bucket>/*"
}Pode ser necessário enviar um e-mail ao departamento de TI da sua empresa/instituição para que isso seja adicionado para você.
Observação: se o seu bucket S3 estiver criptografado com uma chave KMS gerenciada pelo cliente, você também precisará atualizar a política da chave usada para criptografar o bucket.
A seguinte declaração deve ser adicionada à política da sua chave:
{
"Sid": "EnableUseForFederatedNDA",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:user/DownloadManager"
},
"Action": ["kms:GenerateDataKey","kms:Decrypt"],
"Resource": "*"
}Se você tiver algum problema com este cliente Python da ferramenta de validação ou quiser fornecer feedback/comentários, envie um email para [email protected].
